import PackageManagers from "../../../components/PackageManagers.astro"; export const pkgs = `alchemy@latest @alchemy.run/railway@latest effect @effect/platform-bun @effect/platform-node`; Everything you need before deploying to Railway: the alchemy package, a Railway workspace, and an account API token stored in a profile.
Prerequisites
- Bun or Node.js 22+
- A Railway account
- Docker for Effect-native
Services (Alchemy builds and pushes an
image). Image-based Services (
hashicorp/http-echo) do not need it.
Create a Railway workspace
Sign in at railway.com/dashboard. A
personal workspace is created with the account. Tokens are scoped to
the account or a workspace — Alchemy uses
me.workspace ?? me.workspaces[0] when you omit workspaceId on a
Project.
Workspace is not an Alchemy resource. Pin a workspace with
workspaceId on Railway.Project.
Generate an API token
Alchemy needs an account or workspace token
(RAILWAY_API_TOKEN). Project tokens cannot reach workspace-wide
operations.
In the dashboard:
- Open Account Settings → Tokens.
- Create an account token (or a workspace token) with permission to manage projects and services.
- Copy the token — Railway shows it only once.
The official environment variable is RAILWAY_API_TOKEN. An optional
RAILWAY_API_URL overrides the GraphQL host (default
https://backboard.railway.com).
Create a project directory
Install
Connect alchemy to Railway
There is no separate credentials step. The first time you run
alchemy deploy (or plan, dev, destroy) on a stack that uses
Railway.providers(), alchemy walks you through an interactive login
with three options:
- OAuth — opens
railway.com/cli-loginand pairs the CLI with your account. No pre-existing token needed. - API Token — paste the token you generated above. It's saved
under
~/.alchemy/credentials/<profile>/. - Environment Variables — reads
RAILWAY_API_TOKENfrom the environment on every run (plus an optionalRAILWAY_API_URL). In CI (CI=true) alchemy skips the prompt and uses the environment automatically.
Either choice is saved to your default
profile and reused on every subsequent
command.
To re-run the setup later (e.g. to rotate the token, or configure a
separate prod profile):
# Re-run the interactive setup (e.g. to rotate the token)
alchemy profile edit --reconfigure Railway
# Or connect Railway in a separate `prod` profile
alchemy profile create prod
alchemy profile edit --profile prod --add Railway
# Non-interactive (scripts, agents)
alchemy profile edit --add Railway --method stored --set token=env:RAILWAY_API_TOKEN Inspect what's stored (secrets are redacted):
alchemy profile show :::note[Effect-native Services]
Railway.Service with main bundles
your Effect program, generates a Dockerfile, and uploads the
context. Railway builds the image — no GHCR, no Docker daemon on
the machine that runs alchemy deploy. Image-based Services
(image: "hashicorp/http-echo") skip the build and pull a public
tag.
:::
State storage
Railway has no object-storage state backend of its own, so pick one of:
Alchemy.localState()— state on disk under.alchemy/next to your code. Zero setup; right for solo projects and trying things out.- A cloud state store — if you also use Cloudflare or AWS, pass
Cloudflare.state()orAWS.state()so state is shared with your team and CI. See State Store.
Next steps
- Tutorial part 1 — deploy your first Project.
- Railway overview — the map of resources and guides.