DOCSEARCHbyAlgolia
Submit Docs

Railway Documentation

website·Indexed 28 days ago

https://docs.railway.com/

Quick start guide for deploying projects via GitHub, Railway CLI, or Docker images. Includes documentation on the Railway canvas, template deployment, core infrastructure concepts, and best practices for optimizing services.

Tokens
176.9K
Snippets
302
Records
888
Agent score
0%

What's inside Railway

  1. Overview of Railway Public API tokens and scopes

    The Railway Public API is a GraphQL API used for integrating Railway into CI/CD pipelines and workflows. There are four types of tokens available:

    Token TypeScopeBest For
    Account tokenAll resources and workspacesPersonal scripts, local development
    Workspace tokenSingle workspaceTeam CI/CD, shared automation
    Project tokenSingle environment in a projectDeployments, service-specific automation
    OAuthUser-granted permissionsThird-party apps acting on behalf of users

    Endpoint URL: https://backboard.railway.com/graphql/v2

  2. Overview of Railway Metal infrastructure

    Railway Metal is Railway's proprietary cloud infrastructure built on hardware owned and operated by Railway in datacenters globally.

    Key Benefits:

    • Regional Availability: Available to all users, including Trial & Hobby plans, across regions in the US, Europe, and Southeast Asia.
    • Cost Reductions: Once Generally Available, users can expect up to 50% less for Network Egress and up to 40% less for Disk Usage.

  3. Overview of Railway Storage Buckets

    Railway Buckets are private, S3-compatible object storage buckets used for file uploads, static assets, or backups. They provide durable object storage without requiring external providers.

    Key Features

    • S3 Compatibility: Works with standard S3 protocols.
    • Custom Naming: You can choose a custom display name. The actual S3 bucket name is the display name plus a short hash to ensure uniqueness.
    • Region Selection: You must select a region at creation; the region cannot be changed after the bucket is created.

    Creation

    To create a bucket:

    1. Click Create on the canvas.
    2. Select Bucket.
    3. Select a region and optionally provide a name.

  4. Overview of Railway storage options

    Railway provides three primary ways to persist data:

    • Databases: Deploy PostgreSQL, MySQL, Redis, MongoDB, or any open-source database via Docker images and templates.
    • Volumes: Persistent storage attached directly to your services.
    • Storage Buckets: S3-compatible object storage for files and assets.

  5. Overview of Railway AI Integration options

    Railway provides several ways to manage infrastructure using natural language and AI:

    • Railway Agent: A chat-based assistant built into the Railway dashboard. It can create services, configure variables, diagnose failed deployments, and open pull requests with proposed fixes.
    • Agent Integrations: Brings the Railway Agent into Slack and Discord (Beta).
    • Agent Skills: An open format (e.g., use-railway) for extending assistants like Claude Code, Cursor, and OpenAI Codex with specialized Railway knowledge.
    • Claude Code Plugin: A specialized plugin for Claude Code that includes the use-railway skill, hooks, and supporting scripts.
    • MCP Server: Implements the Model Context Protocol for direct communication between AI assistants and Railway infrastructure.

  6. Overview of Railway Infrastructure as Code (IaC)

    Railway Infrastructure as Code (IaC) allows you to define services, databases, volumes, buckets, custom domains, environment variables, replicas, and canvas groups using a TypeScript file located at .railway/railway.ts.

    IaC vs Config as Code

    FeatureScopeFile
    Config as CodeOne service deploymentrailway.json or railway.toml
    Infrastructure as CodeA Railway project/environment.railway/railway.ts

    Important Constraints:

    • Config as Code is read from your service repository during deploy and overrides dashboard values.
    • IaC is evaluated by the Railway CLI.
    • A service cannot be managed by both systems at the same time. If a service is managed by railway.json or railway.toml, you must migrate it before IaC can manage it.

  7. Use Railway Functions for TypeScript code

    Railway Functions are services that run a single file of TypeScript code using the Bun runtime. They are ideal for small, short-lived tasks like webhooks, cron jobs, or simple APIs without the overhead of a full repository.

    Key Features:

    • Instant Deploys: No build step required.
    • NPM Support: Import any package using package@version syntax (e.g., import { Hono } from "hono@4").
    • Native Bun APIs: Access Bun.file(), Bun.serve(), etc.
    • Environment Variables: Available via import.meta.env, process.env, or Bun.env.
    • Persistence: Can attach Volumes to persist data.

    Limitations:

    • Maximum of 1 file per function.
    • Maximum file size of 96KB.

    Workflow:

    1. Open the "Source Code" tab in your service to edit.
    2. Stage changes: ⌘+S (Mac) or Ctrl+S (Windows).
    3. Deploy staged changes: Shift+Enter.

  8. Connect AI coding agents to Railway via MCP

    You can connect AI coding agents (like Cursor, VS Code, Claude Code, or Windsurf) to Railway using the Model Context Protocol (MCP). This allows agents to manage projects, deploy services, and manage environments using natural language.

    There are two connection methods:

    1. Local MCP: Runs through the Railway CLI on your machine. It shares the CLI's authentication and project context. Recommended for most coding-agent workflows.
    2. Remote MCP: A hosted endpoint at mcp.railway.com. No local install or CLI is required; clients authenticate via OAuth in the browser.

    Prerequisites

  9. Compare SSE and WebSockets for Real-time Data on Railway

    When choosing a real-time protocol for Railway, consider the following:

    Server-Sent Events (SSE)

    • Best for: AI/LLM token streaming, live dashboards, and notification feeds.
    • Direction: Unidirectional (Server to client).
    • Protocol: Standard HTTP/1.1.
    • Reconnection: Built into the browser's EventSource API.
    • Railway Constraints: Subject to request limits. Connections can last up to 15 minutes with keep-alive heartbeats, but will close after 5 minutes of inactivity. Recommendation: Send a heartbeat (e.g., an SSE comment) at least every 5 minutes.

    WebSockets

    • Best for: Chat, multiplayer games, and collaborative editing.
    • Direction: Bidirectional.
    • Protocol: HTTP/1.1 upgrade to ws://.
    • Reconnection: Must be implemented manually on the client.
    • Railway Constraints: Exempt from request timeouts and can stay open indefinitely, even while idle.

  10. Core Features and Capabilities of Railway

    Railway is a managed platform designed to eliminate the operational overhead associated with traditional VPS hosting. Key capabilities include:

    • Zero-Configuration Deployment: Automatic builds from GitHub, dependency auto-detection, and built-in support for major programming languages/frameworks.
    • Managed Infrastructure: Automatic OS/security patches, built-in load balancing, and automatic scaling.
    • Security: Encrypted secret/environment management, SSL/TLS encryption for all services, private networking, and DDoS protection. Railway is SOC 2 Type II, GDPR, and HIPAA compliant.
    • Observability: Built-in dashboards for CPU, memory, and network metrics, integrated log aggregation/search, and auto-alerting/notifications.
    • Scalability: Automatic vertical scaling (no downtime) and effortless horizontal scaling via service replicas with automatic load balancing.
    • CI/CD: GitHub integration with preview environments per pull request and one-click rollbacks.

  11. Earn commissions as an Open Source partner on Railway

    Open source maintainers can earn commissions when users deploy their technology on Railway via the template marketplace.

    Commission Rates:

    • Base rate: 15% of usage from your verified templates.
    • Support bonus: An additional +10% (25% total) when you answer user questions in the Template Queue.

    To apply for partnership, visit railway.com/partners. Projects must be open source or open-core.

  12. Build and deploy with Railpack

    Railpack is Railway's zero-configuration build tool that analyzes source code to automatically detect the programming language, install dependencies, and configure build/start commands. It packages the application into an optimized container image.

    Supported Languages

    Node, Python, Go, PHP, HTML/Staticfile, Java, Ruby, Deno, Rust, Elixir, and Shell scripts.

    Customization

    While it works with zero configuration, you can customize the build process using:

    • Environment variables
    • A Railpack config file