spawn/CLAUDE.md

Spawn

Spawn is a matrix of agents x clouds. Every script provisions a cloud server, installs an agent, injects OpenRouter credentials, and drops the user into an interactive session.

The Matrix

manifest.json is the source of truth. It tracks:

• agents — coding agents / AI tools (Claude Code, OpenClaw, NanoClaw, ...)
• clouds — cloud providers to run them on (Sprite, Hetzner, ...)
• matrix — which cloud/agent combinations are "implemented" vs "missing"

How to Improve Spawn

When run via ./improve.sh, your job is to pick ONE of these tasks and execute it:

1. Fill a missing matrix entry

Look at manifest.json → matrix for any "missing" entry. To implement it:

• Find the cloud's lib/common.sh — it has all the provider-specific primitives (create server, run command, upload file, interactive session)
• Find the agent's existing script on another cloud — it shows the install steps, config files, env vars, and launch command
• Combine them: use the cloud's primitives to execute the agent's setup steps
• The script goes at {cloud}/{agent}.sh

Pattern for every script:

1. Source {cloud}/lib/common.sh (local or remote fallback)
2. Authenticate with cloud provider
3. Provision server/VM
4. Wait for readiness
5. Install the agent
6. Get OpenRouter API key (env var or OAuth)
7. Inject env vars into shell config
8. Write agent-specific config files
9. Launch interactive session

OpenRouter injection is mandatory. Every agent script MUST:

• Set OPENROUTER_API_KEY in the shell environment
• Set provider-specific env vars (e.g., ANTHROPIC_BASE_URL=https://openrouter.ai/api)
• These come from the agent's env field in manifest.json

2. Add a new agent

Research coding agents, AI CLI tools, or AI-powered dev tools. To add one:

1. Add an entry to manifest.json → agents with: name, description, url, install command, launch command, and env vars needed for OpenRouter
2. Add "missing" entries to the matrix for every existing cloud
3. Implement the script for at least one cloud
4. Update README.md

Where to find new agents:

• GitHub trending in AI/coding categories
• OpenRouter's ecosystem
• HuggingFace agent frameworks
• CLI tools that accept ANTHROPIC_API_KEY or OPENAI_API_KEY (these work with OpenRouter via base URL override)

3. Add a new cloud provider

Research cloud providers with API-based provisioning. To add one:

1. Create {cloud}/lib/common.sh with the provider's primitives:
   • Auth/token management (env var → config file → prompt)
   • Server creation (API call or CLI)
   • SSH/exec connectivity
   • File upload
   • Interactive session
   • Server destruction
2. Add an entry to manifest.json → clouds
3. Add "missing" entries to the matrix for every existing agent
4. Implement at least one agent script
5. Update README.md

Good candidate clouds have:

• REST API or simple CLI for provisioning
• SSH access to the created server
• Cloud-init or similar userdata support
• Pay-per-hour pricing (so users can destroy after use)

4. Extend tests

test/run.sh contains the test harness. When adding a new cloud or agent:

• Add mock functions for the cloud's CLI/API calls
• Add per-script assertions matching the agent's setup steps
• Run bash test/run.sh to verify

File Structure Convention

spawn/
  {cloud}/
    lib/common.sh     # Cloud-specific shared functions
    {agent}.sh        # One script per agent
  manifest.json       # The matrix (source of truth)
  improve.sh          # Run this to trigger one improvement cycle
  test/run.sh         # Test harness
  README.md           # User-facing docs

Script Conventions

• #!/bin/bash + set -e
• Source lib/common.sh with local-first, remote-fallback pattern
• Use OPENROUTER_API_KEY env var to skip OAuth when set
• All env vars documented in README.md under the relevant section
• Remote fallback URL: https://raw.githubusercontent.com/OpenRouterTeam/spawn/main/{path}
• Scripts must be runnable via: bash <(curl -fsSL https://openrouter.ai/lab/spawn/{cloud}/{agent}.sh)

After Each Change

1. Update manifest.json matrix status to "implemented"
2. Update README.md with usage instructions
3. Run bash test/run.sh if tests exist for the cloud
4. Commit with a descriptive message