Auto-activate for railway.toml, railway.json, Procfile. Expert knowledge for Railway deployment platform. Use when deploying applications, configuring services, managing databases, or troubleshooting Railway deployments. Not for Heroku, Fly.io, or self-hosted deployments.
From flownpx claudepluginhub cofin/flow --plugin flowThis skill uses the workspace's default tool permissions.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
Railway's serverless feature puts services to sleep after 10 minutes of no outbound traffic.
Key Rules:
sleepApplication: false in railway.json disables serverlessWhen to disable serverless:
{
"$schema": "https://railway.com/railway.schema.json",
"build": {
"builder": "DOCKERFILE",
"dockerfilePath": "Dockerfile"
},
"deploy": {
"runtime": "V2",
"numReplicas": 1,
"sleepApplication": false,
"startCommand": "python main.py",
"healthcheckPath": "/health",
"healthcheckTimeout": 300,
"restartPolicyType": "ON_FAILURE",
"restartPolicyMaxRetries": 5
}
}
</example>
Important: A single railway.json in root applies globally to ALL services from the same repo. For service-specific configs:
railway.app.json, railway.worker.json{
"$schema": "https://railway.com/railway.schema.json",
"deploy": {
"startCommand": "npm start"
},
"environments": {
"staging": {
"deploy": {
"startCommand": "npm run staging"
}
},
"pr": {
"deploy": {
"sleepApplication": true
}
}
}
}
</example>
# Login
railway login
# Check current user
railway whoami
# Initialize new project
railway init --name "my-project"
# Link to existing project
railway link
# Check project status
railway status
railway status --json
# Add services
railway add --service "Web App"
railway add --database postgres
railway add --database redis
# Link to specific service
railway service link "Web App"
# List services
railway service --json
# Set variables (triggers redeploy)
railway variables --set "DATABASE_URL=postgres://..." --set "PORT=3000"
# Set variables without redeploy
railway variables --set "CONFIG_VALUE=123" --skip-deploys
# Set for specific service
railway variables --service=backend --set "DEBUG=true"
# View variables
railway variables --kv
railway variables --json
# Use Railway variable references
railway variables --set 'DATABASE_URL=${{Postgres.DATABASE_URL}}'
railway variables --set 'REDIS_URL=${{Redis.REDIS_URL}}'
railway variables --set 'APP_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}'
# Deploy current directory
railway up
# Deploy without waiting
railway up --detach
# View logs
railway logs
railway logs --tail 100
# Generate public domain
railway domain
# Run command with Railway environment
railway run npm start
railway run python manage.py migrate
# Run with specific service's variables
railway run --service=backend npm run dev
For applications with background task processing:
Web Service:
/health)tools/deploy/railway/railway.app.jsonWorker Service:
tools/deploy/railway/railway.worker.jsonExample Config Files:
<example>Web (railway.app.json):
{
"$schema": "https://railway.com/railway.schema.json",
"build": {
"builder": "DOCKERFILE",
"dockerfilePath": "tools/deploy/docker/Dockerfile.distroless"
},
"deploy": {
"runtime": "V2",
"sleepApplication": false,
"healthcheckPath": "/health",
"healthcheckTimeout": 300
}
}
Worker (railway.worker.json):
{
"$schema": "https://railway.com/railway.schema.json",
"build": {
"builder": "DOCKERFILE",
"dockerfilePath": "tools/deploy/docker/Dockerfile.worker"
},
"deploy": {
"runtime": "V2",
"sleepApplication": false,
"restartPolicyType": "ON_FAILURE",
"restartPolicyMaxRetries": 10
}
}
</example>
Example Dockerfiles:
<example>Web (Dockerfile):
CMD ["python", "-m", "gunicorn", "app:create_app", "--bind", "0.0.0.0:8000"]
Worker (Dockerfile.worker):
CMD ["python", "-m", "celery", "-A", "app.tasks", "worker"]
</example>
Both services need access to:
${{Postgres.DATABASE_URL}})${{Redis.REDIS_URL}})Copy shared variables to worker service:
railway service link "Web App"
SECRET=$(railway variables --kv | grep SECRET_KEY | cut -d'=' -f2-)
railway service link "Worker"
railway variables --set "SECRET_KEY=${SECRET}" \
--set 'DATABASE_URL=${{Postgres.DATABASE_URL}}' \
--set 'REDIS_URL=${{Redis.REDIS_URL}}' \
--skip-deploys
</workflow>
Symptoms: Service stuck in "Sleeping" state, requests timeout
Causes:
Solutions:
railway.json → sleepApplicationrailway logsrailway upSymptoms: Jobs queued but not processed
Causes:
Solutions:
REDIS_URL is set correctly with ${{Redis.REDIS_URL}}railway service link "Worker" && railway logsCommon issues:
dockerfilePath in railway.jsonFor HTTP services:
{
"deploy": {
"healthcheckPath": "/health",
"healthcheckTimeout": 300
}
}
For workers: Disable health checks in Railway dashboard (no HTTP endpoint)
${{Postgres.DATABASE_URL}} auto-updates if DB changes--skip-deploys when setting multiple variables to avoid multiple redeploys| Variable | Description |
|---|---|
${{Postgres.DATABASE_URL}} | PostgreSQL connection string |
${{Redis.REDIS_URL}} | Redis connection string |
${{RAILWAY_PUBLIC_DOMAIN}} | Auto-generated public domain |
${{RAILWAY_STATIC_URL}} | URL for static assets |
${{PORT}} | Railway's injected port (use for app port config) |
Railway injects PORT at runtime. Never hardcode port numbers - always reference dynamically:
# Correct - dynamic reference
railway variables --set 'LITESTAR_PORT=${{PORT}}'
# Wrong - hardcoded value won't update if Railway changes it
railway variables --set 'LITESTAR_PORT=8080'