{"id":49111158,"url":"https://github.com/OpenRouterTeam/spawn","last_synced_at":"2026-05-07T11:01:11.138Z","repository":{"id":336522125,"uuid":"1147571355","full_name":"OpenRouterTeam/spawn","owner":"OpenRouterTeam","description":"Spawn any agent, on any cloud","archived":false,"fork":false,"pushed_at":"2026-05-02T08:30:25.000Z","size":11307,"stargazers_count":139,"open_issues_count":23,"forks_count":22,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-02T08:34:25.372Z","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/OpenRouterTeam.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-05-02T07:42:19.000Z","dependencies_parsed_at":"2026-02-17T12:04:38.766Z","dependency_job_id":null,"html_url":"https://github.com/OpenRouterTeam/spawn","commit_stats":null,"previous_names":["openrouterteam/spawn"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/OpenRouterTeam/spawn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenRouterTeam%2Fspawn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenRouterTeam%2Fspawn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenRouterTeam%2Fspawn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenRouterTeam%2Fspawn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenRouterTeam","download_url":"https://codeload.github.com/OpenRouterTeam/spawn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenRouterTeam%2Fspawn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32734391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-04-21T05:00:40.479Z","updated_at":"2026-05-07T11:01:11.126Z","avatar_url":"https://github.com/OpenRouterTeam.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**9 agents. 7 clouds. 63 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` | 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| `sandbox` | Run local agents in a Docker container (sandboxed) |\n\n`--fast` enables `tarball`, `images`, and `parallel` (not `recursive` or `sandbox`).\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#### Sandboxed Local\n\nUse `--beta sandbox` to run local agents inside a Docker container instead of directly on your machine:\n\n```bash\nspawn claude local --beta 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\nIn the interactive picker, `--beta sandbox` adds a \"Local Machine (Sandboxed)\" option alongside the regular \"Local Machine\":\n\n```bash\nspawn --beta sandbox           # Interactive picker shows both local options\nspawn openclaw local --beta sandbox   # Direct launch, sandboxed\n```\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/OpenRouterTeam/spawn/issues\n\n## Matrix\n\n| | [Local Machine](sh/local/) | [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/sst/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\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/OpenRouterTeam/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/OpenRouterTeam/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/OpenRouterTeam/spawn/issues/new?template=cloud_request.yml)\n- [Request an agent](https://github.com/OpenRouterTeam/spawn/issues/new?template=agent_request.yml)\n- [Request a CLI feature](https://github.com/OpenRouterTeam/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%2FOpenRouterTeam%2Fspawn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOpenRouterTeam%2Fspawn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenRouterTeam%2Fspawn/lists"}