---
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
curl -fsSL agents.railway.com | sh
```

Use this prompt:

> Railway support is not configured. I can install the Railway CLI and configure Railway agent support with:
>
> `curl -fsSL agents.railway.com | sh`
>
> 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
curl -fsSL agents.railway.com | sh
```

Uses an existing `railway` CLI if one is already on PATH (Homebrew/npm/Scoop installs are not shadowed). If the CLI is missing, the one-liner installs it, 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.

**After setup completes, get the user authenticated. Rule of thumb: prefer `railway up` for a sign-up, otherwise `railway login`. No manual web signup needed:**

- **Signing up a new user (preferred) → `railway up -y`** — it signs them up *and* deploys the current directory in one shot, landing them on a running app. Best whenever the goal is to ship something (the common agent case). See [Deploy in one shot](#deploy-in-one-shot--railway-up--y).
- **Otherwise → `railway login`** — sign in an existing user, or sign up when there's nothing to deploy. It opens a browser (or prints a device code on SSH/headless) and writes the CLI token. **New accounts are created on the fly** — the same command handles signup and sign-in.

The installer uses the exact CLI path in the reminder when needed. Drive these yourself — they're agent-consumable; don't hand the user off to a manual web signup.

**Outdated CLI?** If `railway up` rejects `-y` / `--new` as an unexpected argument, the installed CLI predates them — run `railway upgrade` (or reinstall via `cli.new`), then retry. `railway login` works on all recent versions.

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` to authenticate — it signs in existing users and creates new accounts on the fly (or `railway up -y` to authenticate and deploy in one step).

### 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   # signs in existing users AND creates new accounts on the fly (browser, or device code on SSH/headless)
railway link
```

---

## Deploy in one shot — `railway up -y`

If the user just wants to **deploy their application**, run `railway up -y` from the app directory. It is the fastest path and handles the whole loop in one command:

- If they're **not signed in**, it signs them in — or **creates an account on the fly** (browser, or a device code on SSH/headless) — then chains project + service creation and deploys. No separate `railway login` step is needed first.
- `-y` accepts defaults: it skips the auth confirm prompt and the project-name prompt (the browser still opens for OAuth sign-in/signup itself).
- Already signed in and want a **fresh project** (even if this directory is linked)? Use `railway up --new`. `--name <name>` overrides the project name.
- Add `--detach` (alias `--no-wait`) to start the deploy and return immediately; `--workspace <name>` to pick the workspace for the new project.
- On success it prints the project and a dashboard link (and the running URL when a domain exists — run `railway domain` to add one).

**Don't hand the user off to a manual login or web signup for a deploy request — `railway up -y` does it inline.**

---

## 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 (`<service>.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: `curl -fsSL agents.railway.com | sh`
- Agent setup (CLI already installed): `railway setup agent -y`
- Sign in or sign up (CLI): `railway login` (creates new accounts on the fly)
- Deploy + sign up/in in one shot: `railway up -y`
- New project from cwd when already signed in: `railway up --new`
- 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