Added shellcheck directive comments before first SSH_OPTS usage in:
- aws-lightsail/lib/common.sh
- gcp/lib/common.sh
- lambda/lib/common.sh
- vultr/lib/common.sh
- linode/lib/common.sh
- hetzner/lib/common.sh
- digitalocean/lib/common.sh
SSH_OPTS is defined in shared/common.sh but shellcheck can't detect
cross-file variable definitions, so we suppress the warning with
an explanatory comment.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Added validate_api_token() to block shell metacharacters
- Added validate_region_name() for cloud regions/zones
- Added validate_resource_name() for server types/sizes
- Added validated_read() wrapper function for easy validation
- Updated 6 cloud libraries to use validated API token input:
- Linode, Vultr, Hetzner, DigitalOcean, E2B, Lambda
- Prevents command injection via API tokens and other inputs
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Split all 16 instances of combined local declaration+assignment to
avoid masking return values. This is a mechanical refactor with no
logic changes.
Fixed lines: 219, 279, 283, 357, 363, 381, 385, 396, 408, 450, 618,
622, 623, 639, 664, 759
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The nc (netcat) approach was fundamentally broken:
- macOS BSD nc has different flags than GNU nc
- nc handles exactly one connection — browsers send favicon, prefetch, etc.
- Pipe-based I/O has race conditions and blocks $() capture
- echo -e doesn't work on macOS bash 3.x for HTTP headers
Replace with Node.js http.createServer (via bun or node):
- Proper HTTP server handles multiple connections
- Parses URL query params correctly (no sed/grep on raw HTTP)
- Sends proper HTTP response with correct headers
- Gracefully ignores favicon/prefetch/extra requests
- Shuts itself down after receiving the callback code
- Works identically on macOS, Linux, and Termux
bun is already a dependency (installed by cloud-init), node is
available on most systems. Falls back to manual API key entry
if neither is available.
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Added shellcheck to catch bash anti-patterns across 115 scripts:
- Created .shellcheckrc configuration
- Added GitHub Actions workflow (.github/workflows/lint.yml)
- Documented shellcheck usage in README
Currently found 3,598 warnings (expected for unlinted codebase).
Using || true temporarily to not block PRs - warnings will be fixed
incrementally in follow-up tasks.
Common issues: SC2250 (missing braces), SC2162 (read without -r),
SC2312 (command substitution masking), SC1091 (sourcing pattern).
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
start_oauth_server was called inside $() to capture the PID, but the
backgrounded nc subshell inherited the $() stdout pipe. Since $()
waits for ALL writers to close, it blocked forever until nc exited
(which never happens — it's listening).
Fix: redirect the subshell's stdout/stderr to /dev/null so it doesn't
hold the pipe open. The PID echo still works because it runs in the
parent (after the & backgrounds the child).
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Round 6 completed 4 high/medium priority tasks:
- Added CLI documentation (366 lines)
- Added error handling and validation to TypeScript CLI
- Added comprehensive test suite (37 tests, ~75% coverage)
- Fixed bash safety flag consistency in cli/spawn.sh
Deferred 3 low-priority tasks (<15 score) as diminishing returns.
CLI is now production-ready with proper docs, tests, and error handling.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Changed set -uo pipefail to set -eo pipefail to align with commit #27
which removed nounset from all other scripts due to incompatibility
with optional env var checks (SPRITE_NAME, OPENROUTER_API_KEY, etc.).
This file was missed in the original nounset removal sweep.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Added comprehensive test suite for cli/ TypeScript code:
- 37 tests covering manifest.ts, commands.ts, and integration scenarios
- Tests for manifest loading, caching, network fallback, and validation
- Tests for all CLI commands (list, agents, clouds, run, help, etc.)
- Integration tests for end-to-end workflows
- ~900 lines of test code covering ~635 lines of source
Test infrastructure:
- Added vitest as test runner for fast execution
- Created isolated test environment with mocked cache directories
- Mocked network calls to avoid external dependencies
- Test coverage for critical paths: caching, offline mode, error handling
All tests passing with proper isolation and cleanup.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Replace empty catch blocks with proper error logging
- Add input validation for agent and cloud names in cmdRun and cmdAgentInfo
- Add detailed error messages for network failures and manifest validation
- Improve error context in execScript, cmdImprove, and cmdUpdate
- All errors now log helpful context instead of failing silently
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The autonomous refactoring reverted all our macOS fixes in shared/common.sh:
1. nc_listen: removed spurious -p flag check that misfires on macOS BSD nc
(BSD nc's -p means source port, not listen port — wrong syntax)
2. start_oauth_server: replaced echo -e (broken on macOS bash 3.x) with
printf-based write_oauth_response_file called before the subshell.
Removed local vars from subshell (not function scope).
3. ((elapsed++)) / ((attempt++)) → $((var + 1)) to avoid set -e killing
the script when the value is 0 (evaluates falsy).
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Protects against 'unbound variable' errors even if set -u is
re-enabled or inherited. Every [[ -n "$UPPER_VAR" ]] pattern now
uses [[ -n "${UPPER_VAR:-}" ]] to safely default to empty.
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The autonomous refactoring added `set -euo pipefail` but the scripts
check optional env vars with `[[ -n "$VAR" ]]` which is a fatal error
under nounset when the var isn't set (e.g. SPRITE_NAME, OPENROUTER_API_KEY).
Fix: downgrade to `set -eo pipefail` across all 42 affected files.
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When scripts run via `bash <(curl ...)`, BASH_SOURCE resolves to
/dev/fd/N, making the relative path `../../shared/common.sh` fail.
Fix: add remote fallback — try local file first, fall back to
fetching shared/common.sh from GitHub via eval+curl.
Applied to all 5 refactored lib/common.sh files (sprite, hetzner,
digitalocean, vultr, linode).
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Three issues broke the OAuth callback server on macOS:
1. echo -e doesn't work in bash 3.x — \r\n appears as literal text
in the HTTP response, browser gets malformed headers.
Fix: pre-write response with printf to a file before the subshell.
2. local variables inside ( ... ) & subshell — undefined behavior in
bash 3.x since subshells aren't function scope.
Fix: use plain variables in subshells.
3. ((elapsed++)) when elapsed=0 evaluates to falsy — set -e kills
the script on the first iteration of the timeout loop.
Fix: use elapsed=$((elapsed + 1)) instead.
Also simplified nc_listen detection to only check for BusyBox
(the -p flag check could misfire on macOS nc).
Applied to all 10 lib/common.sh files.
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
macOS ships bash 3.x which doesn't support nested process substitution.
When scripts are run via `bash <(curl ...)`, the inner `source <(curl ...)`
for loading common.sh fails silently, causing "command not found" errors.
Fix: replace `source <(curl -fsSL URL)` with `eval "$(curl -fsSL URL)"`
across all 100 agent scripts. eval+curl works on bash 3.x and newer.
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rewrites improve.sh to use the experimental Agent Teams feature:
- Lead coordinates in delegate mode (never touches code)
- Teammates work in parallel: Gap Fillers, Agent Scouts, Cloud Scouts
- Shared task list for self-claiming work
- Plan approval required for cloud provider work (lib/common.sh)
CLAUDE.md updated with team role definitions and coordination rules.
.claude/settings.json enables CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS.
Usage:
./improve.sh # one team cycle
./improve.sh --loop # continuous team cycles
./improve.sh --single # old single-agent mode (fallback)
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Cline is an open-source AI coding agent for the terminal.
Works with OpenRouter via OPENAI_BASE_URL override.
- Implemented on all 7 clouds
- Matrix now 10 agents x 7 clouds = 70/70 implemented
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
AWS's AI coding assistant, works with OpenRouter via OPENAI_BASE_URL override.
Installed via official installer script, launched with `q chat`.
- Implemented on all 7 clouds
- Matrix now 9 agents x 7 clouds = 63/63 implemented
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Google's open-source coding agent, works with OpenRouter via
OPENAI_BASE_URL override and GEMINI_API_KEY env var.
- Implemented on all 6 clouds: sprite, hetzner, digitalocean, vultr, linode, aws-lightsail
- Matrix now 8 agents x 6 clouds = 48/48 implemented
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Open Interpreter provides a natural language interface for computer control.
Works with OpenRouter via OPENAI_BASE_URL=https://openrouter.ai/api/v1.
- Implemented on all 5 clouds: sprite, hetzner, digitalocean, vultr, linode
- Matrix now 7 agents x 5 clouds = 35/35 implemented
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Linode instances via REST API v4, with cloud-init via metadata.user_data.
- linode/lib/common.sh: API wrapper, token management, instance lifecycle
- All 6 agents: claude, openclaw, nanoclaw, aider, goose, codex
Matrix now 6 agents x 5 clouds = 30/30 implemented.
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Goose is Block's open-source model-agnostic AI coding agent.
Supports OpenRouter via GOOSE_PROVIDER=openrouter env var.
- sprite/goose.sh, hetzner/goose.sh, digitalocean/goose.sh
- Matrix now 5 agents x 3 clouds = 15/15 implemented
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Aider is the most popular open-source AI pair programming CLI.
Natively supports OpenRouter via OPENROUTER_API_KEY env var
and --model openrouter/... flag.
- sprite/aider.sh, hetzner/aider.sh, digitalocean/aider.sh
- Matrix now 4 agents x 3 clouds = 12/12 implemented
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New cloud provider with full agent coverage:
- digitalocean/lib/common.sh: DO API wrapper, token management, droplet lifecycle
- digitalocean/claude.sh, openclaw.sh, nanoclaw.sh: all 3 agents
Matrix is now 3 agents x 3 clouds = 9/9 implemented.
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Fills the remaining 2 gaps in the agents x clouds matrix:
- hetzner/openclaw.sh: provisions Hetzner server with OpenClaw gateway + TUI
- hetzner/nanoclaw.sh: provisions Hetzner server with NanoClaw WhatsApp agent
Matrix is now 100% complete (3 agents x 2 clouds = 6/6 implemented).
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- manifest.json: tracks agents x clouds matrix with metadata
- CLAUDE.md: instructions for Claude Code to fill gaps and discover new agents/clouds
- improve.sh: loop script that launches Claude Code to expand the matrix
Current matrix: 3 agents (claude, openclaw, nanoclaw) x 2 clouds (sprite, hetzner)
with 2 gaps remaining (hetzner/openclaw, hetzner/nanoclaw).
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Parallel to the existing sprite/ directory, adds hetzner/ scripts that
provision Hetzner Cloud servers with Claude Code + OpenRouter using
curl-based API calls (no hcloud CLI dependency).
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add styled success page with CSS-animated checkmark, fade-in messaging,
and auto-close after 3 seconds with fallback text if browser blocks it.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add nc_listen helper that detects busybox nc and uses -p flag accordingly
- Add termux-open-url support to open_browser
- Deduplicate inline browser opener in try_oauth_flow to use open_browser
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add nc_listen helper that detects busybox nc and uses -p flag accordingly
- Add termux-open-url support to open_browser
- Deduplicate inline browser opener in try_oauth_flow to use open_browser
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Add NanoClaw spawn script
NanoClaw is a lightweight WhatsApp-based Claude AI assistant that runs
agents in isolated containers. This script sets up a sprite with
nanoclaw pre-configured: clones the repo, installs dependencies,
configures the API key, and launches in dev mode for WhatsApp QR auth.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* Fix verify_sprite_connectivity exiting script early after single failed check
Retry connectivity up to 6 attempts (30s) instead of trying once and
silently continuing, which caused the next sprite exec to fail under set -e.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Add test harness for spawn scripts
Mocks the sprite CLI and runs each script end-to-end verifying:
- common.sh sources correctly and all functions resolve
- Log functions write to stderr (not stdout)
- Env var flow (SPRITE_NAME, OPENROUTER_API_KEY)
- Sprite commands called in correct order
- Temp files created and cleaned up
- Each script reaches its final interactive launch
Usage: bash test/run.sh
42 tests, all passing.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Retry connectivity up to 6 attempts (30s) instead of trying once and
silently continuing, which caused the next sprite exec to fail under set -e.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- safe_read(): Test /dev/tty is functional before using it (exists
but fails in containers/VMs)
- Log functions: Write to stderr so they don't pollute stdout in
command substitutions like $(get_sprite_name)
- ensure_sprite_exists(): Fix grep regex (use -E for ERE)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
BASH_SOURCE[0] is /proc/self/fd/N with process substitution, not
"-" or "bash". Instead of guessing execution context, just check
if the local lib/common.sh file actually exists.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
## Problem
The command `curl URL | bash` isn't interactive because curl's output
consumes bash's stdin, preventing user prompts from working.
## Solution
Use bash process substitution instead: `bash <(curl URL)`
This keeps stdin available for the script while downloading from curl.
## Changes
- Added INTERACTIVE_CURL.md - Complete guide to interactive execution
- Added NON_INTERACTIVE_MODE.md - Guide to automation/CI usage
- Updated README.md to recommend `bash <(curl ...)` format
- Documented OpenRouter URL alias pattern
## Recommended Usage
Interactive (best UX):
bash <(curl -fsSL https://openrouter.ai/lab/spawn/sprite/claude.sh)
Non-interactive (CI/CD):
SPRITE_NAME=dev-mk1 curl URL | bash
## Why Process Substitution?
- Stdin available for prompts ✅
- Works like normal bash script ✅
- No /dev/tty workarounds needed ✅
- Better user experience ✅
Both methods are supported for maximum compatibility.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The scripts were failing when run via curl | bash because they tried
to read from /dev/tty which doesn't exist in piped contexts.
## Changes
- Added safe_read() helper function that gracefully handles TTY absence
- Updated get_sprite_name() to support SPRITE_NAME env variable
- Updated all read commands to use safe_read()
- Added clear error messages for non-interactive usage
- Updated README with non-interactive mode documentation
## Usage
Interactive:
curl URL | bash
Non-interactive:
SPRITE_NAME=dev-mk1 curl URL | bash
SPRITE_NAME=dev-mk1 OPENROUTER_API_KEY=sk-xxx curl URL | bash
## Fixes
- /dev/tty: No such device or address error
- Scripts now work in CI/CD and automated contexts
- OAuth fallback still works via OPENROUTER_API_KEY env var
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
