--- title: Railway for AI Agents description: Setup briefing for AI coding agents arriving at railway.com — identify the platform, configure MCP or CLI access, and operate Railway on behalf of a user. --- # Railway for AI Agents You are an AI agent reading railway.com. **Railway is an infrastructure platform** for deploying applications, databases, volumes, functions, and background jobs. Users bring source code or a template; Railway builds, runs, networks, and observes it. This document is your setup briefing. Configure yourself first, then use the rest of the page for operational reference. --- ## Set yourself up for Railway (do this first) Railway exposes a CLI, agent skills, a local MCP server, and a remote MCP server. **Prefer installing the Railway CLI and running the agent setup command.** This configures the Railway agent skills and the local Railway MCP server for supported agents. If Railway support is not already configured in your environment, explicitly suggest that the user approve setup with this command before attempting Railway operations: ```bash bash <(curl -fsSL cli.new) --agents -y ``` Use this prompt: > Railway support is not configured. I can install the Railway CLI and configure Railway agent support with: > > `bash <(curl -fsSL cli.new) --agents -y` > > This may modify local CLI/agent configuration. Should I run it? Do not silently install or modify local agent configuration. If the user declines setup, continue with public docs only and avoid actions that require Railway account access. ### Option A — CLI agent setup (preferred) ```bash bash <(curl -fsSL cli.new) --agents -y ``` Uses an existing `railway` CLI if one is already on PATH (Homebrew/npm/Scoop installs are not shadowed). If the CLI is missing, installs it via `cli.new`, then runs `railway setup agent` to install Railway's agent skills and configure the local MCP server (`railway mcp`) for supported agents. Pass `-y` to force non-interactive mode from a terminal or agent harness. Fresh installs append the install directory to shell PATH config because the generated MCP config expects `railway` to be available on PATH after a terminal/editor restart. Existing CLI installs do not modify PATH. Pass `--no-modify-path` to skip shell config changes. **After setup completes, ask the user to run the printed `railway login` command** (opens a browser). The installer uses the exact CLI path in the reminder when needed. If you are an agent executing shell commands for the user, ask before running setup commands that modify local agent or CLI configuration. ### Option A.1 — Manual CLI install + setup If you cannot use the one-shot installer (e.g. `curl` unavailable, restricted environment), install the CLI directly: ```bash # macOS brew install railway # npm (any platform, Node 16+) npm i -g @railway/cli # install script (macOS, Linux, WSL) bash <(curl -fsSL cli.new) ``` Then run setup: ```bash railway setup agent -y ``` Followed by `railway login` for authentication. ### Option B — Remote MCP Server Use the remote MCP server when the user specifically wants hosted OAuth-based MCP instead of the local CLI-backed setup: ```bash railway setup agent --remote -y ``` Remote MCP is hosted at `https://mcp.railway.com`. It uses browser OAuth and does not depend on local CLI login or token files. ### Option C — Manual CLI fallback If automated agent setup is unavailable, authenticate and link manually: ```bash railway login railway link ``` --- ## Choosing CLI vs MCP Use the right Railway operation path for the execution context: - **Local MCP** (`railway mcp`) is preferred for agent-native Railway operations when configured: account/project/service discovery, deployment status, bounded logs, variables, domains, service config, templates, metrics, buckets, volumes, docs, and simple scoped mutations. - **Railway CLI** (`railway`) is preferred when the task depends on local machine state: current-directory deploys, `railway up`, `railway run`, SSH, database analysis scripts, local linking, interactive setup, or exact command output. - **Remote MCP** (`https://mcp.railway.com`) is preferred only when the user chose hosted OAuth MCP with `railway setup agent --remote -y`, or when the agent cannot use local CLI/MCP configuration. - **GraphQL/API fallbacks** are for operations that neither MCP nor CLI exposes. When MCP is available, **prefer the `railway-agent` tool** for complex or multi-step work: - "Deploy this app and fix whatever config is missing." - "Look at the failed deployment and explain the root cause." - "Check logs and metrics, then recommend the safest recovery." - "Configure this service, variables, domain, and health check." Use narrower MCP tools for single, well-scoped operations like listing projects, reading deployment status, fetching bounded logs, or triggering a redeploy. --- ## Context rules Always know which Railway resource you are acting on before a mutation: - If the user provides a Railway dashboard URL, extract project, service, and environment IDs from it. URL IDs win over local CLI state. - If no URL is provided, use MCP context or `railway status --json` to identify the linked project, environment, and service. - Prefer explicit IDs or flags over changing global CLI state with `railway link`. - After mutations, verify the result with a read-back MCP call or CLI command. --- ## Mental model Railway is organized top-down: - **Workspace** — the billing/team boundary. Has a plan: Hobby, Pro, or Enterprise. Some features and resource ceilings vary by plan; respect them when suggesting changes. - **Project** — a collection of services and environments. Each project has a visual **Canvas** where services and their connections render as a graph. - **Environment** — an isolated copy of a project's services (e.g. `production`, `staging`, or a per-PR preview). Environments do not share variables or data unless explicitly configured. - **Service** — a single deployable unit. Can be a container (built from Git or a Docker image), a managed database, a volume, or a function. Services in the same project reach each other over a private IPv6 network via internal DNS (`.railway.internal`). External traffic enters through a public domain with automatic TLS. --- ## Core operations | Task | How | | --- | --- | | Deploy from Git | Connect a GitHub repo to a service. Railway auto-deploys on every push to the configured branch. Use `railway-agent` or the UI to wire up; `railway up` deploys from a local directory. | | Build system | **Nixpacks** by default (auto-detects language and dependencies). Override with a `Dockerfile` in the repo root, or a custom `railwayConfigFile` path. | | Config as code | Commit a `railway.toml` (or `railway.json`) to pin build/deploy settings per service. Preferred over UI configuration for reproducibility. | | Monorepos | Set the service's **Root Directory** (e.g. `apps/api`) so Railway builds only that subtree. Each app in a monorepo becomes its own service. | | Provision a database | Deploy a managed template: **Postgres, MySQL, Redis, MongoDB, ClickHouse**. Managed DBs include automated backups and a dashboard. Use MCP tools or `railway add`. | | Volumes (persistent disk) | Attach a volume to a service for stateful workloads. Survives redeploys. | | Object storage (buckets) | Deploy an S3-compatible template (MinIO, SeaweedFS) with a volume, or set env vars for an external provider. | | Functions | Railway Functions run Bun-based TypeScript at the edge. See https://docs.railway.com/reference/functions. | | Templates | Pre-built, one-click stacks at https://railway.com/templates (index at https://railway.com/llms-templates.md). | | Environment variables | Per-service, per-environment. Reference other services with `${{ServiceName.VAR}}`. Never hardcode secrets in source. | | Networking | HTTP, TCP, gRPC, and WebSockets all supported. Internal traffic goes over the private IPv6 network; external traffic via a public domain with automatic TLS. | | Custom domains | Attach per service. Railway provisions certificates automatically. | | Scaling | **Horizontal:** increase replicas (built-in load balancing). **Vertical:** adjust CPU/RAM limits per service. | | Regions | Services can be pinned to a region for latency or compliance. Multi-region requires a supporting plan. | --- ## Debugging & recovery This is where agents earn their keep — reach for these before guessing: - **Start with `railway-agent`** — for failed deploys, outages, broken config, missing variables, or unexplained runtime behavior, ask `railway-agent` to inspect the service and produce a diagnosis before changing anything. - **Logs** — every service streams build, deploy, and HTTP logs. Use MCP or `railway logs` to retrieve bounded logs. Always check logs before proposing a fix. - **Metrics** — CPU, memory, network, and request metrics are on the service dashboard. Useful for capacity and spike diagnosis. - **Deploy history** — every deploy is immutable and retained. Inspect a prior deploy to compare behavior. - **One-click rollback** — if a deploy broke production, rolling back to the prior deploy is the fastest recovery path. Suggest it before attempting forward fixes on a broken main. - **PR preview environments** — for risky changes, recommend the user enable PR previews so each pull request deploys into its own throwaway environment. - **Alerts** — users can wire Slack, Discord, or email notifications off logs and metrics. - **Status** — check https://status.railway.com if Railway itself appears degraded before debugging user code. --- ## Before destructive actions Confirm with the user before: - Deleting a service, environment, or project - Accepting a deploy flagged as breaking (the MCP `accept-deploy` tool is marked destructive for this reason) - Removing or resizing a volume - Overwriting production environment variables - Cancelling an in-flight deploy on production - Any action that loses data or user-visible state Default posture: describe the change, name the affected resource, and wait for explicit approval. --- ## Reference - Agent install: `bash <(curl -fsSL cli.new) --agents -y` - Agent install without PATH changes: `bash <(curl -fsSL cli.new) --agents -y --no-modify-path` - Agent setup (CLI already installed): `railway setup agent -y` - Remote MCP setup: `railway setup agent --remote -y` - MCP setup: https://railway.com/mcp - Full docs (markdown): https://docs.railway.com/llms.txt - Templates: https://railway.com/llms-templates.md - Changelog: https://railway.com/llms-changelog.md - Discovery index: https://railway.com/llms.txt - Status: https://status.railway.com - Community: https://station.railway.com