Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
Manages Railway PaaS deployments via CLI for creating services, infrastructure, networking config, environment variables, logs, and SSH debugging.
npx claudepluginhub fortiumpartners/ensemble --plugin ensemble-infrastructureHow this skill is triggered — by the user, by Claude, or both
Slash command
/ensemble-infrastructure:managing-railwayThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Fast reference for Railway CLI operations. See [REFERENCE.md](REFERENCE.md) for comprehensive documentation.
Operates Railway infrastructure: create projects, provision services and databases, manage object storage buckets, deploy code, configure environments and variables, manage domains, and troubleshoot failures via the Railway CLI.
Validates and deploys Node.js, Python, or Docker apps to Railway with environment variables, custom domains, and monitoring.
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Share bugs, ideas, or general feedback.
Fast reference for Railway CLI operations. See REFERENCE.md for comprehensive documentation.
What is Railway: Modern PaaS for instant deployments with zero configuration. Supports any language/framework via Nixpacks or Dockerfile. Includes managed databases, private networking, and automatic SSL.
When to Use: Deploying apps, managing services/databases, debugging (logs, SSH), configuring domains, managing environment variables, CI/CD integration.
Auto-Detection: railway.json, railway.toml, RAILWAY_TOKEN in .env, or user mentions Railway.
Railway CLI can enter interactive mode which will hang Claude Code. Always use flags:
| Command | WRONG | CORRECT |
|---|---|---|
| Link project | railway link | railway link -p <project> -e <env> |
| Create project | railway init | railway init -n <name> |
| Switch env | railway environment | railway environment <name> |
| Remove deploy | railway down | railway down -y |
| Redeploy | railway redeploy | railway redeploy -y |
| Deploy | railway up | railway up --detach |
| SSH | railway ssh | railway ssh -- <command> |
Required flags: -y (skip prompts), --detach (background), explicit names, --json (parsing), -- <cmd> (SSH).
Never use: railway login, railway connect (without service), railway shell, commands without explicit params.
# Verify installation
railway --version # Expects: 3.x.x+
# Install options
npm i -g @railway/cli # npm
brew install railway # Homebrew
bash <(curl -fsSL cli.new) # Shell script
| Token Type | Env Variable | Scope |
|---|---|---|
| Project Token | RAILWAY_TOKEN | Single environment (for logs, up) |
| Account Token | RAILWAY_API_TOKEN | All projects (for init, link) |
Critical: railway logs requires a Project Token, not an account token.
# Set token for session
export RAILWAY_TOKEN="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
# Or inline from .env
RAILWAY_TOKEN=$(grep RAILWAY_TOKEN .env | cut -d= -f2) railway logs
# Verify authentication
railway whoami
grep -i railway .env
grep -E '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' .env
See REFERENCE.md for token creation and storage best practices.
├── Create project → railway init -n <name>
├── Link to project → railway link -p <project> -e <env>
├── List projects → railway list
├── View status → railway status
└── Open dashboard → railway open
├── Deploy (background) → railway up --detach
├── Redeploy → railway redeploy -y
├── Remove deployment → railway down -y
└── Deploy template → railway deploy -t <template>
├── Add PostgreSQL → railway add -d postgres
├── Add Redis → railway add -d redis
├── Add from repo → railway add -r owner/repo
├── Run with vars → railway run <command>
└── Link to service → railway service <name>
├── View logs → railway logs
├── Build logs → railway logs -b
├── SSH command → railway ssh -- <command>
└── Check status → railway status
├── Switch environment → railway environment <name>
├── Create environment → railway environment new -d <source>
├── Delete environment → railway environment delete <name> -y
├── View variables → railway variables
└── Set variable → railway variables --set KEY=value
See REFERENCE.md for all commands with full flag details.
| Command | Example |
|---|---|
railway init | railway init -n myapp |
railway link | railway link -p myproject -e production |
railway list | railway list |
railway status | railway status |
railway unlink | railway unlink |
| Command | Example |
|---|---|
railway up | railway up --detach |
railway redeploy | railway redeploy -y |
railway down | railway down -y |
railway logs | railway logs -d <id> |
| Command | Example |
|---|---|
railway add | railway add -d postgres |
railway service | railway service api |
railway run | railway run npm start |
| Command | Example |
|---|---|
railway logs | railway logs |
railway logs -b | railway logs -b |
railway ssh -- cmd | railway ssh -- ls -la |
| Code | Location |
|---|---|
us-west2 | California, USA |
us-east4-eqdc4a | Virginia, USA |
europe-west4-drams3a | Amsterdam, Netherlands |
asia-southeast1-eqsg3a | Singapore |
| Type | Flag | Shell |
|---|---|---|
| PostgreSQL | -d postgres | psql |
| MySQL | -d mysql | mysql |
| Redis | -d redis | redis-cli |
| MongoDB | -d mongo | mongosh |
| Variable | Description |
|---|---|
RAILWAY_PUBLIC_DOMAIN | Public domain |
RAILWAY_PRIVATE_DOMAIN | Private domain (.railway.internal) |
PORT | Port to listen on |
RAILWAY_ENVIRONMENT | Environment name |
railway init -n myapp # Create project
railway up --detach # Deploy (background)
railway logs # Check logs
railway add -d postgres # Add PostgreSQL
railway run npm run migrate # Run migrations
railway domain # Generate Railway domain
railway domain api.myapp.com -p 3000 # Custom domain
railway status # Check status
railway logs # View runtime logs
railway logs -b # View build logs
railway ssh -- ps aux # SSH command
export RAILWAY_TOKEN=${{ secrets.RAILWAY_TOKEN }}
railway up --detach -s api
See REFERENCE.md for GitHub Actions, GitLab CI, and CircleCI examples.
Services communicate via: <service-name>.railway.internal
Example: http://api.railway.internal:3000
Apps must listen on :: for IPv4/IPv6:
// Node.js
app.listen(process.env.PORT, '::', () => console.log('Running'));
# Python
gunicorn --bind "[::]:${PORT:-8000}" app:app
See REFERENCE.md for library configurations and TCP proxy.
| Error | Resolution |
|---|---|
command not found: railway | Install via npm/brew |
Not logged in | Set RAILWAY_TOKEN |
No project linked | Run railway link |
Unauthorized | Check token, re-authenticate |
Deployment failed | Check railway logs -b |
# 1. Get PROJECT token (not account token)
grep -i railway .env
# 2. Set token and verify
export RAILWAY_TOKEN="<uuid>"
railway whoami
# 3. Check logs
railway logs
Common 502 causes: Missing dependencies, port binding issues, startup crashes.
See REFERENCE.md for comprehensive troubleshooting.
app.listen(process.env.PORT, '::', () => console.log('Running'));
# Procfile
web: gunicorn --bind "[::]:${PORT:-8000}" app:app
// railway.json
{
"deploy": {
"startCommand": "bundle exec rails server -b :: -p $PORT"
}
}
See REFERENCE.md for complete configuration options.
railway status --json | jq '.services[].name'
railway logs --json | jq -r 'select(.level == "error") | .message'
# Authentication
export RAILWAY_TOKEN="xxx"
# Project
railway init -n myapp
railway link -p myproject -e production
railway status
# Deploy
railway up --detach
railway redeploy -y
railway down -y
# Services
railway add -d postgres
railway run npm run migrate
# Debug
railway logs
railway logs -b
railway ssh -- ps aux
# Environment
railway environment staging
railway variables --set KEY=value
# Domain
railway domain api.example.com -p 3000
See REFERENCE.md for: Complete command documentation, advanced deployment patterns, volume management, environment variable strategies, networking deep dive, CI/CD integration, security best practices, troubleshooting, and config-as-code.