railwayexpert

name: RailwayExpert description: Railway.app deployment platform expert. USE WHEN deploy to Railway OR railway.toml OR Railway CLI OR Railway build error OR Railway deploy error OR healthcheck failed OR Railway database OR Railway private networking OR Railway scaling OR Railway API OR Railway pricing OR Railway volumes OR Railpack OR Nixpacks OR "Application failed to respond" OR Railway PORT binding OR Railway cron OR Railway monorepo OR Railway Docker.

RailwayExpert

Expert skill for configuring, deploying, troubleshooting, and optimizing applications on Railway.app. Covers the full lifecycle from project setup to production scaling.

Workflow Routing

Reference Files

Examples

Example 1: Deploy a Node.js app

User: "Deploy my Express app to Railway"
-> Invokes Setup workflow
-> Generates railway.toml with PORT binding
-> Sets healthcheck path
-> Runs: railway up

Example 2: Fix "Application failed to respond"

User: "My Railway deploy shows Application failed to respond"
-> Invokes Troubleshoot workflow
-> Checks: PORT binding (must use process.env.PORT)
-> Checks: Host binding (must be 0.0.0.0, not localhost)
-> Checks: Healthcheck path returns 200
-> Checks: Build completed successfully

Example 3: Set up Postgres with migrations

User: "Add Postgres to my Railway project with Prisma migrations"
-> Invokes Database workflow
-> Adds Postgres service via CLI or dashboard
-> Configures DATABASE_URL reference variable
-> Sets preDeployCommand for migrations
-> Handles private networking vs public URL

Example 4: Configure monorepo

User: "Deploy my Turborepo to Railway"
-> Invokes Setup workflow
-> Sets root directory per service
-> Configures watchPatterns for selective deploys
-> Sets buildCommand with workspace filter

Quick Reference

Essential Commands

railway login                    # Authenticate
railway init                     # Create new project
railway link                     # Link to existing project
railway up                       # Deploy current directory
railway up --detach              # Deploy without log streaming
railway logs                     # View runtime logs
railway logs --build             # View build logs
railway ssh                      # SSH into running container
railway run <cmd>                # Run command with Railway env vars
railway variable set KEY=value   # Set environment variable
railway domain                   # Generate public domain
railway connect                  # Connect to database shell

Minimal railway.toml

[build]
builder = "RAILPACK"

[deploy]
startCommand = "node dist/index.js"
healthcheckPath = "/health"
healthcheckTimeout = 300
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 5

Plans Quick Reference

Usage Pricing

• RAM: $10/GB/month
• CPU: $20/vCPU/month
• Network Egress: $0.05/GB
• Volume Storage: $0.15/GB/month

Regions

Deployment Lifecycle

1. Build → Railpack/Nixpacks/Dockerfile creates image
2. Pre-deploy → preDeployCommand runs (volumes NOT mounted)
3. Deploy → Container starts with startCommand
4. Healthcheck → Polls healthcheckPath until HTTP 200 (timeout: 300s default)
5. Activation → New deploy goes live, old enters drain
6. Overlap → Old stays active for overlapSeconds (default 0)
7. Drain → SIGTERM → wait drainingSeconds → SIGKILL

Critical Gotchas

1. PORT: App MUST listen on process.env.PORT — Railway injects it dynamically
2. Host binding: Must bind to 0.0.0.0, NOT localhost or 127.0.0.1
3. Ephemeral filesystem: Files written outside volumes are lost on redeploy
4. Private networking is IPv6: Use family: 0 in Node.js clients (ioredis, pg)
5. Healthcheck is startup-only: No continuous monitoring — use Uptime Kuma for that
6. Config-as-code overrides dashboard: railway.toml values always win
7. Build phase has no network: Cannot reach private services during build
8. Volumes mount at runtime only: Not available during build or pre-deploy
9. Custom start command breaks SPA detection: Remove start command for Railpack SPAs
10. Healthcheck origin: Requests come from healthcheck.railway.app — allowlist it