# Railway

> Complete Railway.com platform documentation for deploying, configuring, and managing applications. Use this skill for Railway CLI commands, API usage, deployment guides, database setup, networking, volumes, troubleshooting, and framework-specific deployment configurations for Node.js, Python, Go, Ruby, PHP, Java, Rust, and Elixir.

- Skill: `taxi-tabby/railway` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add taxi-tabby/railway`
- Raw SKILL.md: https://api.skillmd.com/api/skills/taxi-tabby/railway/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: taxi-tabby (https://skillmd.com/u/taxi-tabby)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/taxi-tabby/railway

---


# Railway Platform - Skills Documentation

This documentation provides comprehensive information about Railway.com for LLM-based assistants to help users deploy, configure, and manage applications on the Railway platform.

**Last Updated:** 2026-01-23
**Source:** https://docs.railway.com

---

## Documentation Structure

**IMPORTANT:** This skill includes modular documentation files. When you need detailed information, read the appropriate file using the Read tool:

- **api.md** - Complete GraphQL API reference with authentication, queries, mutations, and examples
  - Read this file when user asks about: API usage, GraphQL queries, mutations, authentication tokens, rate limits

- **projects.md** - Project structure, environment management, services, deployments, and team collaboration
  - Read this file when user asks about: project organization, environments, services, team management, templates

- **frameworks.md** - Framework-specific deployment guides for Node.js, Python, Go, Ruby, PHP, Java, Rust, and Elixir
  - Read this file when user asks about: deploying specific frameworks, framework configuration, language-specific setup

**Usage:** When a user question requires detailed information from these topics, use the Read tool to load the relevant file from `.claude/skills/railway/` directory.

---

## Table of Contents

1. [Platform Overview](#platform-overview)
2. [Core Concepts](#core-concepts)
3. [Quick Start](#quick-start)
4. [CLI Reference](#cli-reference)
5. [API Reference](#api-reference)
6. [Configuration](#configuration)
7. [Networking & Domains](#networking--domains)
8. [Databases & Volumes](#databases--volumes)
9. [Best Practices](#best-practices)

---

## Platform Overview

**Railway** is a modern cloud deployment platform that enables instant application deployment with zero-configuration builds and efficient scaling capabilities.

### Key Features

- **Zero-Configuration Deployments**: Automatic language and framework detection
- **Railpack Build System**: Automatic code analysis and container image generation
- **Private Networking**: WireGuard mesh network for inter-service communication
- **Multiple Deployment Sources**: GitHub, Docker images, local directories
- **Built-in Databases**: PostgreSQL, MySQL, Redis, MongoDB templates
- **Instant Scaling**: Vertical autoscaling and horizontal replicas
- **CLI & GraphQL API**: Comprehensive automation support

### Deployment Methods

1. **GitHub Integration** - Auto-deploy on git push
2. **Docker Images** - Public/private registries support
3. **CLI Deployment** - `railway up` command
4. **Templates** - One-click deployments from marketplace

---

## Core Concepts

### Projects

Projects are infrastructure containers that hold all application components. **See [projects.md](./projects.md) for complete details.**

Key features:
- **Services** - Individual application deployments
- **Environments** - Isolated deployment contexts (production, staging, etc.)
- **Variables** - Configuration management
- **Activity Feed** - Change tracking
- **Collaboration** - Team member access control

### Services

Services are deployment targets for applications:
- Deploy from GitHub repos, Docker images, or local directories
- Each service gets its own configuration and variables
- Supports horizontal scaling with replicas
- Can attach one volume for persistent storage
- Automatic or manual deployment triggers

### Environments

Isolated instances of project infrastructure:
- Default `production` environment included
- Create additional environments (staging, development)
- Each environment has separate variables and deployments
- **PR Environments**: Temporary instances for pull requests (auto-created/deleted)
- Environment syncing to propagate services between environments

### Variables

Configuration management system:
- **Service Variables**: Scoped to individual services
- **Shared Variables**: Referenced across multiple services using `${{ shared.VAR }}`
- **Reference Variables**: Cross-service references using `${{ SERVICE_NAME.VAR }}`
- **Sealed Variables**: Enhanced security - values never visible in UI
- **Platform Variables**: Auto-provided like `RAILWAY_PUBLIC_DOMAIN`, `RAILWAY_PRIVATE_DOMAIN`

---

## Quick Start

### 1. Install Railway CLI

```bash
# macOS/Linux
curl -fsSL https://railway.com/install.sh | sh

