feat: railway code — launch Codex or Claude Code in a Railway sandbox with your own plan

[codyde]

Status: out for testing — not intended to merge soon. Draft on purpose; feedback on the two agent flows is what we're after.

What

railway code launches a coding agent in a Railway sandbox on the user's own plan — authenticated, interactive, ~6 seconds end-to-end:

railway code --codex               # sandbox + your local Codex sign-in
railway code --claude              # sandbox + an auto-minted Claude setup-token
railway code --claude --gh         # also inject your GitHub auth (gh auth token)
railway code --codex --new --variable DB_URL=postgres.DATABASE_URL
railway code --codex -- exec "explain this codebase"

Requires the PROJECT_SANDBOXES feature.

The two agent flows

--codex

Uses the flow OpenAI documents for remote machines/containers: the local ~/.codex/auth.json sign-in is read client-side and rides ssh stdin into a 0600 file in the sandbox — never argv, never Railway variables, images, or server-side config. The copy is announced to the user (no data leaves the machine silently).

--claude

Deliberately not a copy of the local sign-in: ~/.claude/.credentials.json carries the OAuth refresh token, and two machines racing one rotating refresh token can sign the laptop out. Instead the CLI mints a purpose-made long-lived token — the same shape as mono's agent-vm Connect tab flow (CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY accepted as alternative):

1. CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_API_KEY in the local env → used silently.
2. Otherwise claude setup-token runs invisibly under script(1)'s pty (claude's TUI needs a tty on both ends). The browser round-trip stays interactive — an existing session with prior consent completes hands-free — while the terminal shows only a spinner. Nothing renders on screen, least of all the minted token; it's harvested from a 0600 recording that's deleted immediately, with ANSI-stripping + soft-wrap reassembly. A 120s timeout catches the one path that can't work hidden (paste-a-code-into-the-terminal) and falls back to a masked paste prompt.
3. The token rides ssh stdin into a 0600 env file (KEY=VALUE, so both var names work), sourced at launch and on every reconnect.

Two sandbox-image gotchas handled: the image ships a ~/.claude.json without hasCompletedOnboarding (the build stamps it), so the flag is merged in via jq (node fallback) rather than written-when-absent — otherwise claude ignores the token and shows the login picker. And the user's local ~/.claude/settings.json (permissions mode, model, plugins) is mirrored into the sandbox when present.

Keeping agents current

Fresh sandboxes launch the image's baked agent version, so a background update always loses the race against the launch (codex then greets the user with its update-available banner). Updates therefore run synchronously during provisioning, behind the spinner, kept cheap: codex compares installed vs registry (~2s when current) and npm-installs only on a real version gap; claude update no-ops when current (the image sets autoUpdates: false, so this is the only updater). Both are timeout-bounded so a wedged registry can't hang provisioning.

DX details

• One connection, one host-key decision per run: provisioning is a single script; every ssh multiplexes over one ControlMaster. Relay connections verify against a CLI-owned known-hosts file (~/.railway/known_hosts_relay, accept-new, self-healing) — the user's ~/.ssh/known_hosts is never touched. Works around the relay fleet presenting per-instance host keys; commented for revert to strict checking once the relay ships a shared key/CA.
• Quiet output: one-line sandbox create, no ssh-key announce, single credential line — the launch reads as one flow, not sandbox plumbing. (The relay's "Railway durable session…" banner needs a small mono change to suppress; tracked separately.)
• Terminal hygiene: agent TUIs enable the kitty keyboard protocol; an unclean exit (ctrl-c, dropped link) used to leave the terminal emitting junk like 9;5:3u. A reset sequence now runs remotely after the agent exits and locally after the session ends — no-ops on a clean terminal.
• Auto-launch on reconnect: a guarded ~/.profile seed reads ~/.railway-code-agent, so any interactive railway sandbox ssh drops back into whichever agent was last provisioned; quitting the agent lands in a shell.
• Sane reuse: repeated runs reuse the active RUNNING/CREATING sandbox; --new forces fresh; disconnect prints reconnect breadcrumbs.
• --variable / --env-file have full sandbox create parity; --gh provisions a 0600 token file + GH_TOKEN export + git credential helper.

Validation

• Codex: 10/10 consecutive fresh create→provision→launch→destroy cycles against production, ~6s each.
• Claude: end-to-end verified against a production sandbox — token minted hands-free, onboarding merge applied, claude -p responded using the injected token; update snippet verified to no-op at current version.
• 457 tests pass (unit coverage for provision scripts, token extraction/reassembly from real recordings, token validation, terminal-reset escaping).

Notes for reviewers

• Replaces feat: railway code --codex — launch OpenAI Codex in a sandbox with your own sign-in #1006 (branch renamed feat/code-codex → feat/code-agents now that it's two agents).
• Codex auth-pattern policy diligence (OpenAI ToU + docs precedent) was done before feat: railway code --codex — launch OpenAI Codex in a sandbox with your own sign-in #1006; the Claude flow uses Anthropic's documented remote-machine mechanism (claude setup-token).

🤖 Generated with Claude Code