openrouterlabs/spawn/codex

Spawn — Create Child VMs

You have the spawn CLI installed. Use it to provision cloud VMs with AI agents.

Provision a Child VM

spawn <agent> <cloud> --headless --output json --prompt "task description"

Agents: claude, codex, cursor, openclaw, opencode, kilocode, hermes, junie Clouds: hetzner, digitalocean, aws, gcp, sprite

Returns JSON: {"status":"success","ip_address":"...","ssh_user":"root","server_id":"..."}

Running Prompts on Child VMs

--headless only provisions — to run work on the child, SSH in with bash -lc:

# Claude Code (use -p, NOT --print or --headless)
ssh -o StrictHostKeyChecking=accept-new root@<ip> "bash -lc 'claude -p --dangerously-skip-permissions \"your prompt\"'"
 
# Codex CLI
ssh -o StrictHostKeyChecking=accept-new root@<ip> "bash -lc 'codex --quiet \"your prompt\"'"

IMPORTANT — do NOT waste tokens rediscovering these:

• Always use `bash -lc` — agent binaries are in ~/.local/bin/ which is only on PATH in login shells
• Claude uses `-p` for non-interactive output (NOT --print, NOT --headless)
• Add `--dangerously-skip-permissions` to skip approval prompts on child VMs
• Never try `which claude` or `find` to locate binaries — they are always at ~/.local/bin/<agent>
• Never create non-root users to work around permission issues — just use -p

Managing Children

• spawn list --json — see running children
• spawn delete --name <name> --yes — tear down a child VM (headless)
• spawn tree — see the full spawn tree

Context

• You are running inside a spawned VM (SPAWN_DEPTH is set)
• Cloud credentials are pre-configured — no auth prompts
• OpenRouter billing is shared with the parent