railway ca
Browse your projects, launch cloud agents, and connect to their terminal sessions. Set up Claude Desktop, Codex Desktop, or OpenCode with railway ca desktop.
railway upgrade for the latest client integrations.Usage
railway ca [COMMAND] [OPTIONS]With no arguments, railway ca opens the terminal interface. Launch flags open the coding session in Railway CA; railway ca start skips the interface. OpenCode flags on ca run the coding client on the cloud agent. Use railway code --opencode for local terminal clients.
Subcommands
| Subcommand | Description |
|---|---|
setup | Configure the default project, coding agent, skills, and theme |
start | Launch a coding agent without the Railway CA interface |
desktop | Prepare a cloud agent and configure a local desktop app |
herdr | Create and manage cloud agents as Herdr machines |
list | List your agents across projects, or within an explicit scope |
create [NAME] | Create a VM without attaching a coding client |
ssh [AGENT] [-- COMMAND...] | Attach to an existing agent's terminal session or run a command |
sleep [AGENT] | Stop compute and processes while retaining the disk |
wake [AGENT] | Wake an existing agent |
delete [AGENT] | Delete an agent and its disk, after confirmation |
AGENT accepts a name or ID. When omitted for lifecycle commands, Railway uses the directory's agent or the sole candidate and reports candidates when it cannot choose. --project and --environment narrow the scope.
Launch options
railway ca and railway ca start share the launch options in the railway code reference. Choose --claude, --codex, --grok, --railway, or --opencode. With no flag, the saved default applies, overridden by RAILWAY_CA_AGENT when set.
railway ca --opencode
railway ca start --codex --newAgents remain running after disconnect. Use railway ca sleep to stop compute; the legacy --keep-awake flag is no longer needed.
Desktop
Prepare the remote tool and its local app connection:
railway ca desktop --claude| Option | Description |
|---|---|
--claude | Write SSH configuration and Claude Desktop's named environment |
--codex | Write the SSH alias discovered by Codex Desktop |
--opencode | Start the OpenCode server and save its Desktop connection and project |
--agent <NAME_OR_ID> | Use an existing agent |
--new | Always create a fresh VM; conflicts with --agent and --remove |
--dir <PATH> | Remote starting directory, default /app; choose the remote folder in Codex itself |
--alias <NAME> | Override the generated railway-agent-<name> SSH alias |
--ssh-config <PATH> | SSH file to write, default ~/.ssh/config |
--dry-run | Preview setup without local changes or creating, waking, or changing a VM |
--remove | Remove managed local configuration and stop a managed OpenCode server on an awake VM |
--no-verify | Skip SSH probes; OpenCode HTTPS authentication is still checked |
-p, --project <PROJECT> | Project ID |
-e, --environment <ENVIRONMENT> | Environment name or ID |
App flags can be combined for the same VM, such as --claude --codex. Without --new, setup reuses and wakes an agent where possible, creating one if needed.
Claude and Codex connect over SSH. Restart the app after setup and select the remote environment or project. OpenCode starts a server on the agent's HTTPS app endpoint, using port 8080, and saves its generated username/password and project in OpenCode Desktop. An occupied port fails without stopping the other process.
On macOS, OpenCode setup restarts the running OpenCode app. Quit it before setup on Windows/Linux. Select Home → Projects → Railway: <agent-name> → /app → New session. Existing chats retain their server.
--remove leaves the VM and disk intact and does not wake a sleeping agent. It removes the shared managed SSH entry, so other apps using that alias are affected. --remove conflicts with --dry-run and --dir.
App walkthroughs: Claude Desktop, Codex Desktop, and OpenCode.
Herdr
Use railway ca herdr to add cloud agents to Herdr and manage their lifecycle. Requires Railway CLI 5.62.0 or later and Herdr 0.9 or later on macOS or Linux. For setup, see Herdr.
In Herdr's Local terminal, run railway ca herdr install once to link the plugin. Then choose one:
# Create a fresh VM for Codex
railway ca herdr new --codex
# Connect an existing VM, or manage sleep, wake, and deletion
railway ca herdr agents| Subcommand | Description |
|---|---|
install | Link the plugin and add shortcuts. --print previews its manifest. --remove unlinks it and stops the session's watcher. --no-keys leaves keybindings unchanged. |
new [NAME] | Always create a fresh VM, add its Herdr machine, and prepare a coding workspace. Prompts for the target and coding tool. |
agents | Pick an agent to connect, sleep, wake, or delete. --wake filters to sleeping agents and wakes directly when only one matches. |
sync | Update saved machines to match agent status and remove entries for deleted agents. Supports --dry-run and --json. |
bootstrap [AGENT] | Retry workspace setup on an awake VM that already has Herdr. Does not create or wake a VM, or add it to the sidebar. |
watch | Follow agent status for the current Herdr session. --foreground prints every event. |
new and agents handle workspace setup; bootstrap and watch are not additional setup steps. new and bootstrap accept --claude, --codex, --grok, or --railway. Without a flag, new asks you to choose a tool and bootstrap uses your saved default.
To select the creation target without project or environment prompts:
railway ca herdr new code-review --codex \
--project <project-id> --environment <environment-id>Add --dry-run to new to preview the selection without creating a VM. To retry setup on an awake agent:
railway ca herdr bootstrap code-review --codexThe plugin starts its watcher automatically with the Herdr session. sync --spawn-watch also ensures it is running. Sync updates machines already added to Herdr. Use agents to add an existing VM.
Removing the plugin keeps your VMs, disks, and saved Herdr machines. Use the Local picker for sleep and wake.
Configure cloud agents
railway ca setup writes your choices to ~/.railway/agent-prefs.json.
| Option | Description |
|---|---|
-y, --yes | Keep existing preferences or choose defaults without prompts; used when stdout is not a terminal |
--show | Print preferences and exit |
--reset | Remove saved preferences |
Skills sync is off when selecting fresh noninteractive defaults. See configuration for sources and import behavior.
List and create
railway ca list --json
railway ca create my-agent --project <project-id> --environment production --jsonlist --all includes agents belonging to other members and requires an explicit --environment. It does not grant access to their credentials or sessions.
create supports --variable, --env-file, --no-wait, and --json. --no-wait returns once creation is requested; it does not mean the agent is ready.
SSH and lifecycle
railway ca ssh <agent-name> -- bash
railway ca sleep <agent-name>
railway ca wake <agent-name>
railway ca delete <agent-name>ssh --session <name> selects a durable terminal session. ssh targets an existing awake VM and does not create one if it cannot find the name.
sleep --all sleeps all your running agents, narrowed by an environment filter when supplied. wake --no-wait returns before readiness. delete --yes skips its confirmation.
Sleep stops processes while retaining files. After waking OpenCode, rerun Desktop setup or a named local-client connect command to restart the managed server. See agent lifecycle.
The interface
The menu offers New Session, New Cloud Agent, and Manage Cloud Agents, with a prompt for a task and a target project. New Session selects an existing agent; New Cloud Agent creates a fresh machine. The tree only adds child rows when actual terminal sessions exist, and loading appears in the agent's status icon.
Keys
| Key | Action |
|---|---|
↑ ↓ | Move between rows |
→ ← | Open and close a row |
enter | Open a row or connect to a session |
shift+esc or ^] | Stop typing in a session |
n | Start a session on an agent or an agent on a project |
x | End the session |
s / w / d | Sleep, wake, or delete the agent |
c | Copy a session's SSH command |
r | Refresh |
t | Set the prompt's target |
^t | Change the target project |
⌥f | Toggle the full-width session view |
shift+enter | Leave the interface and connect full screen |
⌥t | Cycle theme |
⌥s | Open setup |
esc | Return to the menu |
^c | Quit |
In the coding-agent picker and prompt footer, Shift+Tab cycles coding agents. Press ? for the full key reference in the active view.
Mouse
Click a row to select it and double-click a session to connect. In a connected session, scroll with the wheel, open links by clicking, and drag to select and copy text. When the coding agent handles mouse input, hold Shift while dragging to select text instead.