gem-hunter

The Railway CLI lets you interact with your Railway projects from the command line. Read the CLI documentation.

Install the Railway CLI with agent support configured in one step (macOS, Linux, Windows via WSL):

bash <(curl -fsSL railway.com/install.sh) --agents -y

This installs the CLI to ~/.railway/bin and runs railway setup agent to configure detected agent tools.

To install the CLI without agent configuration:

bash <(curl -fsSL railway.com/install.sh) -y

Uninstall the CLI:

bash <(curl -fsSL cli.new) -r

Other installation methods are available in the CLI documentation: Homebrew, npm, Scoop, pre-built binaries, and source builds.

Use railway config partials list to discover named partials and their owned resource addresses. railway config partials release NAME clears a partial's ownership, and railway config partials transfer FROM TO moves it to another partial. Add repeated --resource ADDRESS options to select resources or omit them for the entire source partial. Use --dry-run to preview the exact addresses.

These commands work without the original authoring file and only change ownership metadata. See the IaC guide for confirmation, JSON/CI usage, and moving back to whole-project management.

Before using the CLI, authenticate with your Railway account:

railway login

For environments without a browser, such as SSH sessions, use browserless login:

railway login --browserless

For CI/CD pipelines, set environment variables instead of using interactive login:

• Project token: Set RAILWAY_TOKEN for project-level actions.
• Account or workspace token: Set RAILWAY_API_TOKEN for account-level or workspace-level actions.

RAILWAY_TOKEN=xxx railway up

See Tokens for more information.

Configure Railway agent support for AI coding tools:

railway setup agent -y

This installs Railway skills and configures the remote Railway MCP server (mcp.railway.com via railway mcp proxy, authenticated with your CLI login) for detected tools such as Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, Factory Droid, Pi, and Antigravity.

Use the focused commands when you only need one part of the setup:

railway mcp install --agent cursor
railway skills --agent claude-code

With automatic updates enabled, CLI-managed skills update silently in the background, including on the first normal command after a CLI version change (whether upgraded with railway upgrade or a package manager). Locally modified or deleted skills are skipped, and user-added files are preserved. Restart your coding tool to load updated skills. Use railway skills update to review skipped updates, or add --force to overwrite local changes explicitly.

railway autoupdate disable (or RAILWAY_NO_AUTO_UPDATE=1) disables automatic CLI and skill updates and their update notices. Explicit railway upgrade, railway check-updates, and railway skills update commands remain available.

Opt into the local GraphQL-backed MCP server instead:

railway setup agent -y --local
# or
railway mcp install --local --agent cursor

For VM launch, reconnection, Desktop setup, and authentication details, see the cloud-agent command guide.

railway upgrade presents CLI installation and managed skill synchronization as one flow. Stages advance as work completes, and the final summary says whether the new version is active or will be used on the next command. This explicit command also synchronizes managed skills when automatic updates are disabled.

Automatic discovery and downloads run quietly. After the new CLI is active and its skill sync has finished, an interactive command shows one completion receipt per CLI version. Preserved local edits are reported neutrally; a skill-sync failure is reported separately from a successful CLI install. Commands using JSON, piped output, help, and version output do not show or consume receipts. Install methods that require manual upgrades get one availability notice per release instead.

Run railway autoupdate status to inspect the running and recorded installed versions, staged/in-progress CLI updates, skill-sync results, and unmanaged skills. Use railway skills update for detailed skill results or to retry a sync.

Each railway code invocation with --codex, --opencode, --claude, --grok, or --railway creates a fresh VM. This also applies to remote, Codex desktop-only, and harness arguments after --; --new is accepted but optional. Use connect [agent] for an existing backend, --agent <name-or-id> for explicit server setup, or railway ca ssh <agent> for a shell. Bare launches and shared CA/Desktop provisioning retain their existing targeting behavior.

railway code --railway                       # new VM, local TUI on its public agent endpoint
railway code --railway --agent my-box --dir /app/project
railway code --railway connect my-box        # connect to an existing VM; wake it if asleep
railway code --railway remote                # run the TUI on a new VM over SSH
railway code --railway --connection-json     # setup and verify, without opening a TUI
railway code get-config my-box               # replay saved connection details

