spawn

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