Use railway ca to browse and manage VMs, railway code to launch a coding
session, and railway ca desktop to configure a desktop app. Run any command
with --help for its options.
railway code # new VM with railway-agent-tui
railway code --codex
railway code --opencode
railway code --claude
railway code --codex connect my-boxOpenCode is OpenCode V2. The cloud-agent image ships the official V2 opencode
and railway code --opencode runs it directly; the CLI never installs or
upgrades OpenCode on an agent. OpenCode 1 is not supported, and the earlier
--opencode2 edition flag no longer exists. The launcher and setup wizard offer
one OpenCode option; preferences, saved connections, and VM history recorded
as opencode2 by earlier releases are read as OpenCode.
An agent created from an older image still has OpenCode 1.x. Starting or resuming an OpenCode session on it stops with:
This cloud agent is on an older image whose OpenCode is not V2. Create a new agent with railway code --opencode --new.
railway code --opencode connect <agent> reconnects to a V2 server the CLI
started. A server an earlier CLI started as OpenCode 1 is not reconnected;
create a new agent. Railway verifies local client versions and, when needed,
installs a matching client privately under
~/.railway/runtimes/opencode-client/<version>.
Desktop setup detects the installed app's bundled client version independently of its release channel and configures only a V2 app, preferring stable OpenCode when both channels qualify.
Bare railway code opens railway-agent-tui on a new VM. An explicit agent
flag also creates a new VM unless connect or --agent selects an existing
one. connect [agent] connects to an existing
Codex/OpenCode server; --agent <name-or-id> selects a VM for server setup.
The local Railway Agent client checks for updates on each launch. If GitHub rate-limits the check, the CLI retries with available GitHub authentication. If the update check still fails, including when offline, it uses the newest working client already installed on your machine.
Codex and OpenCode normally run a local client connected to the VM. Their clients run inside the Railway CA interface with command approvals disabled. Codex matches the local client to its server version and trusts the remote project. Missing OpenCode clients can be installed after confirmation. On the VM, OpenCode is the image's official V2 runtime. Both local clients follow the server's recorded release.
Use remote to run the client on the VM. Use -- to pass arguments to the agent:
railway code --codex remote
railway code --codex -- exec "explain this codebase"railway ca --codex and railway ca start --codex launch on the VM and do not
use code's local-client actions. ca start also skips the management interface.
These CA paths do not automatically request a fresh VM; use --new when needed.
railway ca setup saves the default agent, project, and skills. Explicit flags
win over preferences. RAILWAY_CA_AGENT overrides the saved agent for one run.
A directory's linked project takes precedence over the saved default project.
Preferences live in ~/.railway/agent-prefs.json.
Agent selectors accept names or IDs. Lifecycle commands without a selector use this directory's agent or your only agent, otherwise show candidates.
An agent sleeps after 5 idle minutes: no SSH client attached, almost no
network traffic, and no coding agent working or waiting. Sleeping ends its
processes, including commands left running in a detached session, and keeps the
disk; connecting wakes it. Agents created before October 8, 2026 don't sleep on
their own. railway ca sleep <agent> sleeps one now.
railway ca delete <agent> deletes the VM and its disk.
The older railway code --rm deletes this environment's agent and disk.
Use railway ca ssh <agent> for a shell, --session [name] to attach to or start
a terminal session, and --resume to resume the most recent Claude conversation
in a fresh terminal session after sleep or restart.
In the management interface, Option+F toggles the tree. Option+N opens the new-VM
picker from an existing session, with agent, bootstrap, and project selection.
It starts with the current VM's project and environment and creates a fresh VM.
Piped sessions and agent arguments after -- use the terminal directly.
Interactive railway code starts show provisioning, configuration, and client
preparation in the session pane's loading screen for every agent. The sidebar's
projects section opens by default and lists all accessible projects, including
those already hosting agents. Select a project or environment and press n to
create an agent there.
Option+R / Alt+R is the global refresh shortcut, including discovery in unopened
projects. It works from the sidebar and inside sessions. Plain r refreshes the
selected environment when the sidebar is focused.
Grok uses the shared generated name format, such as grok-railg-3ed, unless
--name is supplied. Each Grok launch runs the official updater
on the VM to install the latest stable release before opening the session. An
update failure stops the launch with an error so it cannot silently run an old
version. Credentials, skills, and MCP settings remain in their existing locations.
Grok starts with --trust --always-approve inside cloud VMs: its working
directory is trusted and tool calls do not require approval. This applies to
new sessions, resumed conversations, explicit agent arguments after --, and
SSH autostart. Existing VMs receive the updated autostart on their next
railway code provision. Local Grok settings are unchanged; already-running
sessions must be restarted to pick up the launch flags.
Local sign-ins are optional: without one, sign in using the agent's login flow
on the VM. When available, Codex copies ~/.codex/auth.json, Grok copies
~/.grok/auth.json, and OpenCode carries the active account per provider from
its local V2 credential store (~/.local/share/opencode/opencode.db) into the
VM's store.
Claude uses a setup token from claude setup-token, or the supplied
CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_API_KEY. The CLI can mint the setup token
and caches it locally in ~/.railway/claude-code-token. It reuses a credential
already on the VM. --refresh-auth replaces the cached credentials with a newly
minted token; use it after revoking a token or when authentication fails.
railway logout clears the local token cache.
Railway Agent uses credentials already on the VM and needs no separate model provider sign-in.
railway ca desktop --claude
railway ca desktop --codex
railway ca desktop --opencode --agent my-box
railway code --codex desktop-only --agent my-box --dir /appDesktop setup uses an existing VM when available, creating one if needed.
--new requests a fresh VM; --agent selects an existing one.
railway ca desktop --codex alone is an alias for Codex desktop-only setup.
Setup writes configuration without opening the desktop app. Restart the app to
load the connection. An idle VM sleeps after 5 minutes and connecting wakes it;
Claude and Codex just reconnect. Agents created since October 8, 2026 restart
the OpenCode server on wake, so reconnecting usually works; if it can't connect,
rerun railway ca desktop --opencode.
Normal railway code Codex setup and connect also configure Desktop in the
background. OpenCode setup and connect configure the matching Desktop edition
when its settings are detected. The command reports configuration success or
failure.
Claude and Codex use generated SSH configuration. --ssh-config selects the file.
Codex also saves its connection and remote project in
$CODEX_HOME/codex-app/config.json (default ~/.codex/codex-app/config.json).
After restarting Codex, find Railway: <agent-name> in the project sidebar.
OpenCode uses a public HTTPS endpoint. New VMs request a code endpoint on port
4096; existing VMs use their configured endpoint or app port 8080. Setup saves
the URL, credentials, default server, and project in the selected Desktop edition.
Open Home → Projects → Railway: → /app (or the selected --dir) →
New session. Changing the default server does not move existing chats.
An occupied server port causes setup to fail without stopping its process.
--dry-run previews changes without changing local configuration or the VM.
--remove removes local Desktop configuration and stops the managed OpenCode
server on a running VM. For Codex it removes the import declaration; remove
already-imported hosts and projects in Settings → Connections and the sidebar.
railway code get-config
railway code get-config my-box --json
railway code --codex connect my-box --connection-jsonget-config shows local snapshots without login, network access, or waking a VM.
It does not verify that a saved connection still works. Omit the selector for the
latest snapshot; use an ID when names are ambiguous. Snapshots contain credentials
and are removed by railway logout.
--connection-json returns verified connection details including credentials for
Codex or OpenCode, without opening a local client. Progress goes to stderr.
It works with setup, connect, and Codex desktop-only.
railway ca bootstrap save dev --agent my-box --default
railway code --codex --bootstrap dev
railway ca create my-box --from-checkpoint <checkpoint-id>railway ca bootstrap list shows saved names, capture status, and last-saved
times. An asterisk marks this machine's default. Use --environment staging
to select another environment or --json for structured output.
Bootstraps capture running VMs for reuse. Saving the same name creates a new
version. Save waits for the capture to finish, and --default changes only after
success. Variables supplied with --variable or --env-file are saved with the
bootstrap; explicit variables override matching file entries.
railway ca bootstrap default dev selects a ready bootstrap as this machine's default for future VM creation in the environment; existing VMs are
unaffected. --no-bootstrap skips the default.
--from-checkpoint on ca create accepts a cloud-agent checkpoint ID and bypasses
the default bootstrap.
--variable sets creation-time variables and supports comma-separated values,
repeated flags, and service references such as DB_URL=postgres.DATABASE_URL or
DB_URL=${{postgres.DATABASE_URL}}. Quote the latter in a shell. Repeat
--env-file to load files; --variable overrides matching file entries.
Local clients request their code endpoint automatically. When configuring one
explicitly on railway code or ca start, --code-endpoint and --code-port
require an explicit --new, even when the launcher would create a VM by default.
In the railway ca main screen, press n for a new VM. Below the agent list,
use the arrow keys and Enter or click to toggle Use bootstrap. When enabled,
Select Bootstrap appears below it (b opens the list). Select Project
(p) chooses the project and environment for this VM, with the saved default
project first. This choice does not change your saved default project.