{"id":50140303,"url":"https://github.com/OpenRouterLabs/spawn","last_synced_at":"2026-06-09T17:00:41.527Z","repository":{"id":336522125,"uuid":"1147571355","full_name":"OpenRouterLabs/spawn","owner":"OpenRouterLabs","description":"Spawn any agent, on any cloud","archived":false,"fork":false,"pushed_at":"2026-06-03T07:39:39.000Z","size":11160,"stargazers_count":169,"open_issues_count":41,"forks_count":33,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-06-03T09:18:49.931Z","etag":null,"topics":["claude","cli","codex","openclaw","vm"],"latest_commit_sha":null,"homepage":"https://openrouter.ai/spawn","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenRouterLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-02T00:03:18.000Z","updated_at":"2026-06-03T07:39:40.000Z","dependencies_parsed_at":"2026-02-17T12:04:38.766Z","dependency_job_id":null,"html_url":"https://github.com/OpenRouterLabs/spawn","commit_stats":null,"previous_names":["openrouterteam/spawn","openrouterlabs/spawn"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/OpenRouterLabs/spawn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenRouterLabs%2Fspawn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenRouterLabs%2Fspawn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenRouterLabs%2Fspawn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenRouterLabs%2Fspawn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenRouterLabs","download_url":"https://codeload.github.com/OpenRouterLabs/spawn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenRouterLabs%2Fspawn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34116461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","cli","codex","openclaw","vm"],"created_at":"2026-05-24T01:00:33.380Z","updated_at":"2026-06-09T17:00:41.522Z","avatar_url":"https://github.com/OpenRouterLabs.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Spawn\n\nLaunch any AI agent on any cloud with a single command. Coding agents, research agents, self-hosted AI tools — Spawn deploys them all. All models powered by [OpenRouter](https://openrouter.ai). (ALPHA software, use at your own risk!)\n\n**10 agents. 8 clouds. 79 working combinations. Zero config.**\n\n## Install\n\n**macOS / Linux — and Windows users inside a WSL2 terminal (Ubuntu, Debian, etc.):**\n```bash\ncurl -fsSL https://openrouter.ai/labs/spawn/cli/install.sh | bash\n```\n\n**Windows PowerShell (outside WSL):**\n```powershell\nirm https://openrouter.ai/labs/spawn/cli/install.ps1 | iex\n```\n\n## Usage\n\n```bash\nspawn                         # Interactive picker\nspawn \u003cagent\u003e \u003ccloud\u003e         # Launch directly\nspawn matrix                  # Show the full agent x cloud matrix\n```\n\n### Examples\n\n```bash\nspawn                                    # Interactive picker\nspawn claude sprite                      # Claude Code on Sprite\nspawn codex hetzner                      # Codex CLI on Hetzner\nspawn claude sprite --prompt \"Fix bugs\"  # Non-interactive with prompt\nspawn codex sprite -p \"Add tests\"        # Short form\nspawn claude                             # Show clouds available for Claude\nspawn delete                             # Delete a running server\nspawn delete -c hetzner                  # Delete a server on Hetzner\n```\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `spawn` | Interactive agent + cloud picker |\n| `spawn \u003cagent\u003e \u003ccloud\u003e` | Launch agent on cloud directly |\n| `spawn \u003cagent\u003e \u003ccloud\u003e --dry-run` | Preview without provisioning |\n| `spawn \u003cagent\u003e \u003ccloud\u003e --zone \u003czone\u003e` | Set zone/region for the cloud |\n| `spawn \u003cagent\u003e \u003ccloud\u003e --size \u003ctype\u003e` | Set instance size/type for the cloud |\n| `spawn \u003cagent\u003e \u003ccloud\u003e --prompt \"text\"` | Non-interactive with prompt (or `-p`) |\n| `spawn \u003cagent\u003e \u003ccloud\u003e --prompt-file \u003cfile\u003e` | Prompt from file (or `-f`) |\n| `spawn \u003cagent\u003e \u003ccloud\u003e --headless` | Provision and exit (no interactive session) |\n| `spawn \u003cagent\u003e \u003ccloud\u003e --output json` | Headless mode with structured JSON on stdout |\n| `spawn \u003cagent\u003e \u003ccloud\u003e --model \u003cid\u003e` | Set the model ID (overrides agent default) |\n| `spawn \u003cagent\u003e \u003ccloud\u003e --config \u003cfile\u003e` | Load options from a JSON config file |\n| `spawn \u003cagent\u003e \u003ccloud\u003e --steps \u003clist\u003e` | Comma-separated setup steps to enable |\n| `spawn \u003cagent\u003e \u003ccloud\u003e --custom` | Show interactive size/region pickers |\n| `spawn \u003cagent\u003e gcp --no-secure-boot` | Disable GCP Shielded VM (Secure Boot is on by default) |\n| `spawn \u003cagent\u003e` | Show available clouds for an agent |\n| `spawn \u003ccloud\u003e` | Show available agents for a cloud |\n| `spawn matrix` | Full agent x cloud matrix |\n| `spawn list` | Browse and rerun previous spawns |\n| `spawn list \u003cfilter\u003e` | Filter history by agent or cloud name |\n| `spawn list -a \u003cagent\u003e` | Filter history by agent |\n| `spawn list -c \u003ccloud\u003e` | Filter history by cloud |\n| `spawn list --flat` | Show flat list (disable tree view) |\n| `spawn list --json` | Output history as JSON |\n| `spawn list --clear` | Clear all spawn history |\n| `spawn tree` | Show recursive spawn tree (parent/child relationships) |\n| `spawn tree --json` | Output spawn tree as JSON |\n| `spawn history export` | Dump history as JSON to stdout (used by parent VMs) |\n| `spawn fix` | Re-run agent setup on an existing VM (re-inject credentials, reinstall) |\n| `spawn fix \u003cspawn-id\u003e` | Fix a specific spawn by name or ID |\n| `spawn link \u003cip\u003e` | Register an existing VM by IP |\n| `spawn link \u003cip\u003e --agent \u003cagent\u003e` | Specify the agent running on the VM |\n| `spawn link \u003cip\u003e --cloud \u003ccloud\u003e` | Specify the cloud provider |\n| `spawn last` | Instantly rerun the most recent spawn |\n| `spawn agents` | List all agents with descriptions |\n| `spawn clouds` | List all cloud providers |\n| `spawn feedback \"message\"` | Send feedback to the Spawn team |\n| `spawn uninstall` | Uninstall spawn CLI and optionally remove data |\n| `spawn update` | Check for CLI updates |\n| `spawn delete` | Interactively select and destroy a cloud server |\n| `spawn delete -a \u003cagent\u003e` | Filter servers to delete by agent |\n| `spawn delete -c \u003ccloud\u003e` | Filter servers to delete by cloud |\n| `spawn delete --name \u003cname\u003e --yes` | Headless delete by name (no prompts) |\n| `spawn status` | Show live state of cloud servers |\n| `spawn status -a \u003cagent\u003e` | Filter status by agent |\n| `spawn status -c \u003ccloud\u003e` | Filter status by cloud |\n| `spawn status --prune` | Remove gone servers from history |\n| `spawn help` | Show help message |\n| `spawn version` | Show version |\n\n#### Config File\n\nThe `--config` flag loads options from a JSON file. CLI flags override config values.\n\n```json\n{\n  \"model\": \"openai/gpt-5.3-codex\",\n  \"steps\": [\"github\", \"browser\", \"telegram\"],\n  \"name\": \"my-dev-box\",\n  \"setup\": {\n    \"telegram_bot_token\": \"123456:ABC-DEF...\",\n    \"github_token\": \"ghp_xxxx\"\n  }\n}\n```\n\n```bash\nspawn codex gcp --config setup.json --headless --output json\n```\n\n#### Setup Steps\n\nControl which optional setup steps run with `--steps`:\n\n```bash\nspawn openclaw gcp --steps github,browser     # Only GitHub + Chrome\nspawn claude gcp --steps \"\"                    # Skip all optional steps\n```\n\nAvailable steps vary by agent:\n\n| Step | Agents | Description |\n|------|--------|-------------|\n| `github` | All | GitHub CLI + git identity |\n| `reuse-api-key` | All | Reuse saved OpenRouter key |\n| `browser` | openclaw | Chrome browser (~400 MB) |\n| `telegram` | openclaw | Telegram bot (set `TELEGRAM_BOT_TOKEN` for non-interactive) |\n| `whatsapp` | openclaw | WhatsApp linking (interactive QR scan, skipped in headless) |\n\n#### Fast Mode\n\nUse `--fast` for significantly faster deploys. Enables all speed optimizations:\n\n```bash\nspawn claude hetzner --fast\n```\n\nWhat `--fast` does:\n- **Parallel boot**: server creation runs concurrently with API key prompt and account checks\n- **Tarballs**: installs agents from pre-built tarballs instead of live install\n- **Skip cloud-init**: for lightweight agents (Claude, OpenCode, Hermes), skips the package install wait since the base OS already has what's needed\n- **Snapshots**: uses pre-built cloud images when available (Hetzner, DigitalOcean)\n\n#### Beta Features\n\nIndividual optimizations can be enabled separately with `--beta \u003cfeature\u003e`. The flag is repeatable:\n\n```bash\nspawn claude gcp --beta tarball --beta parallel\n```\n\n| Feature | Description |\n|---------|-------------|\n| `tarball` | Use pre-built tarball for agent install (faster, skips live install) |\n| `images` | Use pre-built cloud images/snapshots (faster boot) |\n| `parallel` | Parallelize server boot with setup prompts |\n| `recursive` | Install spawn CLI on VM so it can spawn child VMs |\n\n`--fast` enables `tarball`, `images`, and `parallel` (not `recursive`).\n\n#### Secure Boot (GCP)\n\nGCP instances are provisioned as [Shielded VMs](https://cloud.google.com/security/shielded-cloud/shielded-vm)\n**by default** — Secure Boot, vTPM, and integrity monitoring are all enabled. This\nhardens the boot chain and is required for the Cloudflare (CF) skill to attest the VM.\nGCP's default Ubuntu LTS images are Shielded-VM-compatible, so this works out of the box.\n\nOpt out for a custom image that is not UEFI/Secure-Boot-capable:\n\n```bash\nspawn claude gcp --no-secure-boot\n```\n\n\u003e Secure Boot is a GCP-only feature here. AWS spawns run on Lightsail, which does not\n\u003e expose Secure Boot; the flag is a no-op on other clouds.\n\n#### Recursive Spawn\n\nUse `--beta recursive` to let spawned VMs create their own child VMs:\n\n```bash\nspawn claude hetzner --beta recursive\n```\n\nWhat this does:\n- **Installs spawn CLI** on the remote VM\n- **Delegates credentials** (cloud + OpenRouter) so child VMs can authenticate\n- **Injects parent tracking** (`SPAWN_PARENT_ID`, `SPAWN_DEPTH`) into the VM environment\n- **Passes `--beta recursive`** to children so they can also spawn recursively\n\nView the spawn tree:\n```bash\nspawn tree\n# spawn-abc  Claude Code / Hetzner  2m ago\n#   ├─ spawn-def  Codex CLI / Hetzner  1m ago\n#   └─ spawn-ghi  OpenClaw / Hetzner  30s ago\n#       └─ spawn-jkl  Claude Code / Hetzner  10s ago\n```\n\nTear down an entire tree:\n```bash\nspawn delete --cascade \u003cid\u003e    # Delete a VM and all its children\n```\n\n#### Local Sandbox\n\nThe `sandbox` cloud runs an agent inside a throwaway Docker container on your own machine, instead of directly on your host:\n\n```bash\nspawn claude sandbox\n```\n\nWhat this does:\n- **Pulls the agent's Docker image** from `ghcr.io/openrouterteam/spawn-\u003cagent\u003e`\n- **Runs the agent in a container** with filesystem, network, and process isolation\n- **Auto-installs Docker** if not present (OrbStack on macOS, docker.io on Linux)\n- **Cleans up the container** automatically when the session ends\n\nIt's the same setup as the `local` cloud, but the agent can't touch your host filesystem, shell, or SSH keys. (This was previously the `--beta sandbox` flag.)\n\n### Without the CLI\n\nEvery combination works as a one-liner — no install required:\n\n```bash\nbash \u003c(curl -fsSL https://openrouter.ai/labs/spawn/{cloud}/{agent}.sh)\n```\n\n### Non-Interactive Mode\n\nSkip prompts by providing environment variables:\n\n```bash\n# OpenRouter API key (required for all agents)\nexport OPENROUTER_API_KEY=sk-or-v1-xxxxx\n\n# Cloud-specific credentials (varies by provider)\n# Note: Sprite uses `sprite login` for authentication\nexport HCLOUD_TOKEN=...           # For Hetzner\nexport DIGITALOCEAN_ACCESS_TOKEN=...  # For DigitalOcean\n\n# Run non-interactively\nspawn claude hetzner\n```\n\nYou can also use inline environment variables:\n\n```bash\nOPENROUTER_API_KEY=sk-or-v1-xxxxx spawn claude sprite\n```\n\nGet your OpenRouter API key at: https://openrouter.ai/settings/keys\n\nFor cloud-specific auth, see each cloud's README in this repository.\n\n## Troubleshooting\n\n### Installation issues\n\nIf spawn fails to install, try these steps:\n\n1. **Check bun version**: spawn requires bun \u003e= 1.2.0\n   ```bash\n   bun --version\n   bun upgrade  # if needed\n   ```\n\n2. **Manual installation**: If auto-install fails, install bun first\n   ```bash\n   curl -fsSL https://bun.sh/install | bash\n   source ~/.bashrc  # or ~/.zshrc for zsh\n   curl -fsSL https://openrouter.ai/labs/spawn/cli/install.sh | bash\n   ```\n\n3. **PATH issues**: If `spawn` command not found after install\n   ```bash\n   # Add to your shell config (~/.bashrc or ~/.zshrc)\n   export PATH=\"$HOME/.local/bin:$PATH\"\n   ```\n\n### Windows (PowerShell)\n\n1. **Use the PowerShell installer** — not the bash one:\n   ```powershell\n   irm https://openrouter.ai/labs/spawn/cli/install.ps1 | iex\n   ```\n   The `.ps1` extension is required. The default `install.sh` is bash and won't work in PowerShell.\n\n2. **Set credentials via environment variables** before launching:\n   ```powershell\n   $env:OPENROUTER_API_KEY = \"sk-or-v1-xxxxx\"\n   $env:DIGITALOCEAN_ACCESS_TOKEN = \"dop_v1_xxxxx\"  # For DigitalOcean\n   $env:HCLOUD_TOKEN = \"xxxxx\"              # For Hetzner\n   spawn openclaw digitalocean\n   ```\n\n3. **Local build failures during auto-update** are normal on Windows — the CLI falls back to a pre-built binary automatically. You may see a brief build error followed by a successful update.\n\n4. **EISDIR or EEXIST errors on config files**: If you see errors about `digitalocean.json` being a directory, delete it:\n   ```powershell\n   Remove-Item -Recurse -Force \"$HOME\\.config\\spawn\\digitalocean.json\" -ErrorAction SilentlyContinue\n   spawn openclaw digitalocean\n   ```\n\n### Headless JSON mode — agent exits immediately\n\nWhen using `--headless --output json` with Claude Code, you must also pass `--prompt` (or `-p`). Without it, Claude exits with `Input must be provided through stdin or --prompt` and the JSON output will show `\"status\":\"error\"`:\n\n```bash\n# WRONG — Claude exits immediately\nspawn claude gcp --headless --output json\n\n# RIGHT — provide a prompt\nspawn claude gcp --headless --output json --prompt \"Fix all linter errors\"\n```\n\nNote: auto-update messages may appear before the JSON on older CLI versions. Run `spawn update` to get the fix.\n\n### Agent launch failures\n\nIf an agent fails to install or launch on a cloud:\n\n1. **Check credentials**: Ensure cloud provider credentials are set\n   ```bash\n   # Example for Hetzner\n   export HCLOUD_TOKEN=your-token-here\n   spawn claude hetzner\n   ```\n\n2. **Try a different cloud**: Some clouds may have temporary issues\n   ```bash\n   spawn \u003cagent\u003e  # Interactive picker to choose another cloud\n   ```\n\n3. **Use --dry-run**: Preview what spawn will do before provisioning\n   ```bash\n   spawn claude hetzner --dry-run\n   ```\n\n4. **Check cloud status**: Visit your cloud provider's status page\n   - Many failures are transient (network timeouts, package mirror issues)\n   - Retrying often succeeds\n\n### Getting help\n\n- **View command history**: `spawn list` shows all previous launches\n- **Rerun last session**: `spawn last` or `spawn rerun`\n- **Check version**: `spawn version` shows CLI version and cache status\n- **Update spawn**: `spawn update` checks for the latest version\n- **Report bugs**: Open an issue at https://github.com/OpenRouterLabs/spawn/issues\n\n## Matrix\n\n| | [Local Machine](sh/local/) | [Local Sandbox](sh/sandbox/) | [Hetzner Cloud](sh/hetzner/) | [AWS Lightsail](sh/aws/) | [DigitalOcean](sh/digitalocean/) | [GCP Compute Engine](sh/gcp/) | [Daytona](sh/daytona/) | [Sprite](sh/sprite/) |\n|---|---|---|---|---|---|---|---|---|\n| [**Claude Code**](https://claude.ai) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| [**OpenClaw**](https://github.com/openclaw/openclaw) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| [**Codex CLI**](https://github.com/openai/codex) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| [**OpenCode**](https://github.com/anomalyco/opencode) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| [**Kilo Code**](https://github.com/Kilo-Org/kilocode) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| [**Hermes Agent**](https://github.com/NousResearch/hermes-agent) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| [**Junie**](https://www.jetbrains.com/junie/) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| [**Cursor CLI**](https://cursor.com/cli) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| [**Pi**](https://pi.dev) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| [**T3 Code**](https://github.com/pingdotgg/t3code) | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n\n### How it works\n\nEach cell in the matrix is a self-contained bash script that:\n\n1. Provisions a server on the cloud provider\n2. Installs the agent\n3. Injects your [OpenRouter](https://openrouter.ai) API key so every agent uses the same billing\n4. Drops you into an interactive session\n\nScripts work standalone (`bash \u003c(curl ...)`) or through the CLI.\n\n## Development\n\n```bash\ngit clone https://github.com/OpenRouterLabs/spawn.git\ncd spawn\ngit config core.hooksPath .githooks\n```\n\n### Structure\n\n```\nsh/{cloud}/{agent}.sh     # Agent deployment script (thin bash → bun wrapper)\npackages/cli/             # TypeScript CLI — all provisioning logic (bun)\nmanifest.json             # Source of truth for the matrix\n```\n\n### Adding a new cloud\n\n1. Add cloud-specific TypeScript module in `packages/cli/src/{cloud}/`\n2. Add to `manifest.json`\n3. Implement agent scripts\n4. See [CLAUDE.md](CLAUDE.md) for full contributor guide\n\n### Adding a new agent\n\n1. Add to `manifest.json`\n2. Implement on 1+ cloud by adapting an existing agent script\n3. Must support OpenRouter via env var injection\n\n## Contributing\n\nThe easiest way to contribute is by testing and reporting issues. You don't need to write code.\n\n### Test a cloud provider\n\nPick any agent + cloud combination from the matrix and try it out:\n\n```bash\nspawn claude hetzner      # or any combination\n```\n\nIf something breaks, hangs, or behaves unexpectedly, open an issue using the [bug report template](https://github.com/OpenRouterLabs/spawn/issues/new?template=bug_report.yml). Include:\n\n- The exact command you ran\n- The cloud provider and agent\n- What happened vs. what you expected\n- Any error output\n\n### Request a cloud or agent\n\nWant to see a specific cloud provider or agent supported? Use the dedicated templates:\n\n- [Request a cloud provider](https://github.com/OpenRouterLabs/spawn/issues/new?template=cloud_request.yml)\n- [Request an agent](https://github.com/OpenRouterLabs/spawn/issues/new?template=agent_request.yml)\n- [Request a CLI feature](https://github.com/OpenRouterLabs/spawn/issues/new?template=cli_feature_request.yml)\n\nRequests with real-world use cases get prioritized.\n\n### Report auth or credential issues\n\nCloud provider APIs change frequently. If you hit authentication failures, expired tokens, or permission errors on a provider that previously worked, please report it — these are high-priority fixes.\n\n### Code contributions\n\nSee [CLAUDE.md](CLAUDE.md) for the full contributor guide covering shell script rules, testing, and the shared library pattern.\n\n## License\n\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenRouterLabs%2Fspawn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOpenRouterLabs%2Fspawn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenRouterLabs%2Fspawn/lists"}