Railway Deploy

Railway Deploy

Operate Railway from the CLI: create projects, add services + databases, set variables, deploy, debug. Optimised for agent + CI use (token-based auth, non-interactive flags).

When to use

• Creating a new Railway project / service / database
• Deploying local code or a Docker image to Railway
• Setting env vars or wiring services together via private networking
• Tailing logs or SSH-ing into a running container
• Debugging a failing deploy (build, healthcheck, migration)

References

Read these on demand — do not pre-load.

• [references/cli-reference.md](references/cli-reference.md) — complete CLI:

every command, flag, template-variable syntax, railway.toml schema, practical patterns. Open when you need an exact command or flag.

• [references/nextjs-prisma.md](references/nextjs-prisma.md) — Next.js

(standalone) + Prisma + PostgreSQL deploy recipe: Dockerfile, entrypoint with prisma migrate deploy, healthcheck route, common pitfalls. Open only when deploying a Next.js+Prisma app.

Authentication

CI / agents → set one env var, no railway login needed:

| Variable | Scope | Use case | |----------|-------|----------| | RAILWAY_TOKEN | single project | agent deploys, CI | | RAILWAY_API_TOKEN | full account | account-wide automation |

Interactive (humans only): railway login (or --browserless in headless shells). Verify with railway whoami / railway status.

Also set RAILWAY_NO_TELEMETRY=1 to silence the telemetry prompt.

Top gotchas (read before acting)

These bite repeatedly. The full list is in the CLI reference.

1. railway init creates a project, not a service. Always follow with

railway add --service "" to create the app service.

1. railway add --service is interactive unless you pass --variables

inline. Pass them to skip the TUI.

1. Variable command is railway variable (singular). Plural exists in

older docs/skills but is wrong in current CLI. Subcommands: list, set, delete. There is no variable get — use railway variable list --kv and grep.

1. --variables KEY=VAL without quotes in spawnSync/execFileSync.

Quotes get parsed as part of the key.

1. railway link always re-prompts. To switch service inside an

already-linked project, use railway service link .

1. VOLUME is banned in Dockerfiles on Railway — build will fail. Strip

any VOLUME instructions.

1. railway up uploads the working directory (respecting

.railwayignore → .gitignore). It is not git-based.

1. railway run is local; railway ssh is in-container. Use ssh for

migrations, bootstrap, or anything touching container fs.

1. Template variables use ${{Service.VAR}} (double braces). Resolved

by Railway at runtime, not by your shell — escape $ in heredocs/scripts.

Core workflows

Deploy a new service from local code

railway init --name "my-app"
railway add --service "api" \
  --variables PORT=3000 \
  --variables NODE_ENV=production \
  --variables 'DATABASE_URL=${{Postgres.DATABASE_URL}}'
railway add --database postgres
railway service link api
railway up --detach
railway domain --port 3000
railway logs

Add a service to an existing project

railway add --service "worker" \
  --variables 'DATABASE_URL=${{Postgres.DATABASE_URL}}' \
  --variables 'API_URL=http://api.railway.internal:3000'
railway service link worker
railway up --detach

Service-to-service networking

Internal DNS, zero config, free egress, encrypted:

http://.railway.internal:

Always prefer this over the public domain for service-to-service calls.

Debug a failing deploy

railway status                     # what's linked?
railway logs -s           # runtime logs
railway logs -s  --build  # build logs
railway ssh -s            # poke around in the container
railway variable list -s  # confirm env

Healthcheck failing? Verify the endpoint returns 200 and the port matches the one Railway is probing (set in railway.toml [deploy] healthcheckPath

• exposed PORT).

Config as code

Place railway.toml at project root — it overrides dashboard settings:

[build]
builder = "DOCKERFILE"
dockerfilePath = "Dockerfile"

[deploy]
healthcheckPath = "/api/health"
healthcheckTimeout = 30
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 3

Full schema (env overrides, cron, watchPatterns, preDeployCommand, …) in the CLI reference.

Quick command index

railway status [--json]                       # current link
railway list [--json]                         # all projects
railway add --service "" --variables K=V
railway add --database postgres|mysql|redis|mongo
railway service link                    # switch service in project
railway variable list [--kv] [-s ]
railway variable set K=V [K2=V2 …]
railway up [--detach] [--ci] [-s ]
railway redeploy [-s ]
railway domain [--port N] [-s ] []
railway logs [-s ] [--build] [-n N]
railway ssh [-s ]                        # in-container shell
railway run                              # local cmd with railway env
railway connect                               # db shell

For anything not listed here, open references/cli-reference.md.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Yesterday-AI
• Source: Yesterday-AI/skills
• License: MIT
• Homepage: https://github.com/Yesterday-AI/skills

Install and usage instructions live in the source repository linked above.