feat(sandbox): fork, templates, and --variable/--env-file on create

[codyde]

What shipped

Expands the railway sandbox namespace (#925) with forking, templates, and variable seeding, riding backend support that already landed in mono (sandboxCreate.sourceSandboxId railwayapp/mono#30565, sandboxCreate.variables railwayapp/mono#30635, sandboxTemplateBuild).

railway sandbox fork [ID]

• Forks a running sandbox's root volume into a new sandbox; defaults to the active sandbox when no ID is given (positional or --id, mirroring destroy)
• The fork becomes the active ref, so a bare railway sandbox ssh / exec immediately targets it

railway sandbox template build (aliases: create, new)

• Builds a template from repeatable -c '<shell command>' instructions via sandboxTemplateBuild; --wait polls the status query until READY/FAILED
• Templates are content-addressed server-side (id = sha256 of the recipe, ~7-day snapshot cache) — re-running an identical build is an instant cache hit ("ready (cached)")
• template status <id-or-name> and template list round out the surface
• railway sandbox create --template <name-or-id>: sandboxCreate needs the full recipe (not just the hash), so the CLI stores built recipes locally in config.json with an optional --name handle and resends the instructions on create

--private-network on create and fork

• Maps to sandboxCreate.networkIsolation: PRIVATE; default stays ISOLATED (field omitted)
• First production caller of the PRIVATE path — verified live: privnet DNS resolves and a psql query against postgres.railway.internal succeeds from both a created and a forked sandbox (--variable DB=Postgres.DATABASE_URL + --private-network is the combo that makes resolved internal URLs actually usable)

--variable KEY=VALUE on create and fork

• Repeatable and comma-separable: --variable FOO=bar,BAZ=qux. A comma only splits when every segment carries its own =, so values containing commas (ALLOWED=a.com,b.com) stay intact
• Values may use Railway references, resolved server-side at create time:
  • bare: DB=Postgres.DATABASE_URL (auto-wrapped to ${{Postgres.DATABASE_URL}})
  • pre-wrapped: DB=${{Postgres.DATABASE_URL}} (passes through verbatim)
  • embedded: URL=http://${{svc.HOST}}:8080
• Auto-wrap is strict (name.UPPER_SNAKE) so plain values like 1.5 or example.com are never mangled; the unambiguous shared. namespace accepts any case (shared.char)

--env-file PATH on create and fork

• Repeatable; dotenv-style parsing (comments, blank lines, export prefix, single/double-quoted values, trailing # comments on unquoted values)
• References inside files resolve the same way; --variable flags override file entries on key collision

fix(ssh): env-aware relay host (dev-mode Permission denied bug)

• The SSH relay was hardcoded to ssh.railway.com while backboard URLs follow RAILWAY_ENV — dev-mode CLIs registered keys against the develop backboard but dialed the prod relay → Permission denied (publickey) (reported by Pierre in raildev)
• Now mirrors backboard's controllers/ssh mapping: dev → ssh.railway-develop.com -p 2222; staging falls through to prod exactly like backboard's IS_DEV-only branch. Covers native ssh, tmux, the generated ~/.ssh/config block, and volume SFTP
• Prod is byte-identical — (ssh.railway.com, None) yields the same target string, no extra args, same config block (existing tests pass unmodified); prod smoke-tested (create → ssh → destroy)

Telemetry

• Command telemetry walks nested subcommand levels: sandbox template build now reports sub_command: "template:build" (previously just "template"). Heads-up for dashboard owners: other nested commands get richer values too (keys:add, files:pull) — exact-match filters on the old single-level names should become prefix matches
• sandbox ssh emits the same stage-tagged failure events as railway ssh (tel.rs generalized): ssh_resolve_target / ssh_key_setup / ssh_session / ssh_exit_nonzero under command: "sandbox"
• (Server-side utilization was already covered: sandbox mutations are tagged source: cli via user-agent, with fork/template metric tags and template cache hit/miss analytics)

Misc

• Experimental warning printed on every railway sandbox invocation (stderr only — --json stdout stays clean): "Railway sandboxes are experimental and APIs may change or break during testing."
• src/gql/schema.json refreshed from prod introspection (own commit; large diff is accumulated drift, only the sandbox types are load-bearing here)

Testing

• 16 unit tests covering the comma heuristic, auto-wrap edge cases (1.5, example.com, a.b.C, pre-wrapped, embedded, shared. lowercase), dotenv parsing, and file/flag precedence
• Full live E2E against production (raildesk project):
  • create with all variable forms at once (env-file + repeated + comma + bare/wrapped/embedded refs + shared lowercase), exec exit-code/stderr/--id semantics, ssh command mode
  • fork volume inheritance verified via marker file, fork-with-variables, positional fork, ref movement after fork
  • template: build with --wait (npm install + marker file), instant cache hit on rebuild, status/list, create --template verified to boot with the baked filesystem (pnpm 9.15.9 + marker present), unknown-template error hint
  • error paths (bad pair, missing file, bogus fork source) and all three destroy forms incl. ref clearing

🤖 Generated with Claude Code