spawn/README.md

Spawn

Launch 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. (ALPHA software, use at your own risk!)

8 agents. 6 clouds. 48 working combinations. Zero config.

Install

macOS / Linux — and Windows users inside a WSL2 terminal (Ubuntu, Debian, etc.):

curl -fsSL https://openrouter.ai/labs/spawn/cli/install.sh | bash

Windows PowerShell (outside WSL):

irm https://openrouter.ai/labs/spawn/cli/install.ps1 | iex

Usage

spawn                         # Interactive picker
spawn <agent> <cloud>         # Launch directly
spawn matrix                  # Show the full agent x cloud matrix

Examples

spawn                                    # Interactive picker
spawn claude sprite                      # Claude Code on Sprite
spawn codex hetzner                      # Codex CLI on Hetzner
spawn claude sprite --prompt "Fix bugs"  # Non-interactive with prompt
spawn codex sprite -p "Add tests"        # Short form
spawn claude                             # Show clouds available for Claude
spawn delete                             # Delete a running server
spawn delete -c hetzner                  # Delete a server on Hetzner

Commands

Command	Description
spawn	Interactive agent + cloud picker
spawn <agent> <cloud>	Launch agent on cloud directly
spawn <agent> <cloud> --dry-run	Preview without provisioning
spawn <agent> <cloud> --zone <zone>	Set zone/region for the cloud
spawn <agent> <cloud> --size <type>	Set instance size/type for the cloud
spawn <agent> <cloud> -p "text"	Non-interactive with prompt
spawn <agent> <cloud> --prompt-file f.txt	Prompt from file
spawn <agent> <cloud> --headless	Provision and exit (no interactive session)
spawn <agent> <cloud> --output json	Headless mode with structured JSON on stdout
spawn <agent> <cloud> --model <id>	Set the model ID (overrides agent default)
spawn <agent> <cloud> --config <file>	Load options from a JSON config file
spawn <agent> <cloud> --steps <list>	Comma-separated setup steps to enable
spawn <agent> <cloud> --custom	Show interactive size/region pickers
spawn <agent>	Show available clouds for an agent
spawn <cloud>	Show available agents for a cloud
spawn matrix	Full agent x cloud matrix
spawn list	Browse and rerun previous spawns
spawn list <filter>	Filter history by agent or cloud name
spawn list -a <agent>	Filter history by agent
spawn list -c <cloud>	Filter history by cloud
spawn list --clear	Clear all spawn history
spawn last	Instantly rerun the most recent spawn
spawn agents	List all agents with descriptions
spawn clouds	List all cloud providers
spawn update	Check for CLI updates
spawn delete	Interactively select and destroy a cloud server
spawn delete -a <agent>	Filter servers to delete by agent
spawn delete -c <cloud>	Filter servers to delete by cloud
spawn status	Show live state of cloud servers
spawn status -a <agent>	Filter status by agent
spawn status -c <cloud>	Filter status by cloud
spawn status --prune	Remove gone servers from history
spawn help	Show help message
spawn version	Show version
spawn <agent> <cloud> --beta <feature>	Opt-in to an experimental feature (repeatable)

Config File

The --config flag loads options from a JSON file. CLI flags override config values.

{
  "model": "openai/gpt-5.3-codex",
  "steps": ["github", "browser", "telegram"],
  "name": "my-dev-box",
  "setup": {
    "telegram_bot_token": "123456:ABC-DEF...",
    "github_token": "ghp_xxxx"
  }
}

spawn codex gcp --config setup.json --headless --output json

Setup Steps

Control which optional setup steps run with --steps:

spawn openclaw gcp --steps github,browser     # Only GitHub + Chrome
spawn claude gcp --steps ""                    # Skip all optional steps

Available steps vary by agent:

Step	Agents	Description
github	All	GitHub CLI + git identity
reuse-api-key	All	Reuse saved OpenRouter key
browser	openclaw	Chrome browser (~400 MB)
telegram	openclaw	Telegram bot (set TELEGRAM_BOT_TOKEN for non-interactive)
whatsapp	openclaw	WhatsApp linking (interactive QR scan, skipped in headless)

Beta Features

Experimental features can be enabled with --beta <feature>. The flag is repeatable:

spawn claude gcp --beta tarball

Feature	Description
tarball	Use pre-built tarball for agent install (faster, skips live install)

Without the CLI

Every combination works as a one-liner — no install required:

