feat(code): coding agents on cloud agent VMs, and railway ca to drive them

[codyde]

Coding agents on Railway cloud agent VMs, with your own credentials. railway ca is a TUI to drive them; railway code is the same launcher without one.

Requires railwayapp/mono#34349 and railwayapp/mono#34350 deployed — the cloud agent API is Internal-only until then.

Commands

Command	Does
railway ca	TUI: prompt, project tree, live sessions
railway ca setup	Default project, harness, skills sync, theme → ~/.railway/agent-prefs.json
railway ca setup --show	Print saved preferences
railway ca start [flags]	Launch without the TUI
railway code --claude | --codex | --grok	Launch a harness on a cloud agent VM, hand over the terminal
railway code -- <args>	Run the harness non-interactively and exit

railway ca with any launch flag, or with no terminal, behaves as railway code. Both take the same flags, read the same preferences, and resolve a target the same way.

Launch flags

• --claude / --codex / --grok — harness; the saved default applies when omitted (RAILWAY_CA_AGENT overrides for one run)
• --new — force a new VM instead of reusing this environment's agent
• --rm — destroy the agent on exit; --keep-awake — leave it running instead of sleeping
• --gh — forward GitHub auth; --refresh-auth — re-deliver credentials to a reused agent
• --variable K=V / --env-file <path> — environment for the session
• -p <project> / -e <environment> — target; --name <name> names a newly created agent

railway ca — menu

• Prompt targeted at a default project, set in setup, changed with ^t from the same card (which updates the default, not just this run)
• New Session — work on an existing agent; asks which when there are several, skips when there is one, says so instead of provisioning when there are none
• New Cloud Agent — fresh VM in the target project
• Manage Cloud Agents — tree: workspace → project → environment → agent → session
• Mouse: click the prompt to focus it, click a card to open it
• Four themes (Railway violet default), ⌥t cycles, persisted on exit
• First run walks setup in the same card style, and offers to create a "Cloud Agents" project

railway ca — manage

• Tree with per-project agent counts and per-agent session counts; default project pinned first
• Sessions are pty-backed ssh into the relay's durable sessions, emulated with vt100, drawn in the right pane; several run at once
• enter connect · shift+esc / ^] release the keyboard · n new session · x end session
• s sleep · w wake · d delete (confirmed) · c copy ssh command · r refresh · ? full key list
• ⌥f maximize the pane, again to restore · shift+enter hand over the real terminal and return to the same session
• Wheel and shift+pgup/pgdn forward to the agent when it owns the mouse, else the emulator's scrollback
• Click a link to open it, including one wrapped across rows (OAuth URLs always are); drag from it to copy instead
• Clicks reach an agent that has taken the mouse, so its own clickable output works; shift+drag takes one back to select
• Drag-to-copy in either pane, with a corner toast confirming
• Wake ends at running, not at accepted — the platform reports the old status until the VM boots, so the environment is re-asked every 1.5s until it arrives (3 min cap). Clearing the label on the first answer is what made a working wake look rolled back.
• Ending a session matches RAILWAY_DURABLE_SESSION_NAME in /proc/*/environ and sends TERM — there is no API for it, and never pkill -f

Skills sync

• Packs the local skills directory, unpacks on the VM add-only — never takes a name the agent already has
• Never ships Railway's own skills (read from the CLI manifest, not a hardcoded name); they are baked into the image
• 2 MB warns, 10 MB refuses; content hash skips an unchanged upload
• Excludes .git/node_modules/.venv/__pycache__/target, .env*, symlinks, empty skills

railway code

Target resolution, shared with railway ca:

1. -p/-e win outright
2. The default project from agent-prefs.json — beats the linked directory, because a link is about deploys and shouldn't put an agent in some service's checkout
3. The linked directory
4. Nothing to go on and a terminal to ask in → runs railway ca setup, so the answer is remembered rather than asked again next launch

Within that environment: the remembered agent, then your sole existing one, then a fresh one — so a second railway code lands on the agent already there rather than billing for a new box. A TUI launch always carries an explicit target, which is what keeps any prompt from being drawn underneath a frame.

Everything else:

• Installs and configures nothing. cloud-agent-base bakes every harness and express-agent serve --agents reconciles their config each boot. Removed as dead code: npm/x.ai installers, AGENT-NO-NPM, codex/claude update snippets, codex trust_level, grok [ui] yolo, the ~/.claude.json onboarding merge, bubblewrap install.
• Credentials over ssh stdin into a 0600 file — never create-time variables, so they never reach the VM spec, an image, an argv, or server-side config. codex/grok copy the local auth.json; claude uses a claude setup-token grant or ANTHROPIC_API_KEY, never the local sign-in's rotating refresh token.
• Sleep on disconnect, wake on next run, disk intact — agents have no idle timeout.
• Reuse keyed per environment. With no local pointer (second machine, wiped config) it adopts your sole existing agent rather than minting a billing duplicate; scoped mine: true so it can't adopt a teammate's.
• ~/.claude/settings.json merged, not overwritten — express-agent co-owns that file, so the previous truncating write stripped the harness's Railway MCP tools until next boot.
• No cd — the machine spec sets workDir (/app) for the workload and every session; forcing $HOME landed outside the dirs express-agent reconciles trust into.
• railway logout clears the cached Claude setup-token.

Structure

• code::launch splits into prepare / run_session / sleep_agent behind a Progress trait, so one pipeline reports into either the TUI's loading pane or spinners
• tui/app.rs is state and keys only — no rendering, no I/O; every key yields state plus at most one Effect, which is what makes navigation testable without a terminal or network
• relay_destination / relay_port_args exposed: a relay target is a username, not a hostname, and the pty session builds its own invocation
• clear_mouse_tracking after any interactive relay session — detaching from a durable session leaves the remote agent's mouse tracking on, and every pointer movement then arrives at the shell prompt as 35;21;32M
• vt100 pinned at 0.15 (0.16 conflicts with ratatui's pinned unicode-width): caps scrollback at one screenful, and hides OSC 8 hyperlinks from link detection

Known gaps

• Per-project counts come from a background sweep of every environment; the list query takes one environment at a time. cloudAgents(workspaceId:) would replace it and enable live status.
• No telemetry event for ca setup — needs a backboard schema change.

Verification

781 tests, cargo fmt --all -- --check and cargo clippy --all-targets --all-features clean. Seven pty tests are #[cfg(unix)]: they need a mode-setting escape sequence to survive the pty, and ConPTY interprets those itself. Driven against prod: launch, reattach, sleep, wake, delete, skills sync, full-screen handoff.