Setup

Everything you need before deploying to Railway: the alchemy package, a Railway workspace, and an account API token stored in a profile.

Prerequisites

• Bun (recommended) 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:

1. Open Account Settings → Tokens.
2. Create an account token (or a workspace token) with permission to manage projects and services.
3. 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

bun

mkdir my-app && cd my-app && bun init -y

npm

mkdir my-app && cd my-app && npm init -y

pnpm

mkdir my-app && cd my-app && pnpm init

yarn

mkdir my-app && cd my-app && yarn init -y

Install

bun

bun add "alchemy@next" "effect@rc" "@effect/platform-bun@rc" "@effect/platform-node@rc"

npm

npm install "alchemy@next" "effect@rc" "@effect/platform-bun@rc" "@effect/platform-node@rc"

pnpm

pnpm add "alchemy@next" "effect@rc" "@effect/platform-bun@rc" "@effect/platform-node@rc"

yarn

yarn add "alchemy@next" "effect@rc" "@effect/platform-bun@rc" "@effect/platform-node@rc"

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 two options:

• API Token — paste the token you generated above. It’s saved under ~/.alchemy/credentials/<profile>/.
• Environment Variables — reads RAILWAY_API_TOKEN from the environment on every run (plus an optional RAILWAY_API_URL). This is the method for CI — when alchemy detects CI=true it 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):

alchemy login --configure
alchemy login --profile prod --configure

Inspect what’s stored (secrets are redacted):

alchemy profile show

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() or AWS.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.