# Windows (PowerShell)
iwr https://railway.com/install.ps1 | iex

# npm
npm install -g @railway/cli
```

### 2. Login

```bash
railway login
```

### 3. Create a New Project

```bash
# Initialize new project
railway init

# Or link to existing project
railway link
```

### 4. Deploy

```bash
# Deploy from local directory
railway up

# Deploy with build logs
railway up --verbose
```

### 5. Manage Variables

```bash
# Set a variable
railway variables set KEY=value

# View all variables
railway variables

# Run command with variables
railway run npm start
```

---

## CLI Reference

### Project Management

| Command | Description |
|---------|-------------|
| `railway init` | Create a new project |
| `railway link` | Link to existing project |
| `railway list` | Display all projects |
| `railway open` | Open project dashboard in browser |
| `railway status` | View current project information |

### Environment Operations

| Command | Description |
|---------|-------------|
| `railway environment new` | Create new environment |
| `railway environment delete` | Remove an environment |
| `railway environment link` | Connect environment to project |

### Service & Deployment

| Command | Description |
|---------|-------------|
| `railway add` | Add service (database, Docker image) |
| `railway service` | Link service to current project |
| `railway up` | Upload and deploy from local directory |
| `railway deploy` | Deploy a template |
| `railway down` | Remove most recent deployment |
| `railway redeploy` | Redeploy latest deployment |

### Development Tools

| Command | Description |
|---------|-------------|
| `railway run <cmd>` | Run command with environment variables |
| `railway shell` | Open subshell with variables |
| `railway ssh` | Connect to service |
| `railway connect <db>` | Access database shell (psql, mysql, redis-cli, mongosh) |
| `railway logs` | View deployment logs |

### Configuration

| Command | Description |
|---------|-------------|
| `railway variables` | Display/modify variables |
| `railway variables set KEY=value` | Set variable |
| `railway variables delete KEY` | Delete variable |
| `railway domain` | Manage domains |
| `railway volume` | Manage persistent storage |

### Full CLI Documentation

```bash
railway --help              # Show all commands
railway <command> --help    # Command-specific help
```

---

## API Reference

Railway provides a **GraphQL API** for programmatic access. **See [api.md](./api.md) for complete API documentation.**

### Quick Reference

**Endpoint:** `https://backboard.railway.com/graphql/v2`

**Authentication:**
```bash
curl --request POST \
  --url https://backboard.railway.com/graphql/v2 \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"query { me { name email } }"}'
```

**Token Types:**
1. **Account Tokens** - Personal resources
2. **Team Tokens** - Team resources (Pro feature)
3. **Project Tokens** - Single environment scope

**Rate Limits:**
- Free: 100 requests/hour
- Hobby: 1,000 requests/hour, 10 requests/second
- Pro: 10,000 requests/hour, 50 requests/second
- Enterprise: Custom limits

**Common Operations:**
- Get user info: `query { me { name email } }`
- List projects: `query { workspace(workspaceId: "...") { projects { ... } } }`
- Create service: `mutation { serviceCreate(input: {...}) { id } }`
- Fetch deployments: `query { deployments(input: {...}) { ... } }`
- Manage variables: `mutation { variableUpsert(input: {...}) }`

**For complete API documentation, see [api.md](./api.md)**

---

## Configuration

### railway.json / railway.toml

Configure build and deployment behavior:

#### Basic railway.json

```json
{
  "$schema": "https://railway.com/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm run build"
  },
  "deploy": {
    "startCommand": "npm start",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 100,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}
```

#### Basic railway.toml

```toml
[build]
builder = "NIXPACKS"
buildCommand = "npm run build"

[deploy]
startCommand = "npm start"
healthcheckPath = "/health"
healthcheckTimeout = 100
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 10
```

