The best way to control Claude Code, Codex and more from any computer or phone
| 1 | --- |
| 2 | title: Setup |
| 3 | description: Create a Railway workspace, generate an account API token, and store it in a profile. |
| 4 | --- |
| 5 | |
| 6 | import PackageManagers from "../../../components/PackageManagers.astro"; |
| 7 | |
| 8 | export const pkgs = `alchemy@latest @alchemy.run/railway@latest effect @effect/platform-bun @effect/platform-node`; |
| 9 | |
| 10 | Everything you need before deploying to Railway: the alchemy package, |
| 11 | a Railway workspace, and an account API token stored in a profile. |
| 12 | |
| 13 | ## Prerequisites |
| 14 | |
| 15 | - [Bun](https://bun.sh) or Node.js 22+ |
| 16 | - A [Railway](https://railway.com) account |
| 17 | - [Docker](https://docs.docker.com/get-docker/) for Effect-native |
| 18 | [Services](/railway/compute/services) (Alchemy builds and pushes an |
| 19 | image). Image-based Services (`hashicorp/http-echo`) do not need it. |
| 20 | |
| 21 | ## Create a Railway workspace |
| 22 | |
| 23 | Sign in at [railway.com/dashboard](https://railway.com/dashboard). A |
| 24 | personal workspace is created with the account. Tokens are scoped to |
| 25 | the account or a workspace — Alchemy uses |
| 26 | `me.workspace ?? me.workspaces[0]` when you omit `workspaceId` on a |
| 27 | [Project](/railway/compute/projects). |
| 28 | |
| 29 | Workspace is **not** an Alchemy resource. Pin a workspace with |
| 30 | `workspaceId` on `Railway.Project`. |
| 31 | |
| 32 | ## Generate an API token |
| 33 | |
| 34 | Alchemy needs an **account** or **workspace** token |
| 35 | (`RAILWAY_API_TOKEN`). Project tokens cannot reach workspace-wide |
| 36 | operations. |
| 37 | |
| 38 | In the dashboard: |
| 39 | |
| 40 | 1. Open **Account Settings** → **Tokens**. |
| 41 | 2. Create an account token (or a workspace token) with permission to |
| 42 | manage projects and services. |
| 43 | 3. Copy the token — Railway shows it **only once**. |
| 44 | |
| 45 | The official environment variable is `RAILWAY_API_TOKEN`. An optional |
| 46 | `RAILWAY_API_URL` overrides the GraphQL host (default |
| 47 | `https://backboard.railway.com`). |
| 48 | |
| 49 | ## Create a project directory |
| 50 | |
| 51 | <PackageManagers init dir="my-app" /> |
| 52 | |
| 53 | ## Install |
| 54 | |
| 55 | <PackageManagers add={pkgs} /> |
| 56 | |
| 57 | ## Connect alchemy to Railway |
| 58 | |
| 59 | There is no separate credentials step. The first time you run |
| 60 | `alchemy deploy` (or `plan`, `dev`, `destroy`) on a stack that uses |
| 61 | `Railway.providers()`, alchemy walks you through an interactive login |
| 62 | with three options: |
| 63 | |
| 64 | - **OAuth** — opens `railway.com/cli-login` and pairs the CLI with |
| 65 | your account. No pre-existing token needed. |
| 66 | - **API Token** — paste the token you generated above. It's saved |
| 67 | under `~/.alchemy/credentials/<profile>/`. |
| 68 | - **Environment Variables** — reads `RAILWAY_API_TOKEN` from the |
| 69 | environment on every run (plus an optional `RAILWAY_API_URL`). |
| 70 | In CI (`CI=true`) alchemy skips the prompt and uses the |
| 71 | environment automatically. |
| 72 | |
| 73 | Either choice is saved to your **`default`** |
| 74 | [profile](/environments/profiles) and reused on every subsequent |
| 75 | command. |
| 76 | |
| 77 | To re-run the setup later (e.g. to rotate the token, or configure a |
| 78 | separate `prod` profile): |
| 79 | |
| 80 | ```sh |
| 81 | # Re-run the interactive setup (e.g. to rotate the token) |
| 82 | alchemy profile edit --reconfigure Railway |
| 83 | |
| 84 | # Or connect Railway in a separate `prod` profile |
| 85 | alchemy profile create prod |
| 86 | alchemy profile edit --profile prod --add Railway |
| 87 | |
| 88 | # Non-interactive (scripts, agents) |
| 89 | alchemy profile edit --add Railway --method stored --set token=env:RAILWAY_API_TOKEN |
| 90 | ``` |
| 91 | |
| 92 | Inspect what's stored (secrets are redacted): |
| 93 | |
| 94 | ```sh |
| 95 | alchemy profile show |
| 96 | ``` |
| 97 | |
| 98 | :::note[Effect-native Services] |
| 99 | [`Railway.Service`](/railway/compute/services) with `main` bundles |
| 100 | your Effect program, generates a Dockerfile, and uploads the |
| 101 | context. Railway builds the image — no GHCR, no Docker daemon on |
| 102 | the machine that runs `alchemy deploy`. Image-based Services |
| 103 | (`image: "hashicorp/http-echo"`) skip the build and pull a public |
| 104 | tag. |
| 105 | ::: |
| 106 | |
| 107 | ## State storage |
| 108 | |
| 109 | Railway has no object-storage state backend of its own, so pick one of: |
| 110 | |
| 111 | - **`Alchemy.localState()`** — state on disk under `.alchemy/` next |
| 112 | to your code. Zero setup; right for solo projects and trying |
| 113 | things out. |
| 114 | - **A cloud state store** — if you also use Cloudflare or AWS, pass |
| 115 | `Cloudflare.state()` or `AWS.state()` so state is shared with |
| 116 | your team and CI. See [State Store](/state-store). |
| 117 | |
| 118 | ## Next steps |
| 119 | |
| 120 | - [Tutorial part 1](/railway/tutorial/part-1) — deploy your first |
| 121 | Project. |
| 122 | - [Railway overview](/railway) — the map of resources and guides. |