railway code --railway creates a new VM and opens the client in the Railway CA session pane, using the same setup progress and terminal frame as Codex and OpenCode. connect is only for reusing an existing VM; it is not required for the normal launch. Use --agent my-box to target a specific existing VM during setup. The conversation sidebar lists and resumes the daemon's native sessions.

The local railway-agent-tui connects over WebSocket to the existing CloudAgent.agentWsUrl (wss://<agent-domain>/agent). It shares the platform-supervised railway-agent serve daemon and persistent sessions with dashboard chat and the VM's TUI. Creating or waking the VM starts that daemon; the launcher verifies the public control protocol with get_state before opening the TUI. It does not start a second daemon or require a code-* domain. --dir selects the remote project, defaulting to /app; reconnect uses the locally saved directory when available. Without a name, normal cloud-agent selection applies. Older VMs without an agent endpoint report that limitation.

The gateway takes a five-minute JWT from cloudAgentHarnessToken on each WebSocket upgrade. A small local WebSocket bridge mints a fresh token on every TUI connection, including reconnects and session switches. This is a public WSS data path, with no SSH tunnel. The local bridge requires its own random capability, and both the bridge and its connections close when the TUI exits. An open conversation is not interrupted when the upgrade token expires. Expiring gate tokens are neither saved in get-config nor passed to the TUI. Model credentials and tool execution stay on the VM.

Every local launch, reconnect, and --connection-json invocation checks the latest stable release in the public agent-releases repository. Missing or outdated clients install automatically into ~/.railway/runtimes/railway-tui/<version>/, with the bundled daemon alongside the TUI. An installed client is reused when it matches the latest version. Downloads are checked against the release asset's SHA-256 digest before replacing any files; a failed download leaves previously installed versions intact. The client requires an attach-capable release (v0.1.15 or newer); the VM image owns the server version. A release must include an asset for your platform; Windows users need WSL or remote.

The TUI opens inside the CA frame, with the conversation sidebar a key away. --connection-json returns the public URL, remote directory, client version, and token-minting metadata, without credentials. Use the reconnect command from get-config to open it again. Explicit remote and passthrough harness arguments retain their VM-hosted behavior.

The code-* endpoint is optional and configured only at VM creation. Ordinary cloud agents do not request it by default. Managed Codex/OpenCode client setup requests it automatically when creating a VM:

railway code --codex --new
railway code --opencode --new

# Explicitly request the endpoint on a plain cloud agent:
railway ca create my-box --code-endpoint

# Choose a custom port instead of the default 4096:
railway code --opencode --new --code-port 5000
railway ca create my-box --code-port 5000

OpenCode Desktop setup also requests it. SSH-only sessions do not need the code endpoint. The API uses the optional CloudAgentCreateInput.codeEndpoint object: {} selects port 4096, { "port": 5000 } selects a custom port, and omission disables it. Ports must be 1024-65535, excluding the app port 8080 and gateway port 8790. The API injects RAILWAY_CODE_PORT from that configuration, and FactoryVM injects RAILWAY_PUBLIC_DOMAIN_<port>. Caller and bootstrap variables cannot override RAILWAY_CODE_PORT or provision a route by setting it.

Cloud agents with a code-* domain expose the configured port for a managed Codex or OpenCode server. Both launchers use this endpoint, leaving the app-* domain and port 8080 available for your application. One managed backend can occupy the code port at a time; setup reports a conflict if another process uses it. OpenCode's server URL also serves its web UI with the printed credentials.

Agents without a code endpoint continue using port 8080 for managed backends. This is creation-time configuration: setting an environment variable inside an existing VM or reconnecting does not attach a domain. Sleep/wake preserves the chosen routes. Running managed servers keep their current endpoint. On restart, a server uses the VM's explicit code-port configuration; older VMs without it retain their saved port. A configured code endpoint never falls back to the app domain if its domain is unavailable.

Capture the source with the existing cloudAgentCheckpointCreate mutation and poll cloudAgentCheckpoint until its status is SUCCEEDED. Then create a new VM:

railway ca create restored-box --from-checkpoint <checkpoint-id> --code-endpoint
# Or select a custom port:
railway ca create restored-box --from-checkpoint <checkpoint-id> --code-port 5000
railway code --opencode --agent restored-box

The equivalent API request is:

mutation {
  cloudAgentCreate(input: {
    environmentId: "<same-environment-id>"
    name: "restored-box"
    cloudAgentCheckpointId: "<checkpoint-id>"
    codeEndpoint: { port: 5000 }
  }) {
    id
    name
    domains { prefix port domain }
  }
}

The disk is restored into a new VM with its own identity and domains. Processes do not carry over. Saved Codex/OpenCode credentials and project directories are reused, while the launchers adopt the new VM's configured endpoint. Source VM variables are not copied automatically; pass needed variables or use a bootstrap. Checkpoint and bootstrap creates opt in explicitly. The separate fork operation preserves the source VM's code endpoint and port.

Prepare an authenticated server on a cloud agent and open your local client:

railway code --opencode
railway code --opencode --name my-box

OpenCode means OpenCode V2: the cloud-agent image ships the official V2 opencode, and the CLI launches it directly. OpenCode 1 is no longer supported, and the earlier --opencode2 edition flag is gone. An agent created from an older image whose opencode is still 1.x cannot run OpenCode sessions; launching or resuming one prints

This cloud agent is on an older image whose OpenCode is not V2. Create a new agent with railway code --opencode --new.

Preferences, saved connections, and VM history recorded as opencode2 by earlier CLI releases are read as OpenCode.

When a compatible OpenCode Desktop installation has an existing settings file or desktop database, Railway automatically saves the server URL, credentials, default server, and project in it. The final output confirms that configuration was updated; open Railway: <agent-name> in Desktop's server picker. Both JSON settings and SQLite renderer state are supported, with backups of previous settings. You may need to restart OpenCode Desktop to load the updated configuration. Configuration failures are non-fatal and reported alongside the connection details; rerun the command to retry.

The CLI also prints the server URL, username, password, and project directory for manual setup, plus a Railway reconnect command: railway code --opencode connect <agent>. The matching local terminal client launches automatically inside the Railway CA frame. Interactive starts show provisioning and client setup in its loading pane, installing a missing client quietly. Reconnecting with connect offers to install a missing client first; declining leaves the server running and prints the connection details. Use railway code get-config to view saved connection and Desktop settings. Failed setup keeps its diagnostic output visible. Local clients are verified against the remote server's protocol and release.

New OpenCode agents are named oc-railg-3ed; Codex uses codex-railg-3ed, Claude Code uses cc-railg-3ed, Grok uses grok-railg-3ed, and Railway uses rlwy-railg-3ed: the first five letters/digits of the project name, lowercase, plus a random three-character suffix. When using your default cloud agents project, the label comes from the local repository or directory instead. Existing names are checked before creation; --name overrides the generated name. The same naming applies to remote and railway ca desktop.

Reconnect to an existing server using your local client:

railway code --opencode connect
railway code --opencode connect my-box

connect discovers running OpenCode servers on agents you own. A server that an earlier CLI started as OpenCode 1 is not discovered or reconnected; create a new agent with railway code --opencode --new. One match connects directly; multiple matches show a workspace/project/agent picker. A name or ID targets an agent directly and can wake a saved server. Connecting also refreshes a compatible Desktop installation's configuration. Connecting never creates a new agent or installs a server on an unrelated box. In noninteractive terminals, the CLI still attempts Desktop configuration and prints connection details instead of prompting, installing software, or launching a terminal client; multiple matches require a name or ID.

To run both client and server inside the cloud agent, in Railway CA:

railway code --opencode remote

Harness launches create a fresh VM; --agent <name-or-id> targets an existing one. For the local-client setup, --dir selects the remote project directory (default /app). OpenCode V2 uses its server's startup directory, so switching it requires a fresh agent. Setup uses the same generated credentials, HTTPS checks, provider sign-in behavior, skills, and MCP sync as Desktop. It saves settings in detected Desktop installations and prints them for manual entry. A running server and its password are reused. Use railway ca sleep <name> when finished.

Put harness-specific arguments after --, for example: railway code --opencode -- run --standalone "explain this project".

Save a configured, running cloud agent as a reusable starting point:

railway ca bootstrap save dev --agent configured-vm
railway ca bootstrap list
railway ca bootstrap save updated --agent another-vm --default
railway ca bootstrap default dev

railway code --codex                         # uses your local environment default
railway code --codex --bootstrap updated     # selects a named bootstrap
railway code --codex --no-bootstrap          # starts with a clean VM
railway ca create scratch --bootstrap dev

On the railway ca launcher, click the bootstrap row below Target Project or press Option+B. If bootstraps exist, the row says Select Bootstrap and opens a compact, one-line-per-bootstrap list. Choose a bootstrap to make it your local default, Create New to create one, or No Default to start future Cloud Agents without a bootstrap. Select a project or environment in the sidebar and press b to open the same list; this opens on Create New at the end of the list and uses that row's environment without changing the launcher's prompt target.

Press n in the tree or bootstrap list to choose an agent for a new VM. The picker includes ChatGPT Codex, a Use bootstrap checkbox, and an Option+B shortcut to use the project default, select another bootstrap, or start clean. These launch choices do not change the stored default. Press Option+N on a VM, its session, or inside its focused terminal to open the same new VM picker with bootstrap and project selection. It starts with the current VM's project and environment; launching creates a fresh machine.

Failed captures are hidden from the TUI bootstrap pickers. Ready bootstraps and captures still saving appear before No Default, with Create New last.

App shortcuts use Option (Alt on other keyboards): Option+B for bootstraps, Option+T for the target project, and Option+O for an SSH shell. Option+Esc returns keyboard focus to the tree. Ctrl+B, Ctrl+T, and Ctrl+] remain compatibility shortcuts; Ctrl+C keeps its standard interrupt behavior.

