First time? Wonderful.
Get ready to amaze yourself, by yourself.
This is the one-time, account-level groundwork before your first harness project: three accounts wired together, two tokens, two secrets. None of it assumes you've done anything like this before, every step shows you where to click, and you will never have to read this page again. Budget about fifteen unhurried minutes.
Most people land here because /setup in Claude Code sent them. Perfect: read top to bottom, do the steps, and the page ends with the exact phrase to type when you get back.
code-only?If your project won't deploy anywhere (a script, a library, a CLI), you only need steps 1a and 1b below: GitHub plus Claude. Everything Railway, tokens included, is for projects that go live on the web.
Three accounts, one hub
The harness runs on three services. GitHub stores your code, Claude writes it, and Railway puts it on the internet. GitHub is the hub: Claude connects to GitHub so Claude Code can work with your repository, and Railway connects to GitHub so it can deploy what lands there. Claude and Railway never talk to each other directly.
The order that cannot fail: first the GitHub account, then Claude → GitHub, then Railway → GitHub. Both connections attach to GitHub, so GitHub has to exist before either of them; the two connections are independent of each other, so once GitHub exists, nothing you do here can deadlock. We do Claude before Railway simply because you'll drive everything from Claude Code afterwards.
Create your GitHub account
Sign up at github.com/signup if you don't have an account yet. The free plan is all the harness needs. This account will own your project repositories, so pick a username you like saying out loud.
Connect Claude to GitHub
You'll need a Claude account with Claude Code (the Pro plan covers it): sign up at claude.ai. Then open claude.ai/code and sign in. On your first visit it prompts you to connect GitHub: follow the prompt and install the Claude GitHub App on the account you just created, granting it access to your repositories.
That connection is what lets Claude Code reach your repositories from claude.ai and the mobile app. If you later run Claude Code on your own machine (the desktop app, CLI, or an IDE extension), you'll also sign in to GitHub once there when you first clone a repository; the tools walk you through it.
Create your Railway account
Sign up at railway.com (the Hobby plan is fine). "Login with GitHub" is the comfortable route, but heads up: logging in with GitHub only signs you in. It does not yet let Railway see your repositories; that's the next step, and skipping it is the classic first-timer trap.
Install Railway's GitHub App
In the Railway dashboard, click + New › Deploy from GitHub repo and follow the Configure GitHub App button (you can cancel the project creation afterwards; the harness creates real projects for you later). GitHub asks where to install the Railway app: pick the account from step 1a.
Under Repository access, choose All repositories. Your harness repository doesn't exist yet, and "all" means never coming back to this screen. Prefer Only select repositories? Also fine, just remember the deal: every new harness repository must be added to that list right after you create it (github.com › Settings › Applications › Railway › Configure).
See the connection with your own eyes
Back in Railway, open Account Settings and find the Connected Accounts section. GitHub should be listed there with your username. If it shows up, the link is real and you're done wiring accounts, forever.
The GitHub token (PAT_TOKEN)
The harness's automation runs inside GitHub Actions, and it needs permission to act on your repository: push branches, merge pull requests, store a secret. That permission slip is a fine-grained personal access token, a long random string you create once per project and scope tightly to that one repository. You'll create it now and plant it as the secret PAT_TOKEN in step 4.
Open the token form
Go to github.com/settings/personal-access-tokens/new (the long way there: GitHub › Settings › Developer settings › Personal access tokens › Fine-grained tokens). Name it after your project, something like my-app-harness. GitHub asks for an expiration; pick what you're comfortable with. When it eventually expires, workflows start failing with auth errors and the fix is a fresh token pasted over the old secret. Future you will cope.
Scope it to the one repository
Under Repository access, choose Only select repositories and pick the repository this project lives in (if you're following the wizard, the one you just created). The token then can't touch anything else you own, which is exactly how you want it.
Grant the permissions
Under Permissions › Repository permissions, set all four of these to Read and write. Tick them off as you go:
all four are required; setup's token check fails if any is missing.
Click Generate token and copy the value somewhere safe for the next few minutes (or straight into step 4). It is shown only once.
The Railway token (RAILWAY_ACCOUNT_TOKEN)
Same idea, other side: GitHub Actions also needs permission to act on your Railway account, so it can create your production and preprod environments and a fresh preview environment for every feature you build. That's a Railway account token.
Create an account token
Go to railway.com/account/tokens, name the token after your project, and, the one detail that matters: leave the workspace dropdown on No workspace. That makes it an account-level token. A workspace-scoped token can't manage the per-feature environments the harness creates and deletes on your behalf.
Create it and copy the value. Like the GitHub one, it is shown exactly once.
Plant both in your repository
Now hand both values to your repository's automation. GitHub calls these repository secrets: values workflows can use but nobody can read back, not even you.
Add the two secrets
In your repository on GitHub, open Settings › Secrets and variables › Actions, click New repository secret, and add each of these, names exactly as written, values pasted plain with no quotes and no spaces:
- →
PAT_TOKEN: the GitHub token from step 2 - →
RAILWAY_ACCOUNT_TOKEN: the Railway token from step 3
Don't verify anything by hand
Planted is finished. You do not need to test these tokens, and honestly you couldn't: GitHub never shows a secret again. Instead, /setup runs a preflight: a real workflow that uses both tokens for real, before anything on your repository is touched. If a permission is missing, it stops and names the exact probe that failed, you fix the token, run /setupagain, and it re-checks. Verification is the harness's job now, not yours.
What happens next
So nothing that follows surprises you, here's the whole /setup run from the inside. It narrates every stage as it goes; the quiet stretches are machines doing machine things, not something stuck.
- 01a couple of questionsyou
whether this is your first time (you're handling that right now), whether the project deploys to Railway, and whether to start from the pre-built technical foundation.
- 02the token check~1 min
a real workflow run tries both tokens for real. Pass and it moves on; fail and it names exactly what failed and waits for you to fix it.
- 03applying your configurationseconds (foundation: +2-3 min)
the chosen machinery is moved into place and one commit is pushed. If you picked the technical foundation, the pre-built app is copied in and verified first.
- 04provisioning on Railway~3-6 min
production and preprod environments appear: app service, PostgreSQL database, and file bucket in each. This is the longest quiet stretch.
- 05your live URLsthe payoff
setup prints the production and preprod URLs and polls production until it confirms the app is actually serving, then hands off.
And after that? A fresh chat, type /feature, describe one small idea in a sentence, and watch the pipeline you just wired carry it all the way to a live URL. That's the amaze-yourself part.
The two ways this usually goes sideways
Setup stopped on the GitHub token
Setup quotes a line naming the probe that failed, for example pat-secrets: denied. That means the token is missing one of its permissions. Open github.com/settings/personal-access-tokens, edit the token (or generate a fresh one), set all four, Contents, Pull requests, Workflows, Secrets, to Read and write, update the PAT_TOKEN secret if you regenerated, and run /setup again. It simply re-runs the check; nothing was changed in your repository before it stopped.
Setup stopped on the Railway token
A line like railway-token: invalid means Railway would not accept the token. The usual cause is the wrong kind: redo step 3a and make sure the workspace dropdown was left on No workspace, so you get an account token rather than a workspace-scoped one. Overwrite the RAILWAY_ACCOUNT_TOKEN secret with the new value and run /setup again. A missing line instead of an invalid one usually means the secret name is misspelled: it must match exactly.
// the magic words
That's everything. Go back to your Claude Code session, where /setup is patiently waiting, and type exactly:
That phrase is the cue /setup listens for; it picks up right where it left off. No session open yet because you arrived from the wizard? Finish the wizard first; the cue is for when /setup sends you here.