The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 122 lines 4.04 KB
Raw
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.