### Build Configuration

**Builder Options:**
- `NIXPACKS` (default) - Zero-config builds
- `DOCKERFILE` - Use project's Dockerfile

**Build Settings:**
```json
{
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm run build",
    "watchPatterns": ["src/**"],
    "dockerfilePath": "./Dockerfile"
  }
}
```

### Deploy Configuration

**Deploy Settings:**
```json
{
  "deploy": {
    "startCommand": "node server.js",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 100,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10,
    "numReplicas": 2,
    "region": "us-west1"
  }
}
```

**Restart Policies:**
- `ON_FAILURE` - Restart only on failure
- `ALWAYS` - Always restart
- `NEVER` - Never restart

### nixpacks.toml

Override Nixpacks build behavior:

```toml
[phases.setup]
nixPkgs = ["nodejs-18_x", "python310"]

[phases.install]
cmds = ["npm install"]

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

[start]
cmd = "npm start"
```

---

## Networking & Domains

### Public Networking

**Railway-Provided Domain:**
- Automatically generated: `<service-name>-production-<hash>.railway.app`
- Enable in Service Settings → Networking → Public Networking

**Custom Domains:**
```bash
# Add custom domain
railway domain add example.com

# List domains
railway domain list
```

**DNS Configuration:**
- Add CNAME record: `your-subdomain.example.com` → `<service>.railway.app`
- Root domain: Add A/AAAA records provided by Railway

### Private Networking

**Automatic Service Discovery:**
- All services in same project/environment communicate via private network
- Use service name as hostname: `http://<service-name>:PORT`
- Port defined by `PORT` environment variable

**Private Networking Variables:**
- `RAILWAY_PRIVATE_DOMAIN` - Private DNS name for service
- `RAILWAY_TCP_PROXY_DOMAIN` - TCP proxy domain (if enabled)
- `RAILWAY_TCP_PROXY_PORT` - TCP proxy port

**Example:**
```javascript
// Service A connecting to Service B
const response = await fetch(`http://${process.env.BACKEND_PRIVATE_DOMAIN}:3000/api`);
```

### TCP Proxy

For TCP/UDP protocols:
1. Enable in Service Settings → Networking → TCP Proxy
2. Use `RAILWAY_TCP_PROXY_DOMAIN` and `RAILWAY_TCP_PROXY_PORT`
3. Supports: databases, game servers, custom protocols

---

## Databases & Volumes

### Databases

Railway provides one-click database templates:

**Available Databases:**
- PostgreSQL
- MySQL
- MongoDB
- Redis
- Valkey

**Adding a Database:**
```bash
# Via CLI
railway add --database postgres