Press Enter on an existing VM to reopen its primary coding agent terminal. The CLI uses that VM's configuration and session history to identify the agent; when it cannot, it asks you to choose without using or changing your default. Clicking the terminal pane only changes focus; connecting to an unopened thread still requires Enter or a double-click on that thread.

Drag the edge between the sidebar and terminal to resize the sidebar. Thread text and horizontal separators use the full available width. The sidebar has a solid dark grey background and a right border that defines its raised edge. The width is saved when you release the mouse and restored next time you open the CLI. A narrower terminal temporarily limits the displayed width without changing that preference. Press Escape during a drag to cancel it.

The Create bootstrap form stays centered in the terminal pane. It has bordered fields for a name, an optional repository (owner/repo or an HTTPS URL), and a coding agent, plus a Make default checkbox. Click fields and the Create bootstrap button, or use Tab/Shift+Tab to move between fields, left/right to edit text or choose the agent, and Enter to activate a control. The footer shows the available shortcuts.

Creation shows the current stage in a compact progress card while the CLI creates a temporary VM, copies the selected harness's available local sign-in, skills, MCP configuration and settings, optionally clones the repository into /app, and saves a checkpoint. Existing Railway-managed harness settings take precedence over imported settings. Private repositories use the VM's GitHub access. Once capture is ready, the CLI applies your default choice and deletes the setup VM. Provisioning or capture failures attempt cleanup and preserve the previous default. Cleanup failures name the remaining VM.

