A Railway.Function is an Effect
program on Railway's canvas Function runtime: a single TypeScript
file on Bun. No GitHub repo. No Docker. No registry. Distinct from
Effect-native Service({ main }),
which uploads a generated Dockerfile. Cap is 96KB once encoded.
Marketplace Templates deploy a
serialized config into a Project. Sandbox
is an ephemeral Linux VM. CloudAgent
is a coding-agent VM.
Declare an Effect-native Function
A Function is a class. Props describe the canvas Function. The Effect is the program that runs in it.
// src/ping.ts
import * as Railway from "@alchemy.run/railway";
import * as Effect from "effect/Effect";
import * as HttpServerResponse from "effect/http/HttpServerResponse";
import { Site } from "./project.ts";
export default class Ping extends Railway.Function<Ping>()(
"Ping",
{
project: Site,
main: import.meta.url,
},
Effect.gen(function* () {
return {
fetch: Effect.succeed(HttpServerResponse.text("ok")),
};
}),
) {} main: import.meta.url is the bundle entrypoint. Alchemy bundles
this file with Rolldown into one JS file and writes it as the
Function's startCommand. Railway does not pull a registry
image.
Schemaless RPC
Return methods next to fetch. Call enableRailwayRpc() in the constructor
(the canvas start command is capped at 96KB, so the dispatcher is
opt-in). Another Function or Service binds the class and calls
them over {name}.railway.internal with a shared token. Public
*.up.railway.app traffic to /__rpc__/* gets 401 even with the
token — this is not a public API.
export default class Query extends Railway.Function<Query>()(
"Query",
{ project: Site, main: import.meta.url },
Effect.gen(function* () {
Railway.enableRailwayRpc();
return {
greet: (name: string) => Effect.succeed(`hello ${name}`),
};
}),
) {} export default class Api extends Railway.Service<Api>()(
"Api",
{ project: Site, main: import.meta.url },
Effect.gen(function* () {
const query = yield* Railway.bindFunction(Query);
return {
fetch: query
.greet("sam")
.pipe(Effect.map((greeting) => HttpServerResponse.text(greeting))),
};
}),
) {} bindService is the same stub for a tagged Service. Calls are
POST http://{dnsName}:{port}/__rpc__/{method} on the private mesh.
Do not send rpcToken to the browser.
Inline source
Pass inline source (or path to a .ts file) instead of main
when the Function is not an Effect class. Alchemy generates a
*.up.railway.app domain unless http: false or a cron schedule is
set.
const site = yield* Railway.Project("Site");
const ping = yield* Railway.Function("Ping", {
project: site,
source: `
Bun.serve({
hostname: "0.0.0.0",
port: Number(process.env.PORT ?? 3000),
fetch() { return new Response("ok"); },
});
`,
}); path is the CLI --path equivalent. The file is read at
plan/reconcile.
const ping = yield* Railway.Function("Ping", {
project: site,
path: "./fn.ts",
}); Cron Function
cronSchedule runs the Function on a cron expression (--cron).
HTTP domains are skipped unless http: true is set explicitly.
const job = yield* Railway.Function("Cleanup", {
project: site,
source: `console.log("tick");`,
cronSchedule: "0 * * * *",
}); Marketplace templates
templateId is a marketplace UUID or code (postgres). Pass a
Project to deploy into it, or omit project and Alchemy creates one.
const site = yield* Railway.Project("Site");
const db = yield* Railway.Template("Postgres", {
templateId: "postgres",
project: site,
}); Sandboxes
An ephemeral Linux VM. Create it, execSandbox commands, snapshot
with checkpoints, destroy it when the task is done. Sandboxes are
Priority Boarding.
const box = yield* Railway.Sandbox("Box", {
environment: site,
idleTimeoutMinutes: 5,
});
yield* Railway.execSandbox({
sandboxId: box.sandboxId,
environmentId: box.environmentId,
command: "echo hello",
}); Cloud agents
A persistent coding-agent VM. Sleep keeps the disk; wake re-runs the
entrypoint. Variables are create-only and may use
Railway.ref.
const agent = yield* Railway.CloudAgent("Coder", {
environment: site,
variables: {
DATABASE_URL: Railway.ref(db, "DATABASE_URL"),
},
}); Where next
Services is the container when you need
Docker (main). Functions stay on the canvas runtime.
The Function,
Template,
Sandbox, and
CloudAgent references list every
prop.