Enhance UX across CLI and cloud providers with actionable error messages:
1. Modal sandbox creation failures now provide:
- Detailed error output from Python SDK
- Common causes (auth expired, quota issues, network)
- Step-by-step troubleshooting (re-auth, check quota, status page)
2. Modal CLI installation failures now explain:
- Missing pip/pip3 (with installation commands)
- Permission issues (suggest --user flag)
- Manual installation steps
3. Sprite connectivity failures now include:
- Commands to check sprite status and logs
- Steps to recreate sprite
- Support contact information
4. Sprite CLI installation now:
- Catches installation failures with helpful error messages
- Verifies installation succeeded before proceeding
- Provides manual installation instructions
5. CLI script download failures improved:
- Distinguish between 404 (doesn't exist) and other errors
- Provide specific next steps for each scenario
- Suggest checking matrix for implementation status
All error messages follow the pattern:
- What went wrong
- Why it might have happened (common causes)
- What to do next (actionable steps)
Agent: ux-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
- Modified ensure_sprite_installed() to check if sprite is already installed
- When sprite is found, log version and skip installation
- Prevents unnecessary reinstalls when sprite CLI is already present
Fixes#63
Agent: community-coordinator
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Root causes:
- `clear` command fails with exit 1 when TERM is not set (test env has
no terminal), crashing the script due to set -e. Guard with || true.
- Test patterns for Claude settings/state uploads used old temp file
naming convention (/tmp/claude_settings, /tmp/claude_global) that no
longer matches the paths generated by upload_config_file +
upload_file_sprite (/tmp/*settings.json, /tmp/*.claude.json).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The upstream OpenCode installer pipes `curl -# -L | tar xz` which fails
in container exec environments (Sprite, E2B, Modal, Daytona) where the
binary stream gets corrupted through the exec layer, producing
"gzip: stdin: not in gzip format" errors.
Added opencode_install_cmd() to shared/common.sh that downloads the
binary to a file first, then extracts it. Updated all 17 opencode.sh
scripts to use this robust method instead of the upstream installer.
The previous fix (#44) only addressed Sprite with a hardcoded
linux-x86_64 architecture. This fix detects OS/arch dynamically and
applies to all cloud providers.
Fixes#42
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The upstream install script (curl|bash) fails inside Sprite sandboxes
because the nested curl|tar pipeline receives non-gzip content. Replace
with direct binary download from GitHub releases which is more reliable
in sandboxed/piped execution contexts.
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Plandex is an open source AI coding agent for complex tasks (15k+ GitHub
stars, multiple HN frontpage posts). It natively supports OpenRouter via
OPENROUTER_API_KEY environment variable and installs via a single curl
command. Go-based CLI with sandbox and version control for AI changes.
Implemented on all 14 clouds: sprite, hetzner, digitalocean, vultr,
linode, lambda, aws-lightsail, gcp, e2b, modal, fly, civo, scaleway,
daytona.
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: extract shared test helpers and utilities
Created centralized test-helpers.ts module to eliminate duplication across test files:
**Extracted Helpers:**
- createMockManifest() - Reusable mock manifest data
- createEmptyManifest() - Empty manifest for edge cases
- createConsoleMocks() - Console spy setup
- createProcessExitMock() - Process exit mock
- restoreMocks() - Mock cleanup utility
- mockSuccessfulFetch() - Simplified successful fetch mock
- mockFailedFetch() - Simplified failed fetch mock
- mockFetchWithStatus() - Fetch mock with custom status
- setupTestEnvironment() - Test directory and env setup
- teardownTestEnvironment() - Cleanup utility
**Deduplication Impact:**
- commands.test.ts: Removed 50+ lines of duplicate mock setup
- manifest.test.ts: Removed 80+ lines of duplicate manifest data and setup code
- integration.test.ts: Removed 40+ lines of duplicate setup/teardown
**Benefits:**
- Single source of truth for test fixtures
- Consistent mock patterns across all tests
- Easier maintenance - changes to test setup in one place
- Improved test readability
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* refactor: Add non-interactive mode for agent execution
Implements --prompt and --prompt-file flags to enable non-interactive
agent execution. This allows users to:
- Execute agents with a prompt and exit automatically
- Use spawn in CI/CD pipelines and automation scripts
- Pass prompts via command line or file
Changes:
- TypeScript CLI: Parse --prompt/-p and --prompt-file flags
- Security: Add validatePrompt() to prevent command injection
- Commands: Pass prompt via SPAWN_PROMPT env var to bash scripts
- Bash scripts: Detect SPAWN_PROMPT and fork interactive/non-interactive
- Help text: Document new flags with examples
Implementation:
- claude.sh: Use 'claude -p' for non-interactive execution
- aider.sh: Use 'aider -m' for non-interactive execution
- shared/common.sh: Add execute_agent_non_interactive() helper
Security:
- Validates prompts for command injection patterns
- Length limit: 10KB max
- Blocks $(), backticks, piping to bash/sh
- Uses printf %q for proper shell escaping
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: Add testing guide for non-interactive mode
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>
The refactor in f9dd9a7 hardcoded /root/ as the upload destination for
Claude Code and OpenClaw config files, breaking all non-root providers
(Lambda, AWS Lightsail, GCP, Sprite, E2B, Modal, Fly). Upload to /tmp/
first then mv to ~/ via run_callback so the remote shell expands ~ to
the correct home directory.
Also add OPENROUTER_API_KEY env var check to sprite scripts (claude,
openclaw, nanoclaw) so the OAuth flow is skipped when the key is already
set, and fix echo -e to printf for macOS bash 3.x compat.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
OpenCode is a Go-based AI coding agent with a terminal TUI (Bubble Tea).
It natively supports OpenRouter as a built-in provider via OPENROUTER_API_KEY.
- Add opencode agent to manifest.json with env config
- Implement sprite/opencode.sh for Sprite cloud
- Implement hetzner/opencode.sh for Hetzner Cloud
- Add matrix entries (implemented: sprite, hetzner; missing: rest)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Completed ENV_TEMP pattern extraction across remaining providers:
1. Modal: gptme.sh (1 script) - uses inject_env_vars_local
2. GCP: all 10 agent scripts - uses inject_env_vars_ssh
3. Fly.io: all 11 agent scripts - uses new inject_env_vars_fly
- Added inject_env_vars_fly() to fly/lib/common.sh
- Handles both .bashrc and .zshrc (Fly-specific requirement)
4. Sprite: amazonq, cline, gemini (3 scripts) - uses inject_env_vars_sprite
Total scripts converted in this commit: 25
Total scripts converted in Round 25 Task #1: 78 scripts
Each conversion replaces 11-15 lines of temp file management with a single
function call that handles creation, permissions, content generation, upload,
sourcing, and cleanup.
The only remaining ENV_TEMP patterns are DOTENV_TEMP in nanoclaw scripts,
which are agent-specific .env files and should remain as-is.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* feat: add gptme agent to spawn matrix
Add gptme (https://github.com/gptme/gptme) - a personal AI agent in the
terminal with tools for code editing, terminal commands, web browsing,
and more. Natively supports OpenRouter via OPENROUTER_API_KEY.
- Add gptme agent entry to manifest.json with OpenRouter env vars
- Implement sprite/gptme.sh deployment script
- Implement hetzner/gptme.sh deployment script
- Add "missing" matrix entries for remaining 8 clouds
- Update README.md with usage instructions for Sprite and Hetzner
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add Fly.io cloud provider with claude and aider agents
Add Fly.io as a new cloud provider using the Machines REST API for
provisioning and flyctl CLI for SSH access. Docker-based machines
with pay-per-second pricing.
- Create fly/lib/common.sh with Fly.io Machines API integration
- Implement fly/claude.sh for Claude Code deployment
- Implement fly/aider.sh for Aider deployment
- Update README.md with Fly.io usage instructions and env vars
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add gemini, amazonq, cline, gptme to Fly.io
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add openclaw, nanoclaw, goose, codex, interpreter to Fly.io
Implements 5 new agent scripts for the Fly.io cloud provider:
- fly/openclaw.sh: OpenClaw with gateway + TUI, model selection, config
- fly/nanoclaw.sh: NanoClaw WhatsApp agent with .env configuration
- fly/goose.sh: Block's Goose agent with OpenRouter provider
- fly/codex.sh: OpenAI Codex CLI with OpenRouter base URL override
- fly/interpreter.sh: Open Interpreter with OpenRouter base URL override
All scripts follow the Fly.io pattern (flyctl-based, no IP args for
run_server/interactive_session) and use upload_file for env injection.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add gptme agent to 8 remaining clouds
Implement gptme agent scripts for digitalocean, vultr, linode, lambda,
aws-lightsail, gcp, e2b, and modal. Each script follows the exact
pattern of that cloud's existing aider.sh, adapted for gptme's install
and launch commands. Updates manifest.json matrix entries from "missing"
to "implemented".
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Add guardrails from insights: CLAUDE.md rules, hooks, pre-commit
Based on usage insights analysis:
CLAUDE.md:
- Shell script rules: curl|bash compat, macOS bash 3.x compat
- Autonomous loop rules: test after each iteration, never revert fixes
- Git workflow rules: always use feature branches
.claude/settings.json:
- PostToolUse hook validates .sh files on every Write/Edit:
syntax check, no relative source, no echo -e, no set -u
.githooks/pre-commit:
- Blocks commits with: syntax errors, relative sources, echo -e,
set -euo, references to deleted functions
- Install: git config core.hooksPath .githooks
README.md:
- Added developer setup section with hook installation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Removed manual rm calls for temp files in sprite/lib/common.sh since
traps now handle cleanup automatically. Combined traps for both temp
files in configure_shell_sprite() function.
Impact: Prevents temp file leaks on crashes/interrupts
Risk: Low - only removing redundant cleanup calls
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- 5 nanoclaw scripts only create DOTENV_TEMP but trap referenced both
- Causes trap to fail silently when trying to rm undefined variable
- Fix: Change trap from both temps to just DOTENV_TEMP
- Affected: digitalocean, hetzner, linode, sprite, vultr
Root cause: Automated trap addition in Round 19 incorrectly detected
these files as using both temp variables (DOTENV_TEMP contains substring
ENV_TEMP which caused false positive in grep check)
- Add trap 'rm -f "${ENV_TEMP}"' EXIT after mktemp creation
- Scripts with DOTENV_TEMP get combined trap for both files
- Remove manual rm calls that are now redundant
- Prevents temp file leaks on early script exit (errors, signals)
- Affects 67 agent scripts across all providers
Impact: Prevents /tmp pollution in production deployments
Score: 90 (Impact: 9, Confidence: 10, Risk: 1)
Quote INSTANCE_STATUS_POLL_DELAY, SSH_RETRY_DELAY, and
SPRITE_CONNECTIVITY_POLL_DELAY to prevent potential word splitting
issues with unusual values.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Separated local variable declaration from command substitution assignment
in upload_file_sprite function to avoid masking return values.
Co-Authored-By: Claude Sonnet 4.5 <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>
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>
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>
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: 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>
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>
- OAuth authentication flow with OpenRouter to mint API keys
- Automatic sprite creation and environment configuration
- Claude Code setup with bypassed onboarding and dark theme
- OpenClaw setup with gateway and TUI launch
- Shell environment setup (bun PATH, zsh switch)