# Or via Dashboard: Add Service → Database → Select type
```

**Connection Variables:**
Automatically provided after database creation:
- PostgreSQL: `DATABASE_URL`, `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`
- MySQL: `MYSQL_URL`, `MYSQLHOST`, `MYSQLPORT`, `MYSQLUSER`, `MYSQLPASSWORD`, `MYSQLDATABASE`
- MongoDB: `MONGO_URL`
- Redis: `REDIS_URL`

**Connecting from Another Service:**
```bash
# Reference database variable from another service
DATABASE_URL=${{ database-service.DATABASE_URL }}
```

### Volumes

Persistent storage for services:

**Creating a Volume:**
1. Service Settings → Volumes → Add Volume
2. Specify mount path (e.g., `/data`)
3. Volume persists across deployments

**Via CLI:**
```bash
railway volume add --mount /data
railway volume list
```

**Important:**
- Each service can attach ONE volume
- Volumes are environment-specific
- Size limit: 50GB (Hobby), 100GB+ (Pro)
- NOT shared between services (use database/object storage for shared data)

**Use Cases:**
- User uploads
- Application data
- SQLite databases
- Logs and caches

---

## Best Practices

### Environment Variables

1. **Use sealed variables for secrets** (API keys, tokens)
2. **Leverage shared variables** to reduce duplication
3. **Use reference variables** for service URLs: `${{ api.RAILWAY_PRIVATE_DOMAIN }}`
4. **Import from .env files** for easier migration
5. **Never commit secrets** to version control

### Deployment

1. **Configure health checks** for zero-downtime deployments
2. **Use PR environments** for testing before merging
3. **Set resource limits** to control costs
4. **Enable auto-sleep** for development environments
5. **Use multiple environments** (dev, staging, production)

### Networking

1. **Use private networking** for inter-service communication
2. **Enable public networking** only when needed
3. **Configure custom domains** for production
4. **Set up health checks** at `/health` endpoint
5. **Use TCP proxy** for non-HTTP protocols

### Performance

1. **Deploy in region closest** to users
2. **Use horizontal replicas** for high availability
3. **Configure cron jobs** for scheduled tasks
4. **Monitor resource usage** in Metrics tab
5. **Use volumes sparingly** (prefer databases/object storage)

### Security

1. **Use sealed variables** for sensitive data
2. **Rotate secrets regularly**
3. **Restrict environment access** (Enterprise)
4. **Review activity feed** for changes
5. **Use least-privilege API tokens** (project tokens vs account tokens)

### Cost Optimization

1. **Set usage limits** per service
2. **Enable auto-sleep** for inactive services
3. **Use appropriate instance sizes**
4. **Monitor spend** in Usage tab
5. **Clean up unused services** and environments

---

## Framework-Specific Guides

Railway supports automatic detection and deployment for many frameworks. **See [frameworks.md](./frameworks.md) for complete framework guides.**

### Supported Frameworks

**Node.js:**
- Next.js
- Express.js
- Nest.js
- Remix
- Nuxt.js

**Python:**
- Django
- Flask
- FastAPI
- Streamlit

**Go:**
- Standard library
- Gin
- Echo
- Fiber

**Ruby:**
- Rails
- Sinatra

**PHP:**
- Laravel
- Symfony

**Java:**
- Spring Boot
- Quarkus

**Rust:**
- Axum
- Actix Web
- Rocket

**Elixir:**
- Phoenix

### Quick Deploy Examples

**Next.js:**
```json
{
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "startCommand": "npm start"
  }
}
```

**Django:**
```json
{
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "python manage.py collectstatic --noinput"
  },
  "deploy": {
    "startCommand": "gunicorn myapp.wsgi"
  }
}
```

**For complete framework documentation, see [frameworks.md](./frameworks.md)**

---

## Troubleshooting

### Common Issues

#### Build Failures

**Issue:** Build fails with "command not found"
- **Solution:** Add required packages to `nixpacks.toml` or use custom Dockerfile

**Issue:** Build times out
- **Solution:** Optimize build process, increase timeout in settings, or use build cache

#### Deployment Issues

**Issue:** Service crashes immediately after deployment
- **Solution:** Check logs (`railway logs`), verify start command, check environment variables

**Issue:** Healthcheck fails
- **Solution:** Verify healthcheck path returns 200 status, increase timeout

#### Networking Issues

**Issue:** Can't connect to database
- **Solution:** Verify connection string, check if database service is running, use private domain

**Issue:** 502 Bad Gateway
- **Solution:** Ensure app listens on `0.0.0.0:$PORT`, verify app is running

### Debugging Commands

```bash
# View recent logs
railway logs

# View logs with follow
railway logs --follow

# Connect to service shell
railway ssh

# Connect to database
railway connect postgres

# Check service status
railway status

# View variables
railway variables
```

### Getting Help

1. **Documentation:** https://docs.railway.com
2. **Discord Community:** Join Railway Discord
3. **Status Page:** https://status.railway.com
4. **GitHub Issues:** Report bugs at railway-app/railway

---

## Additional Resources

- **Main Documentation:** https://docs.railway.com
- **API Reference:** See [api.md](./api.md)
- **Project Management:** See [projects.md](./projects.md)
- **Framework Guides:** See [frameworks.md](./frameworks.md)
- **GraphiQL Playground:** https://railway.com/graphiql
- **Railway Blog:** https://railway.com/blog
- **Railway Discord:** https://discord.gg/railway

---

*Last Updated: 2026-01-23*
*Documentation extracted from https://docs.railway.com*