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