bash <(curl -fsSL https://openrouter.ai/labs/spawn/{cloud}/{agent}.sh)

Non-Interactive Mode

Skip prompts by providing environment variables:

# OpenRouter API key (required for all agents)
export OPENROUTER_API_KEY=sk-or-v1-xxxxx

# Cloud-specific credentials (varies by provider)
# Note: Sprite uses `sprite login` for authentication
export HCLOUD_TOKEN=...           # For Hetzner
export DO_API_TOKEN=...           # For DigitalOcean

# Run non-interactively
spawn claude hetzner

You can also use inline environment variables:

OPENROUTER_API_KEY=sk-or-v1-xxxxx spawn claude sprite

Get your OpenRouter API key at: https://openrouter.ai/settings/keys

For cloud-specific auth, see each cloud's README in this repository.

Troubleshooting

Installation issues

If spawn fails to install, try these steps:

1. Check bun version: spawn requires bun >= 1.2.0

   bun --version
   bun upgrade  # if needed
   

2. Manual installation: If auto-install fails, install bun first

   curl -fsSL https://bun.sh/install | bash
   source ~/.bashrc  # or ~/.zshrc for zsh
   curl -fsSL https://openrouter.ai/labs/spawn/cli/install.sh | bash
   

3. PATH issues: If spawn command not found after install

   # Add to your shell config (~/.bashrc or ~/.zshrc)
   export PATH="$HOME/.local/bin:$PATH"
   

Agent launch failures

If an agent fails to install or launch on a cloud:

1. Check credentials: Ensure cloud provider credentials are set

   # Example for Hetzner
   export HCLOUD_TOKEN=your-token-here
   spawn claude hetzner
   

2. Try a different cloud: Some clouds may have temporary issues

   spawn <agent>  # Interactive picker to choose another cloud
   

3. Use --dry-run: Preview what spawn will do before provisioning

   spawn claude hetzner --dry-run
   

4. Check cloud status: Visit your cloud provider's status page

   • Many failures are transient (network timeouts, package mirror issues)
   • Retrying often succeeds

Getting help

• View command history: spawn list shows all previous launches
• Rerun last session: spawn last or spawn rerun
• Check version: spawn version shows CLI version and cache status
• Update spawn: spawn update checks for the latest version
• Report bugs: Open an issue at https://github.com/OpenRouterTeam/spawn/issues

Matrix

	Local Machine	Hetzner Cloud	AWS Lightsail	DigitalOcean	GCP Compute Engine	Sprite
Claude Code	✓	✓	✓	✓	✓	✓
OpenClaw	✓	✓	✓	✓	✓	✓
ZeroClaw	✓	✓	✓	✓	✓	✓
Codex CLI	✓	✓	✓	✓	✓	✓
OpenCode	✓	✓	✓	✓	✓	✓
Kilo Code	✓	✓	✓	✓	✓	✓
Hermes Agent	✓	✓	✓	✓	✓	✓
Junie	✓	✓	✓	✓	✓	✓

How it works

Each cell in the matrix is a self-contained bash script that:

1. Provisions a server on the cloud provider
2. Installs the agent
3. Injects your OpenRouter API key so every agent uses the same billing
4. Drops you into an interactive session

Scripts work standalone (bash <(curl ...)) or through the CLI.

Development

git clone https://github.com/OpenRouterTeam/spawn.git
cd spawn
git config core.hooksPath .githooks

Structure

sh/{cloud}/{agent}.sh     # Agent deployment script (thin bash → bun wrapper)
packages/cli/             # TypeScript CLI — all provisioning logic (bun)
manifest.json             # Source of truth for the matrix

Adding a new cloud

1. Add cloud-specific TypeScript module in packages/cli/src/{cloud}/
2. Add to manifest.json
3. Implement agent scripts
4. See CLAUDE.md for full contributor guide

Adding a new agent

1. Add to manifest.json
2. Implement on 1+ cloud by adapting an existing agent script
3. Must support OpenRouter via env var injection

Contributing

The easiest way to contribute is by testing and reporting issues. You don't need to write code.

Test a cloud provider

Pick any agent + cloud combination from the matrix and try it out:

spawn claude hetzner      # or any combination

If something breaks, hangs, or behaves unexpectedly, open an issue using the bug report template. Include:

• The exact command you ran
• The cloud provider and agent
• What happened vs. what you expected
• Any error output

Request a cloud or agent

Want to see a specific cloud provider or agent supported? Use the dedicated templates:

• Request a cloud provider
• Request an agent
• Request a CLI feature

Requests with real-world use cases get prioritized.

Report auth or credential issues

Cloud 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.

Code contributions

See CLAUDE.md for the full contributor guide covering shell script rules, testing, and the shared library pattern.

License

Apache 2.0