Blog ·How-to ·April 23, 2026 ·9 min read

How to get AI to deploy code to Railway

A safe, repeatable pattern for giving an agent deploy access — without giving away the keys to the kingdom.

TL;DR

Create a scoped Railway token. Install the CLI. Pin config in railway.json. Give the agent repo + CLI access. Run railway up, verify health check, generate domain, rollback on fail. Rotate token every 90 days.

What you'll learn

How to scope a Railway token for agent use
The exact CLI commands an agent should be allowed to run
A railway.json pattern for deterministic builds
Rollback as a first-class safety net

What you need

A Railway account (free tier works for small projects)
A GitHub repo
An AI agent with shell access (Cursor, Claude Code, or Black Box)
Node 20+ for the CLI

Step 1: Create a Railway account + project

Go to railway.app. Sign in with GitHub. Click New Project → Deploy from GitHub. Connect the repo you want deployed. Railway auto-detects most stacks (Node, Python, Go, Rust). Railway's auto-detect gets you 80% of the way with zero config.

Step 2: Get a Railway API token

In Railway → Account Settings → Tokens → Create Token. Copy it immediately — shown once. Scope: Team or Personal depending on the project. Treat it like a password. Project-scoped beats account-scoped. Rotate every 90 days.

Step 3: Set up the CLI

Run: npm i -g @railway/cli. Then: railway login --browserless. Paste the token. Verify with: railway whoami. You're now authenticated on the machine (or container) that the AI will run from. The CLI is the agent's hands. No CLI = no deploy.

Step 4: Give the AI the repo + a clear goal

The prompt that works: "Here is the repo [paste tree + key files]. Deploy it to Railway. Ensure env vars [list] are set. Run the health check at /healthz after deploy. Report the public URL." Specific goal + measurable success criterion = a repeatable deploy.

Step 5: Scope the AI's tool access correctly

The agent needs: read/write to the repo, shell access for the Railway CLI, and a way to set env vars. Do NOT give it your billing/account-delete scopes. In Black Box, the Coding specialist is already scoped this way. Principle of least privilege applies to agents more than to humans.

Step 6: Use railway.json to pin config

Create a railway.json at repo root: { "build": { "builder": "NIXPACKS" }, "deploy": { "startCommand": "node dist/server.js", "healthcheckPath": "/healthz", "restartPolicyType": "ON_FAILURE" } }. Makes deploys deterministic. Deterministic config = reproducible deploys.

Step 7: Run railway up and stream the logs

The AI runs: railway up --detach, then railway logs -f | head -200. If the build succeeds and /healthz returns 200, the deploy is live. If not, the AI reads the log, diffs against the last green deploy, and proposes a fix. Logs + health check = the deploy's own QA.

Step 8: Generate a public domain + custom subdomain

railway domain generates a public URL (xyz.up.railway.app). To add a custom domain: railway domain add api.yourcompany.com, then follow the CNAME instructions. SSL provisions automatically in ~2 minutes. Railway's DNS + SSL handling is the cleanest on the market right now.

Step 9: Wire a rollback strategy

Every Railway deploy keeps the previous build. If anything goes wrong: railway rollback. The agent should always check /healthz post-deploy and rollback automatically if it fails twice. The rollback condition is the safety net. Never ship without it.

Concrete example: a Node API deploy in 4 minutes

An engineer we work with onboarded a new Node API this week. Clone → add railway.json → railway init → railway up. The agent watched logs, saw a missing DATABASE_URL env var, ran railway variables set DATABASE_URL=..., re-deployed, /healthz returned 200, generated a custom domain. End-to-end: 4m 17s of wall-clock time. One deploy, one rollback available, zero SSH sessions.

Common pitfalls + how to avoid them

Account-scoped tokens. Project-scoped only. One leaked token shouldn't mean full billing access.
No health check. Agents need a deterministic "succeed or fail" signal. /healthz is it.
Secrets in prompts. Never. Use env vars + named references.
No rollback logic. The first bad deploy is inevitable. The undo must exist.

Key takeaways

Scoped tokens + CLI = safe agent deploys.
railway.json pins config. Deterministic beats clever.
Health check is the deploy's own QA.
Custom domain + SSL: one command.
Rollback is the safety net. Always wire it.

FAQ

Is it safe to give an AI my Railway token?

Yes if you scope it to one project and rotate every 90 days. In Black Box the token is stored in our vault and never shown to the model — the agent uses it via a server-side tool call.

What if the deploy fails?

A good agent reads the build logs, diffs them against the last success, proposes a fix, and asks before re-deploying. Bad agents just retry. Ask the agent to report back before re-running.

Does this work with Vercel / Fly / Render?

Same pattern. Replace the CLI (vercel / flyctl / render). Every major platform has a token-auth CLI suitable for agent use.

Can the AI manage env vars?

Yes: railway variables set KEY=VALUE. Never put secrets in the prompt — always reference them by name and let the agent read them from a pre-populated env file or secrets vault.