The launcher returns to your unchanged prompt after completion. Creating from the sidebar returns to the tree. Launching a real VM also shows only its current preparation stage, in a fixed-width panel.

Highlight an existing running VM and press b to open a Name form inside the TUI. Saving captures its disk without stopping, deleting, or disconnecting the source VM. Make default starts checked when no default exists, and unchecked when one is already selected; you can change it before creating. A failed disk capture is not a usable bootstrap even though its name has been reserved. Retry with the same name from the same VM to reuse that failed capture record; if it is still saving, the TUI waits for that capture instead of submitting a duplicate. Ready bootstraps and names captured from other VMs cannot be overwritten by this form. A server-side snapshot timeout is reported with its failure reason, and the default changes only after a successful capture. The flat railway ca bootstrap save command still supports saving a new version of an existing name and selecting it with --default. Default changes wait for capture to succeed.

Bootstraps are shared within a project/environment pair. The default selection is stored only in your local Railway CLI config, keyed by Railway host and environment ID (which also identifies the project). It does not change the dashboard or teammates’ defaults. Without a local default, new VMs start clean. Explicit --project and --environment flags take precedence, followed by the directory's Railway link, then the saved CA project preference. Bootstrap names are resolved only within that environment. list, save, and default support --json; save accepts --env-file and --variable for stored bootstrap variables. Launch-time variables override stored bootstrap variables.

