mirror of
https://github.com/OpenRouterTeam/spawn.git
synced 2026-04-30 12:59:32 +00:00
298065f4ad
Enhance the spawn CLI user experience with actionable error messages, comprehensive help documentation, and visual progress feedback. Changes: - Help text: Add AUTHENTICATION, TROUBLESHOOTING, and MORE INFO sections - Error messages: Show examples of valid options when validation fails - Progress indicators: Add spinners for script downloads - Install flow: Provide clear alternatives when npm install requires sudo - README: Add environment variable documentation and alternative install URL - Security errors: Suggest workarounds for false positives All error messages now follow the pattern: 1. What went wrong 2. Why it matters 3. What to do next Documentation: .docs/UX_IMPROVEMENTS_20260208.md Co-authored-by: Sprite <noreply@sprite.dev> Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
149 lines
6.2 KiB
Markdown
149 lines
6.2 KiB
Markdown
# Spawn
|
|
|
|
Launch any AI coding agent on any cloud with a single command. All models powered by [OpenRouter](https://openrouter.ai). (ALPHA software, use at your own risk!)
|
|
|
|
**13 agents. 18 clouds. 234 combinations. Zero config.**
|
|
|
|
## Install
|
|
|
|
```bash
|
|
curl -fsSL https://openrouter.ai/lab/spawn/cli/install.sh | bash
|
|
```
|
|
|
|
Or install directly from GitHub:
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/OpenRouterTeam/spawn/main/cli/install.sh | bash
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
spawn # Interactive picker
|
|
spawn <agent> <cloud> # Launch directly
|
|
spawn list # Show the full matrix
|
|
```
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
spawn # Interactive picker
|
|
spawn claude sprite # Claude Code on Sprite
|
|
spawn aider hetzner # Aider on Hetzner
|
|
spawn claude sprite --prompt "Fix bugs" # Non-interactive with prompt
|
|
spawn aider sprite -p "Add tests" # Short form
|
|
spawn claude # Show clouds available for Claude
|
|
```
|
|
|
|
### Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `spawn` | Interactive agent + cloud picker |
|
|
| `spawn <agent> <cloud>` | Launch agent on cloud directly |
|
|
| `spawn <agent> <cloud> -p "text"` | Non-interactive with prompt |
|
|
| `spawn <agent> <cloud> --prompt-file f.txt` | Prompt from file |
|
|
| `spawn <agent>` | Show available clouds for an agent |
|
|
| `spawn list` | Full agent x cloud matrix |
|
|
| `spawn agents` | List all agents |
|
|
| `spawn clouds` | List all cloud providers |
|
|
| `spawn update` | Check for CLI updates |
|
|
|
|
### Without the CLI
|
|
|
|
Every combination works as a one-liner — no install required:
|
|
|
|
```bash
|
|
bash <(curl -fsSL https://openrouter.ai/lab/spawn/{cloud}/{agent}.sh)
|
|
```
|
|
|
|
### Non-Interactive Mode
|
|
|
|
Skip prompts by providing environment variables:
|
|
|
|
```bash
|
|
# OpenRouter API key (required for all agents)
|
|
export OPENROUTER_API_KEY=sk-or-v1-xxxxx
|
|
|
|
# Cloud-specific credentials (varies by provider)
|
|
export SPRITE_API_KEY=... # For Sprite
|
|
export HCLOUD_TOKEN=... # For Hetzner
|
|
export DIGITALOCEAN_TOKEN=... # For DigitalOcean
|
|
|
|
# Run non-interactively
|
|
spawn claude sprite
|
|
```
|
|
|
|
You can also use inline environment variables:
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Matrix
|
|
|
|
| | [Sprite](sprite/) | [Hetzner](hetzner/) | [DigitalOcean](digitalocean/) | [Vultr](vultr/) | [Linode](linode/) | [Lambda](lambda/) | [Lightsail](aws-lightsail/) | [GCP](gcp/) | [E2B](e2b/) | [Modal](modal/) | [Fly.io](fly/) | [Civo](civo/) | [Scaleway](scaleway/) | [Daytona](daytona/) | [RunPod](runpod/) | [UpCloud](upcloud/) | [BinaryLane](binarylane/) | [Genesis Cloud](genesiscloud/) |
|
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
| [**Claude Code**](https://claude.ai) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
| [**OpenClaw**](https://github.com/OpenRouterTeam/openclaw) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
| [**NanoClaw**](https://github.com/gavrielc/nanoclaw) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
| [**Aider**](https://github.com/paul-gauthier/aider) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
| [**Goose**](https://github.com/block/goose) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
| [**Codex CLI**](https://github.com/openai/codex) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
| [**Open Interpreter**](https://github.com/OpenInterpreter/open-interpreter) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
| [**Gemini CLI**](https://github.com/google-gemini/gemini-cli) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
| [**Amazon Q CLI**](https://aws.amazon.com/q/developer/) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
| [**Cline**](https://github.com/cline/cline) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
| [**gptme**](https://github.com/gptme/gptme) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
| [**OpenCode**](https://github.com/opencode-ai/opencode) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
| [**Plandex**](https://github.com/plandex-ai/plandex) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
|
|
### 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 coding agent
|
|
3. Injects your [OpenRouter](https://openrouter.ai) 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
|
|
|
|
```bash
|
|
git clone https://github.com/OpenRouterTeam/spawn.git
|
|
cd spawn
|
|
git config core.hooksPath .githooks
|
|
```
|
|
|
|
### Structure
|
|
|
|
```
|
|
{cloud}/lib/common.sh # Cloud provider primitives (provision, SSH, cleanup)
|
|
{cloud}/{agent}.sh # Agent deployment script
|
|
shared/common.sh # Shared utilities (OAuth, logging, SSH helpers)
|
|
cli/ # TypeScript CLI (bun)
|
|
manifest.json # Source of truth for the matrix
|
|
```
|
|
|
|
### Adding a new cloud
|
|
|
|
1. Create `{cloud}/lib/common.sh` with provisioning primitives
|
|
2. Add to `manifest.json`
|
|
3. Implement agent scripts using the cloud's primitives
|
|
4. See [CLAUDE.md](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
|
|
|
|
## License
|
|
|
|
[Apache 2.0](LICENSE)
|