railway code

Launch Claude Code, Codex, or Grok CLI on a cloud agent and hand your terminal to it.

The code command requires cloud agents to be enabled for your account through Priority Boarding. It's under active development, and its commands and flags may change in breaking ways.

Usage

railway code [OPTIONS] [-- <AGENT_ARGS>...]

railway code is the launcher on its own. railway ca opens a terminal interface over the same launcher, reads the same preferences, and takes the same options.

Options

Option	Description
`--claude`	Launch Claude Code, minting a token with `claude setup-token`
`--codex`	Launch Codex using `~/.codex/auth.json`
`--grok`	Launch Grok CLI using `~/.grok/auth.json`
`--new`	Create a fresh agent instead of reusing this environment's
`--keep-awake`	Leave the agent running on disconnect instead of sleeping it
`--rm`	Destroy this environment's agent and exit
`--refresh-auth`	Re-mint the Claude credential on an agent that already has one
`--name <NAME>`	Name a newly created agent
`--variable <KEY=VALUE>`	Set a variable on a newly created agent (repeatable)
`--env-file <PATH>`	Load variables from a `.env` file (repeatable)
`-p`, `--project <PROJECT>`	Project ID
`-e`, `--environment <ENVIRONMENT>`	Environment name or ID

With no agent option, railway code launches the coding agent saved by railway ca setup. Set RAILWAY_CA_AGENT to override the saved agent for one run.

Where the agent runs

Railway resolves the target project and environment in this order:

The --project and --environment options.
The default project saved by railway ca setup.
The linked project in the working directory.
railway ca setup, which Railway opens for you. Setup saves the answer, so later launches skip this step.

Within that environment, Railway reuses the agent it remembers, adopts your existing agent when there's no local record, and creates one when you have none. See Reuse and create agents.

Railway reads your local credential, tells you which one it's using, and writes it to the agent over SSH. It doesn't store the credential: it never becomes a Railway variable, part of an image, or an argument on a command line.

Claude Code needs a token minted for the VM, because its local sign-in uses a rotating refresh token. Railway runs claude setup-token for you, caches the result, and reuses it on later launches. Set CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY to supply your own instead.

Codex and Grok CLI read their local auth.json, so a missing sign-in fails before Railway creates a machine.

Running railway logout deletes the cached Claude token from your machine.

Agent arguments

Arguments after -- pass through to the coding agent. Railway runs them and exits when the agent finishes, rather than leaving you in a session:

railway code --codex -- exec "explain this codebase"

To start an interactive session with a task already handed to the agent, use the prompt in railway ca.

Examples

Launch your configured agent

railway code

railway code --codex

Force a fresh agent

railway code --codex --new

Create an agent with variables

railway code --codex --new --variable DATABASE_URL=postgres.DATABASE_URL

Values can reference variables from other services in the environment. Railway resolves them when the agent is created, so pair --variable with --new.

Create an agent from a variables file

railway code --codex --new --env-file .env

Keep the agent running after you disconnect

railway code --claude --keep-awake

A running agent bills for compute even when nothing is connected to it.

Destroy the agent

railway code --rm

This deletes the agent for the target environment along with its disk.