Only new VMs use bootstraps. Connecting to an existing VM preserves its disk. A deleted, saving, or degraded local default produces an error; --no-bootstrap explicitly bypasses it. ca create --from-checkpoint also bypasses the default and cannot be combined with bootstrap flags.

The snapshot includes files and installed tools. Use an idempotent, non-blocking /etc/railway/bootstrap/startup.sh to restart local services on boot/wake, and /etc/railway/bootstrap/AGENTS.md for setup notes.

Run the native Codex terminal UI on your computer, connected to Codex App Server on a persistent Railway cloud agent:

railway code --codex
railway code --codex --agent my-box --dir /app
railway code --codex connect my-box
railway code --codex connect

New Codex agents use the same naming rules as OpenCode, with a codex- prefix (for example, codex-railg-3ed). The generated name works with connect, get-config, and cloud-agent lifecycle commands; --name sets a custom name.

For a Desktop-only workflow:

railway code --codex desktop-only
railway code --codex desktop-only --agent my-box --dir /app

This prepares the VM, starts or reuses the authenticated backend App Server, verifies its public endpoint, registers SSH, and saves the remote project for Codex Desktop to import at its next startup. It then exits, leaving the backend running. It never prompts to install or launch a local terminal client. The results panel shows backend credentials, the SSH configuration file location, the Desktop project name, and commands to reconnect or retrieve the configuration.

Terminal setup carries your available local Codex sign-in and configured skills/MCP sync, starts App Server on the configured code port (default 4096, or 8080 for legacy connections), verifies its public WebSocket handshake, and automatically launches the local client inside the Railway CA frame. Tools, files, and threads live on the VM. Use /resume in Codex or select a conversation in the CA sidebar to reopen a remote thread. connect discovers running Codex servers; an explicit agent also wakes and restarts a previously configured server as needed. Click web links in the pane to open them in your browser, including shortened URLs and labeled links.

The remote terminal client uses a separate, persistent CODEX_HOME under ~/.railway/codex-client/<backend-id>/. The VM owns its tools and sessions; local-only MCP servers, plugins, and hooks must not participate in remote startup. This also keeps the terminal's busy indicator and cancellation state consistent with the backend. Ctrl+C interrupts active work and exits when idle; Ctrl+D on an empty prompt detaches even during startup.

The terminal connection uses wss:// through the agent's public domain. Its bearer token is passed to the local client through an environment variable. The remote server's token, PID, version, directory, and logs live under ~/.railway/codex/. Setup on an explicitly selected agent reuses its token and healthy server when the version is unchanged. An occupied port or a different running project directory requires another agent.

Setup and connect also register and verify the agent's SSH host in ~/.ssh/config as railway-<agent-name>, using the same registration as railway ca desktop --codex. Reconnecting upgrades the previous railway-agent-<agent-name> default in both SSH and Codex Desktop's saved config. They merge the connection and remote project into ~/.codex/codex-app/config.json ($CODEX_HOME/codex-app/config.json when set) in the background. Setup never launches or activates Codex Desktop; the app imports the saved configuration when you next start it. Find Railway: <name> in Codex Desktop's project sidebar. An existing custom SSH alias and project label are preserved. connect imports the server's actual working directory. You can use the same VM from the terminal and Desktop.

