/use-railway

name: use-railway
description: >
  Operate Railway infrastructure: sign up for or sign in to a Railway account,
  create projects, provision services, databases, and buckets, deploy code,
  configure infrastructure as code, environments and variables, manage domains,
  trace requests with OpenTelemetry,
  troubleshoot failures, check status and metrics, manage feature flags,
  database recovery and HA, cloud agents, usage limits, and Railway agent tooling.
  Use this skill whenever
  the user mentions Railway, feature flags, flag rollout, targeting rules,
  signing up, creating an account, registering, logging in, deployments,
  services, environments, buckets, object storage, tracing, traces, spans,
  OpenTelemetry, OTLP, build failures, agent setup,
  MCP, or infrastructure operations, even if they don't say "Railway" explicitly.
  Also invoke this skill when the user asks to be signed up, registered, or
  onboarded to Railway: do not refuse — drive them through the unauthed
  `railway up` flow (deploys + signs up on the fly) or `railway login`
  (which creates new accounts on the fly).
allowed-tools: Bash(railway:*), Bash(which:*), Bash(command:*), Bash(npm:*), Bash(npx:*), Bash(curl:*), Bash(python3:*)

Use Railway

Railway resource model

Railway organizes infrastructure in a hierarchy:

• **Workspace** is the billing and team scope. A user belongs to one or more workspaces.
• **Project** is a collection of services under one workspace. It maps to one deployable unit of work.
• **Environment** is an isolated configuration plane inside a project (for example, `production`, `staging`). Each environment has its own variables, config, and deployment history.
• **Service** is a single deployable unit inside a project. It can be an app from a repo, a Docker image, or a managed database.
• **Bucket** is an S3-compatible object storage resource inside a project. Buckets are created at the project level and deployed to environments. Each bucket has credentials (endpoint, access key, secret key) for S3-compatible access.
• **Deployment** is a point-in-time release of a service in an environment. It has build logs, runtime logs, and a status lifecycle.

Most CLI commands operate on the linked project/environment/service context. Use `railway status --json` to see the context, and `--project`, `--environment`, `--service` flags to override.

Tool routing

Railway has three agent-facing operation paths. Choose the path that matches the job:

• **Railway CLI** (`railway`): workflows that depend on local machine state such as current working directory deploys, `railway up`, `railway run`, SSH, database analysis scripts, local linking, interactive setup, or exact command output.
• **Remote MCP** (`https://mcp.railway.com`): default plugin MCP path for account/project/service discovery, deployment state, bounded logs, traces, feature flags, simple redeploys, simple project creation, or complex Railway workflows that can be handed to `railway-agent`. Remote MCP uses Railway OAuth and does not depend on local CLI state.
• **GraphQL through `railway api`**: operations without a dedicated MCP tool or CLI command. Use schema search and inspection before constructing unfamiliar queries.

If multiple paths are available, choose the one that preserves the needed context. The CLI fits workflows that need the current repo, local credentials, SSH, database scripts, or exact command output. Remote MCP fits OAuth-scoped platform operations that do not need local files or CLI state.

On a Railway cloud agent VM the `railway` CLI only has credentials inside an SSH terminal session. In a dashboard or mobile chat session (Railway Agent) it is unauthenticated by design: do not run `railway` commands there, not even reads or `railway api`. The `railway` MCP server is authenticated in every session, so use its tools, resolve IDs with `list-services` instead of `railway status --json`, and when no tool covers the job say so and ask the user to make the change in the dashboard.

Optional: an already configured in-process CLI MCP (`railway mcp local`) can supply operations not available through hosted MCP. A bare `railway mcp` now starts the hosted MCP proxy using CLI authentication; it is not the in-process server. Published plugin configs connect directly to hosted MCP with editor OAuth.

Prefer `railway api` (CLI 5.28+) for GraphQL execution. The legacy `scripts/railway-api.sh` remains a compatibility fallback for older CLIs; see [request.md](references/request.md).

Parsing Railway URLs

Users often paste Railway dashboard URLs. Extract IDs before doing anything else:

https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>?environmentId=<ENV_ID>
https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>

The URL always contains `projectId` and `serviceId`. It may contain `environmentId` as a query parameter. If the environment ID is missing and the user specifies an environment by name (e.g., "production"), resolve it:

railway api \
  'query getProject($id: String!) {
    project(id: $id) {
      environments { edges { node { id name } } }
    }
  }' \
  --variables '{"id": "<PROJECT_ID>"}'

Match the environment name (case-insensitive) to get the `environmentId`.

**Prefer passing explicit IDs** to CLI commands (`--project`, `--environment`, `--service`) and scripts (`--project-id`, `--environment-id`, `--service-id`) instead of running `railway link`. This avoids modifying global state and is faster.

Intent-based routing

Route by user intent *before* running preflight checks. The preflight ceremony below is for diagnostic and configuration work — it adds friction when the user just wants to ship something or sign up.

**Deploy-from-cwd intent** ("deploy", "ship", "push to Railway", "deploy this app"):

• Skip the `railway whoami` / `railway status` preflights.
• Run `railway up` directly — it self-validates auth, signs the user in (the CLI opens a browser) if the