🎯

railway

🎯Skill
g1joshi/agent-skills1 Installs9Last Updated Feb 10, 2026

Installation

$npx skills add g1joshi/agent-skills --skill railway

Run it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).

Uses skills.sh Β· Node.js 22.20+

After installing

Ask for related work and the agent uses it on its own, or call it yourself.

Run it (Claude Code)/railway
Install by hand

Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.

Open the skill folder β†’
  • This project .claude/skills/railway/
  • All projects ~/.claude/skills/railway/

These paths are for Claude Code. For other tools, the command above puts it in the right place.

Expert Railway cloud platform assistance covering Nixpacks buildpacks, instant deployments, PostgreSQL/Redis plugins, and environment variables. Use when deploying full-stack web applications without infrastructure overhead.

Railway

Railway is a modern PaaS that offers "Infrastructure from Code". It introspects your repo and deploys it. Can also deploy Databases (Postgres, Redis, Mongo).

When to Use

  • Frictionless Full-Stack Cloud Hosting: Deploying databases, microservices, and frontends with instant Git synchronization.
  • Private Mesh Networking: Communicating between services over secure private IPv6 addresses without internet traversal.
  • Managed Production Databases: One-click provisioning of PostgreSQL, Redis, MySQL, and MongoDB with automated backups.
  • Ephemeral PR Preview Environments: Creating isolated staging environments automatically for every pull request.

Quick Start

railway login
railway init
railway up

Core Concepts

Declarative Service Configuration (railway.json)

Defining build commands, health checks, and restart policies:

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm run build"
  },
  "deploy": {
    "startCommand": "npm start",
    "healthcheckPath": "/healthz",
    "healthcheckTimeout": 100,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 5
  }
}

Private Networking Across Microservices

Connecting internal services securely using Railway private domains:

// Using internal private networking domain (zero public exposure)
const databaseUrl =
  process.env.DATABASE_PRIVATE_URL ||
  "postgresql://postgres:secret@postgres.railway.internal:5432/railway";

const redisUrl =
  process.env.REDIS_PRIVATE_URL ||
  "redis://default:secret@redis.railway.internal:6379";

Railway CLI Workflow

Managing environments and deploying from terminal:

# Log in to Railway account
railway login

# Link local directory to Railway project
railway link

# Run command locally with remote environment variables injected
railway run npm run migrate

# Trigger deployment from local branch
railway up

Common Patterns

Nixpacks Configuration with Custom System Packages

Problem: Applications requiring system packages (e.g. ffmpeg, graphicsmagick) fail to build on standard container buildpacks.

Solution: Specify custom runtime packages in nixpacks.toml:

[phases.setup]
nixPkgs = ["nodejs-20_x", "ffmpeg", "openssl"]

[phases.build]
cmds = ["npm run build"]

[start]
cmd = "npm start"

Best Practices

Do:

  • Use Railway Private Networking (*.railway.internal) for service-to-service communication.
  • Define an explicit healthcheckPath in railway.json to enable zero-downtime rolling deployments.
  • Enable PR environments to test database migrations and frontend changes in isolated stacks.
  • Utilize Nixpacks for automatic dependency and runtime version detection.

Don't:

  • Expose databases publicly when microservices reside within the same Railway project.
  • Commit .env files; use Railway's encrypted environment variables dashboard or CLI.
  • Store persistent file uploads on the service container filesystem; use S3, R2, or Railway Volume mounts.

Troubleshooting

ErrorCauseSolution
Deploy failed: Process did not listen on $PORTWeb service hardcoding port instead of dynamic Railway $PORT.Bind web server to dynamic port: process.env.PORT || 3000.
Database connection timeout in productionService connecting using public database proxy URL inside the same Railway project.Use private internal DNS host provided by Railway for zero latency and free egress.
Railway CLI: UnauthorizedProject token or user token missing.Run railway login or export RAILWAY_TOKEN.

References

More from this repository10