Server setup silently checks npm for the latest official Codex release and validates its authenticated App Server before replacing a running process. Versions are cached under ~/.railway/runtimes/codex-server/<version>/, with update diagnostics in ~/.railway/codex/update.log. A failed update preserves the existing server. connect keeps a running server's version; restarting a stopped server checks for updates. Terminal mode automatically finds or installs the exact matching local @openai/codex version using npm under ~/.railway/runtimes/codex-client/<version>/.

For scripts, --connection-json returns a single JSON object containing schemaVersion, agent identity, and connection url, token, directory, version, and reused. Progress goes to stderr.

railway code --codex --connection-json connect my-box
railway code --codex remote             # run the UI inside Railway CA
railway code --codex -- exec "run tests" # execute inside the VM

Closing the local client leaves the server running. Use railway ca sleep my-box to stop compute, then railway code --codex connect my-box to wake and reconnect. Codex currently marks its remote App Server transport experimental.

Local connections enable automatic command permissions. Codex starts, resumes, and forks conversations with full VM access and approvals disabled, and OpenCode clients run with --auto. These settings also apply on reconnect. Codex records trust for the remote project directory, including a different repository selected when resuming a thread.

Fresh OpenCode launches open the native home/splash screen. A conversation is created when you submit a prompt; a launch with an initial prompt starts directly in that conversation. Connection details are shown before launch and again after the local client exits.

In railway ca and the railway code frame, expand a cloud agent in the left list to browse its Claude, Grok, Codex, and OpenCode conversations. Select a title and press Enter to reopen that exact thread. Saved conversations remain available after their terminal exits; opening the list does not launch clients for them. A fresh harness pane starts as New Thread, then adopts the harness's generated title. [S] is reserved for direct VM shells; harness consoles, server processes, and provisioning commands do not get session rows. Conversation metadata is cached locally across restarts, including for sleeping VMs. Discovery runs at startup, when selecting or expanding a running machine, when Option+F / Alt+F reveals the sidebar, and on explicit refresh. Loaded rows, their order, expansion choices, and the selected conversation stay in place. The machine's status icon always represents its machine state.

Use Option+R / Alt+R to refresh agents and visible conversations from anywhere, including inside a session. It also finds agents in unopened projects; there is no separate discovery shortcut. Plain r refreshes the selected environment when the sidebar is focused.

Press x / X on a saved conversation to delete it from its harness. The row disappears immediately while native deletion runs in the background; failures restore the row and show an error. This deletes the saved conversation, rather than just disconnecting its terminal. Draft New Thread panes simply close, and [S] shell rows retain their end-session action.

There is no periodic account or VM-history polling. Codex and OpenCode title and activity changes come from their existing native-client connections. Output from an active SSH harness pane triggers a coalesced read of Railway's stored session reports, without opening another VM connection. An idle sidebar does not refresh history on its own; changes made elsewhere appear on the next explicit refresh.

Claude and Grok history is discovered directly on the VM over SSH, including conversations started outside Railway's launcher. Claude uses a pinned official Agent SDK, cached automatically on the VM when history is first discovered; Grok uses its saved summary.json metadata. Discovery respects CLAUDE_CONFIG_DIR and GROK_HOME, and filters hidden subagents and empty startup records. A temporary discovery failure retains previously loaded rows. Codex and OpenCode also expose their VM-local metadata indexes, so their history is available without a locally saved backend connection. OpenCode history saved as opencode2 by earlier CLI releases is listed as OpenCode.

Selecting a Claude or Grok thread reconnects to its verified live terminal when available, or resumes its native UI from the recorded project and configuration directory. Claude background jobs use claude attach. Live metadata and hooks update thread status and associate native panes with their conversation IDs. Grok launches and resumed conversations use --trust --always-approve on the cloud VM, skipping folder-trust and tool-approval prompts. SSH autostart uses the same flags after the next railway code provision; local settings are unchanged. Native Codex and OpenCode client actions update the pane's exact conversation identity through a per-pane aut