"spawn connect" is not a valid top-level CLI command — users following
this guidance after SSH reconnect failure would see "Unknown agent or
cloud: connect". Replace with "spawn last" which correctly reconnects
to the most recent spawn.
Agent: ux-engineer
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Two bugs from the #3305 rollout:
1. Test pollution: orchestrate.test.ts imports runOrchestration directly
and never calls initTelemetry, but _enabled defaulted to true in the
module so captureEvent happily fired real events at PostHog tagged
agent=testagent. The onboarding funnel filled up with CI fixture data.
2. Funnel started too late: funnel_* events fired inside runOrchestration,
which is only called AFTER the interactive picker completes. Users who
bail at the agent/cloud/setup-options/name prompts were invisible —
yet that's exactly where real drop-off happens.
Fix 1 — telemetry.ts:
- Default _enabled = false. Nothing fires until initTelemetry is
explicitly called. Production (index.ts) calls it; tests that need
telemetry (telemetry.test.ts) call it with BUN_ENV/NODE_ENV cleared.
- Belt-and-suspenders: initTelemetry now short-circuits when
BUN_ENV === "test" || NODE_ENV === "test", so even if future code
calls it from a test context, events stay local.
Fix 2 — picker instrumentation:
New events fired before runOrchestration in every entry path:
spawn_launched { mode: interactive | agent_interactive | direct | headless }
menu_shown / menu_selected / menu_cancelled (only when user has prior spawns)
agent_picker_shown
agent_selected { agent } — also sets telemetry context
cloud_picker_shown
cloud_selected { cloud } — also sets telemetry context
preflight_passed
setup_options_shown
setup_options_selected { step_count }
name_prompt_shown
name_entered
picker_completed
Wired into:
commands/interactive.ts cmdInteractive + cmdAgentInteractive
commands/run.ts cmdRun (direct `spawn <agent> <cloud>`)
cmdRunHeadless (only spawn_launched)
runOrchestration's existing funnel_* events continue to fire unchanged.
The final funnel in PostHog:
spawn_launched → agent_selected → cloud_selected → preflight_passed
→ setup_options_selected → name_entered → picker_completed
→ funnel_started → funnel_cloud_authed → funnel_credentials_ready
→ funnel_vm_ready → funnel_install_completed → funnel_configure_completed
→ funnel_prelaunch_completed → funnel_handoff
Tests:
- telemetry.test.ts: 2 new env-guard tests (BUN_ENV, NODE_ENV), plus
updated beforeEach to clear both env vars so existing tests still
exercise initTelemetry.
- Full suite: 2131/2131 pass, biome 0 errors.
Bumps 1.0.12 -> 1.0.13 (patch — auto-propagates under #3296 policy).
* feat(telemetry): funnel + lifecycle events for onboarding drop-off
Adds low-volume, high-signal product events on top of the existing
errors/warnings telemetry (shared/telemetry.ts). Answers "where do users
bail before reaching a running agent" at the fleet level.
Funnel events (in orchestrate.ts, both fast and sequential paths):
funnel_started pipeline begins
funnel_cloud_authed cloud.authenticate() ok
funnel_credentials_ready OR key + preProvision resolved
funnel_vm_ready VM booted and SSH-reachable
funnel_install_completed agent install succeeded (tarball or live)
funnel_configure_completed agent.configure() ran
funnel_prelaunch_completed gateway / dashboard / preLaunch hooks done
funnel_handoff about to launch TUI (final step)
Every event carries elapsed_ms since funnel_started, plus agent and cloud
via telemetry context. Per-step counts reveal the drop-off funnel in
PostHog without touching any PII.
Lifecycle events (new shared/lifecycle-telemetry.ts):
spawn_connected { spawn_id, agent, cloud, connect_count, date }
fired from list.ts when the user reconnects via the interactive picker.
Increments connection.metadata.connect_count and writes last_connected_at
so subsequent events and the eventual spawn_deleted have the total.
spawn_deleted { spawn_id, agent, cloud, lifetime_hours, connect_count, date }
fired from delete.ts (both interactive confirmAndDelete and headless
cmdDelete loop) after a successful cloud destroy. lifetime_hours is
computed from SpawnRecord.timestamp to now. Clamped at 0 for corrupt
clocks. connect_count is read from metadata.
New captureEvent(name, properties) helper in telemetry.ts:
- Respects SPAWN_TELEMETRY=0 opt-out (no new flag)
- Runs every string property through the existing scrubber (API keys,
GitHub tokens, bearer, emails, IPs, base64 blobs, home paths)
- Non-string values pass through untouched
Tests: 20 new (15 lifecycle-telemetry + 2 captureEvent + 3 assertion
additions to disabled-telemetry). Full suite: 2129/2129 pass.
Bumps 1.0.10 -> 1.0.11. Patch bump — auto-propagates under #3296 policy.
* fix(test): replace mock.module with spyOn in lifecycle-telemetry tests
mock.module contaminates the global module registry when running under
--coverage, causing telemetry.test.ts and history-cov.test.ts to receive
mocked implementations instead of the real modules. Switch to spyOn with
mockRestore in afterEach so the real modules are preserved across files.
Agent: pr-maintainer
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: L <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(security): use temp file for GitHub token to avoid process listing exposure
Fixes#3300
Agent: security-auditor
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix(security): pass GitHub token via heredoc instead of local temp file
The previous fix wrote the token to a temp file on the LOCAL host, but
the command string was executed on the REMOTE server via runner.runServer(),
so `cat` would fail with 'No such file or directory'. Switch to a heredoc
which is parsed by the remote shell and never appears in /proc/*/cmdline.
Agent: pr-maintainer
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix(security): upload token to remote via SCP instead of heredoc
The previous heredoc approach (`cat <<'EOF'`) doesn't work because all
cloud runners wrap commands in `bash -c ${shellQuote(cmd)}`, and heredocs
are not valid inside single-quoted bash -c strings.
Use runner.uploadFile() (SCP) to place the token on the remote server as
a temp file (mode 0600), then cat+rm it in the remote command. This is
the same proven pattern used by uploadConfigFile(). The local temp file
is always cleaned up after upload, and the remote temp file is cleaned up
both on success (inline rm) and on failure (best-effort rm).
Agent: security-auditor
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* feat(cli): hermes web dashboard tunnel support
Hermes Agent v0.9.0 ships a local web dashboard (hermes dashboard, default
127.0.0.1:9119) for config / session / skill / gateway management. This wires
Hermes into spawn's existing SSH-tunnel infrastructure so `spawn run hermes`
auto-exposes the dashboard to the user's local browser.
- agent-setup.ts: new startHermesDashboard() helper — session-scoped
background launch via setsid/nohup with a port-ready wait loop. No systemd
(unlike OpenClaw's gateway) because the dashboard only needs to live for
the duration of the spawn session. Falls back gracefully if hermes isn't
in PATH or the dashboard fails to come up.
- Wire preLaunch, preLaunchMsg, and tunnel { remotePort: 9119 } into the
hermes AgentConfig. Mirrors the OpenClaw tunnel pattern at
orchestrate.ts:628 — startSshTunnel + openBrowser happen automatically.
- manifest.json: update hermes notes to mention the dashboard.
- hermes-dashboard.test.ts: 7 new unit tests verifying the deploy script
calls `hermes dashboard --port 9119 --host 127.0.0.1 --no-open`, checks
all three port-probe fallbacks (ss / /dev/tcp / nc), uses setsid+nohup,
waits for the port, and does NOT install a systemd unit.
- Bump cli version 1.0.6 -> 1.0.7.
Closes#3293
* chore: bump cli to 1.0.8 to leave 1.0.7 for #3296
---------
Co-authored-by: L <6723574+louisgv@users.noreply.github.com>
Add validateRemotePath() and shellQuote() to instruction_path handling
in skills.ts, matching the pattern used by uploadConfigFile(). Previously,
remotePath from manifest.json was interpolated directly into shell commands
without validation, allowing path traversal and shell injection via a
malicious instruction_path field.
Closes#3275
Agent: security-auditor
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(security): validate env var keys in skill injection (orchestrate.ts)
Fixes#3269
Agent: security-auditor
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(security): add base64 validation for defense-in-depth in skill env injection
Add validation of base64-encoded values to match the existing pattern
in injectEnvVarsToRunner (line 518), providing defense-in-depth even
though base64 output is highly unlikely to contain invalid characters.
Agent: security-auditor
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(security): base64-encode entire skill env payload before shell interpolation
Matches the injectEnvVarsToRunner pattern: base64-encode the full payload
and decode on the remote side, eliminating any shell interpolation of
individual env lines. Addresses review feedback on double-evaluation risk.
Agent: pr-maintainer
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
CLI plumbing for the skills feature. The skills catalog in manifest.json
is populated by the discovery scout (#3252), not manually curated.
Flow:
1. User runs `spawn claude hetzner --beta skills`
2. Skills picker shows available skills for that agent (from manifest.json)
3. User selects skills, enters required env vars (GITHUB_TOKEN, etc.)
4. During provisioning, skills are installed on the VM:
- MCP servers → merged into agent's config (settings.json, mcp.json)
- Instruction skills → SKILL.md written to agent's skills directory
- Prerequisites → apt packages, Chrome, etc. installed first
5. Env vars appended to .spawnrc for MCP server runtime access
Headless: SPAWN_SELECTED_SKILLS=github-mcp,context7 spawn claude hetzner
Supports: Claude Code, Cursor (native MCP config), all other agents
(generic mcp.json fallback).
Signed-off-by: Ahmed Abushagur <ahmed@abushagur.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Tarballs are built with /root/ paths. On non-root VMs (Sprite), the old
approach extracted to /root/ with sudo, then mirrored files to $HOME/.
This failed on Sprite which doesn't have sudo.
New approach: use tar --transform to remap /root/ → $HOME/ during
extraction. No sudo needed, no mirror step. Falls back to sudo extract
for clouds with passwordless sudo (AWS, GCP).
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Fixes#3250
The unbounded quantifier {40,} with word boundary \b caused exponential
backtracking on long non-matching strings. Adding {40,100} upper bound
and removing \b prevents catastrophic backtracking.
Agent: security-auditor
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
PostHog's /batch/ endpoint requires distinct_id inside each event's
properties object, not at the event level. Events were silently dropped.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
pullChildHistory was awaited after the interactive session, blocking
process.exit() for up to 5+ minutes while it SSHed back into the VM.
This is a convenience feature for `spawn tree` — it should never make
the user wait.
Changed to fire-and-forget: process.exit() fires immediately,
killing any in-flight SSH calls. Headless mode still awaits it
since there's no user waiting.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sends CLI errors, warnings, and crashes to PostHog for observability.
Strictly error/warning events — no command tracking or session events.
All messages are scrubbed before sending:
- API keys (sk-or-v1-*, sk-ant-*, key-*)
- GitHub tokens (ghp_*, github_pat_*)
- Bearer tokens
- Email addresses
- IP addresses
- Long tokens (60+ char alphanumeric)
- Base64 blobs (40+ chars)
- Home directory paths (/Users/name → ~/[USER])
Default on. Disable with SPAWN_TELEMETRY=0.
Fire-and-forget with 5s timeout — never blocks the CLI.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
`openclaw onboard --non-interactive` now defaults to arcee/trinity-large-thinking
instead of using the OpenRouter provider. Always run `openclaw config set
agents.defaults.model.primary` after onboard to ensure openrouter/auto is set.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds two behavioral crypto miner checks to the security scan:
- Flag non-agent processes using >80% CPU (catches renamed miners)
- Detect outbound connections to known mining pool ports (3333, 4444, etc.)
Adds a Security column to `spawn status` that shows clean/alerts/—
for each running server, with detailed alert summary after the table.
JSON output includes security and security_alerts fields.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Installs a cron job (every 6h) that checks for SSH key anomalies,
failed login attempts (brute-force), suspicious software (attack tools,
crypto miners), unexpected processes, rogue cron entries, and unusual
listening ports. Findings are written to /var/log/spawn-security-alerts.log
and displayed as warnings when users reconnect via `spawn connect`.
Signed-off-by: Ahmed Abushagur <ahmed@abushagur.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: complete VM recovery rewrite for spawn fix command
Fixes#3173
Rewrites spawn fix to use CloudRunner interface for full VM recovery
instead of a flat bash script piped over SSH. Now runs the same
install(), configure(), preLaunch() functions as initial provisioning.
- Added generic SSH CloudRunner (ssh-runner.ts) reusable by other commands
- Exported injectEnvVarsToRunner() from orchestrate.ts for shared use
- Fixed command injection vulnerability via validateIdentifier(binaryName)
- Updated dependency injection: runScript → makeRunner (CloudRunner)
- Updated tests to use CloudRunner-based DI pattern
Agent: code-health
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(ssh-runner): add coverage for validation paths
Tests cover the early-exit branches in makeSshRunner methods
(runServer invalid command, uploadFile/downloadFile path traversal)
that throw before any subprocess is spawned.
Agent: team-lead
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(openclaw): fix telegram bot not responding to messages
The switch to `openclaw config set` calls in #2655 created malformed
nested config structures — the bot token and dmPolicy weren't read
properly by openclaw, so the bot never started polling for messages.
The `groups` block was also dropped entirely.
Fix: write the complete telegram channel object atomically via a bun
script that reads the existing config, deep-merges the full telegram
block, and writes it back — matching the original atomic JSON approach.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(security): pass telegram config via env var instead of JS interpolation
Prevents JavaScript code injection via attacker-controlled bot token by
passing the telegramConfig JSON through a shell-quoted environment variable
(TELEGRAM_CONFIG) and parsing it with JSON.parse(process.env.TELEGRAM_CONFIG)
inside the bun script, instead of interpolating it directly into JS source.
Agent: security-auditor
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* test: add test for atomic telegram config write
Verifies that openclaw telegram config uses a bun merge script (atomic
write) instead of individual `openclaw config set` calls, and that the
full config object (botToken, dmPolicy, groupPolicy, groups) is included.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Signed-off-by: Ahmed Abushagur <ahmed@abushagur.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
The SKILL_BODY and HERMES_SNIPPET in spawn-skill.ts listed available
agents and clouds but were not updated when pi (#3156) and daytona
(#3168) were added. Agents spawned via the skill system could not
delegate work to Pi or provision on Daytona.
Agent: code-health
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
cursor was missing from the AGENT_SKILLS map in spawn-skill.ts, causing
spawn skill injection to silently skip cursor VMs when --beta recursive
is active. pi was present in AGENT_SKILLS but missing from all test
arrays in spawn-skill.test.ts.
Agent: code-health
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Poll `openclaw status --json` after onboarding until bootstrapPending
is false (up to 60s). Prevents the Control UI from opening into a
broken state where chat fails with "No session found" because the
initial session hasn't been created yet.
Fixes#3167
Agent: ux-engineer
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Cursor CLI validates CURSOR_API_KEY before connecting to the configured
endpoint. The dummy value "spawn-proxy" fails validation immediately,
causing an infinite restart loop. Use the actual OPENROUTER_API_KEY as
CURSOR_API_KEY so it passes Cursor's key format check.
Fixes#3166
Agent: ux-engineer
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
The same 12-line saveSpawnRecord block was duplicated 3 times in
runOrchestration() (fast-mode boot, fast-mode retry, sequential path).
A bug fixed in one copy could easily be missed in another. Extracted
a shared recordSpawn() helper that all 3 sites now call.
Agent: complexity-hunter
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Add pre-encoding validation to reject ${} interpolation patterns in
script template strings before they are base64-encoded and injected
into systemd services running with root privileges on remote VMs.
Defense-in-depth against future regressions where template variable
interpolation before encoding could allow command injection.
Fixes#3130
Agent: security-auditor
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix(ci): remove stale paths from biome check step in lint.yml
biome.json restricts linting to packages/**/*.ts via its includes filter,
so passing .claude/scripts/ and .claude/skills/setup-spa/ to the biome
check command was a no-op — biome reported 0 files processed for those
paths and silently skipped them.
Remove the stale paths so the CI step accurately reflects what biome
actually checks.
* feat: add OpenRouter proxy for Cursor CLI agent (#3100)
Cursor CLI uses a proprietary ConnectRPC/protobuf protocol with BiDi
streaming over HTTP/2. It validates API keys against Cursor's own servers
and hardcodes api2.cursor.sh for agent streaming — making direct
OpenRouter integration impossible.
This adds a local translation proxy that intercepts Cursor's protocol
and routes LLM traffic through OpenRouter:
Architecture:
Cursor CLI → Caddy (HTTPS/H2, port 443) → split routing:
/agent.v1.AgentService/* → H2C Node.js (BiDi streaming → OpenRouter)
everything else → HTTP/1.1 Node.js (fake auth, models, config)
Key components:
- cursor-proxy.ts: proxy scripts + deployment functions
- Caddy reverse proxy for TLS + HTTP/2 termination
- /etc/hosts spoofing to intercept api2.cursor.sh
- Hand-rolled protobuf codec for AgentServerMessage format
- SSE stream translation (OpenRouter → ConnectRPC protobuf frames)
Proto schemas reverse-engineered from Cursor CLI binary v2026.03.25:
- AgentServerMessage.InteractionUpdate.TextDeltaUpdate.text
- agent.v1.ModelDetails (model_id, display_model_id, display_name)
- TurnEndedUpdate (input_tokens, output_tokens)
Tested end-to-end on Sprite VM: Cursor CLI printed proxy response with
EXIT=0.
Co-authored-by: Ahmed Abushagur <ahmed@abushagur.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(digitalocean): use canonical DIGITALOCEAN_ACCESS_TOKEN env var (#3099)
Replaces all references to DO_API_TOKEN with DIGITALOCEAN_ACCESS_TOKEN,
matching DigitalOcean's official CLI and API documentation. This includes
TypeScript source, tests, shell scripts, Packer config, CI workflows,
and documentation.
Supersedes #3068 (rebased onto current main).
Agent: pr-maintainer
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: remove --trust flag from Cursor CLI launch command (#3101)
Cursor CLI v2026.03.25 only allows --trust in headless/print mode.
Launching interactively with --trust causes immediate exit with error.
Co-authored-by: spawn-bot <spawn-bot@openrouter.ai>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Ahmed Abushagur <ahmed@abushagur.com>
* fix(cursor): set CURSOR_API_KEY to skip browser login (#3104)
Cursor CLI requires authentication before making API calls. Without
CURSOR_API_KEY set, it falls back to browser-based OAuth which fails
because the proxy spoofs api2.cursor.sh to localhost, breaking the
OAuth callback. Setting a dummy CURSOR_API_KEY makes Cursor use the
/auth/exchange_user_api_key endpoint instead, which the proxy already
handles with a fake JWT.
Co-authored-by: spawn-bot <spawn-bot@openrouter.ai>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: sync README with source of truth (#3097)
- update tagline: 8 agents/48 combos -> 9 agents/54 combos
- add Cursor CLI row to matrix table
manifest.json has 9 agents (cursor was added but README matrix
was not updated) and 54 implemented entries.
Co-authored-by: spawn-qa-bot <qa@openrouter.ai>
Co-authored-by: Ahmed Abushagur <ahmed@abushagur.com>
* fix(cursor): update proxy model list to current models (#3105)
Replace outdated models (Claude Sonnet 4, GPT-4o) with current ones:
- Claude Sonnet 4.6 (default), Claude Haiku 4.5
- GPT-4.1
- Gemini 2.5 Pro, Gemini 2.5 Flash
Co-authored-by: spawn-bot <spawn-bot@openrouter.ai>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(status): add agent alive probe via SSH (#3109)
`spawn status` now probes running servers by SSHing in and running
`{agent} --version` to verify the agent binary is installed and
executable. Results show in a new "Probe" column (live/down/—) and
as `agent_alive` in JSON output. Only "running" servers are probed;
gone/stopped/unknown servers are skipped.
The probe function is injectable via opts for testability.
Co-authored-by: spawn-bot <spawn-bot@openrouter.ai>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: add cursor to agent lists in spawn skill files (#3108)
cursor is a fully implemented agent across all 6 clouds but was missing
from the available agents list in spawn skill instructions injected onto
child VMs. This caused claude, codex, hermes, junie, kilocode, openclaw,
opencode, and zeroclaw to be unaware they could delegate work to cursor.
Signed-off-by: Ahmed Abushagur <ahmed@abushagur.com>
Co-authored-by: spawn-qa-bot <qa@openrouter.ai>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Ahmed Abushagur <ahmed@abushagur.com>
* fix(security): expand $HOME before path validation in downloadFile (#3080)
Fixes#3080
Prevents path traversal via other $VAR expansions by normalizing
$HOME to ~ before the strict path regex check, removing the need
to allow $ in the charset.
Applied to all 5 cloud providers:
- digitalocean: downloadFile
- aws: downloadFile
- sprite: downloadFileSprite
- gcp: uploadFile + downloadFile
- hetzner: downloadFile
Also bumps CLI version to 0.27.7.
Agent: security-auditor
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(manifest): correct cursor repo to cursor/cursor and update star counts (#3092)
The cursor agent's repo was set to anysphere/cursor (private, returns 404),
which caused the stars-update script to store the raw 404 error object as
github_stars instead of a number — breaking the manifest-type-contracts test.
Fix: update repo to the public cursor/cursor repo (32,526 stars as of 2026-03-29).
Also applies the daily star count updates for all other agents.
-- qa/e2e-tester
Co-authored-by: spawn-qa-bot <qa@openrouter.ai>
* fix(spawn-fix): load API keys via config file, not just process.env (#3095)
Previously buildFixScript() resolved env templates directly from
process.env, silently writing empty values when the user authenticated
via OAuth (key stored in ~/.config/spawn/openrouter.json). Now fixSpawn()
loads the saved key before building the script, matching orchestrate.ts.
Fixes#3094
Agent: code-health
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: sync README commands table with help.ts (--prompt, --prompt-file) (#3106)
Co-authored-by: spawn-qa-bot <qa@openrouter.ai>
* fix(e2e): reduce Hetzner batch parallelism from 3 to 2 (#3112)
Prevents server_limit_reached errors when pre-existing servers (e.g.
spawn-szil) consume quota during E2E batch 1.
Fixes#3111
Agent: test-engineer
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* refactor(e2e): normalize unused-arg comments in headless_env functions (#3113)
GCP, Sprite, and DigitalOcean had commented-out code `# local agent="$2"`
in their `_headless_env` functions. Hetzner already used the cleaner style
`# $2 = agent (unused but part of the interface)`. Normalize to match.
Co-authored-by: spawn-qa-bot <qa@openrouter.ai>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* test: Remove duplicate and theatrical tests (#3089)
* test: remove duplicate and theatrical tests
- update-check.test.ts: fix 3 tests using stale hardcoded version '0.2.3'
(older than current 0.29.1) to use `pkg.version` so 'should not update
when up to date' actually tests the current-version path correctly
- run-path-credential-display.test.ts: strengthen weak `toBeDefined()`
assertion on digitalocean hint to `toContain('Simple cloud hosting')`,
making it verify the actual fallback hint content
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test: replace theatrical no-assert tests with real assertions in recursive-spawn
Two tests in recursive-spawn.test.ts captured console.log output into a
logs array but never asserted against it. Both ended with a comment like
"should not throw" — meaning they only proved the function didn't crash,
not that it produced the right output.
- "shows empty message when no history": now spies on p.log.info and
asserts cmdTree() emits "No spawn history found."
- "shows flat message when no parent-child relationships": now asserts
cmdTree() emits "no parent-child relationships" via p.log.info.
expect() call count: 4831 to 4834 (+3 real assertions added).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test: consolidate redundant describe block in cmd-fix-cov.test.ts
The file had two separate describe blocks with identical beforeEach/afterEach
boilerplate. The second block ("fixSpawn connection edge cases") contained only
one test ("shows success when fix script succeeds") and could be merged directly
into the first block ("fixSpawn (additional coverage)") without any loss of
coverage or setup fidelity.
Removes 23 lines of duplicated boilerplate. Test count unchanged (6 tests).
---------
Co-authored-by: spawn-qa-bot <qa@openrouter.ai>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(config): extend biome.json includes to cover .claude/**/*.ts
Add .claude/**/*.ts to biome.json includes so TypeScript files in
.claude/scripts/ and .claude/skills/ are covered by biome formatting.
Linting is disabled for .claude/** via override because the GritQL
plugins (no-try-catch, no-typeof-string-number) target the main CLI
codebase and cannot be scoped per-path — .claude/ hook scripts
legitimately use try/catch as they run standalone outside the package.
Agent: pr-maintainer
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix(prompts): stop infinite shutdown loop after TeamDelete in non-interactive mode (#3116)
After TeamDelete completes in -p (non-interactive) mode, Claude Code's
harness was re-injecting shutdown prompts every turn. The root cause:
the Monitor Loop instructed the agent to call TaskList + Bash on EVERY
iteration, including after TeamDelete, which kept the session alive so
the harness could inject more shutdown prompts.
Fix: add an explicit EXCEPTION to both refactor-team-prompt.md and
refactor-issue-prompt.md instructing the team lead that after TeamDelete
is called, the very next response MUST be plain text only with no tool
calls. A text-only response is the termination signal for the
non-interactive harness.
Fixes#3103
Agent: issue-fixer
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix(zeroclaw): remove broken zeroclaw agent (repo 404) (#3107)
* fix(zeroclaw): remove broken zeroclaw agent (repo 404)
The zeroclaw-labs/zeroclaw GitHub repository returns 404 — all installs
fail. Remove zeroclaw entirely from the matrix: agent definition,
setup code, shell scripts, e2e tests, packer config, skill files,
and documentation.
Fixes#3102
Agent: code-health
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix(zeroclaw): remove stale zeroclaw reference from discovery.md ARM agents list
Addresses security review on PR #3107 — the last remaining zeroclaw
reference in .claude/rules/discovery.md is now removed.
Agent: issue-fixer
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix(zeroclaw): remove remaining stale zeroclaw references from CI/packer
Remove zeroclaw from:
- .github/workflows/agent-tarballs.yml ARM build matrix
- .github/workflows/docker.yml agent matrix
- packer/digitalocean.pkr.hcl comment
- sh/e2e/e2e.sh comment
Addresses all 5 stale references flagged in security review of PR #3107.
Agent: issue-fixer
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix(cli): allow --headless and --dry-run to be used together (#3117)
Removes the mutual-exclusion validation that blocked combining these flags.
Both flags serve independent purposes: --dry-run previews what would happen,
--headless suppresses interactive prompts and emits structured output.
Combining them is valid for CI pipelines that want structured JSON previews.
Fixes#3114
Agent: issue-fixer
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix(cli): allow --headless and --dry-run to be used together (#3118)
* test: remove redundant theatrical assertions (#3120)
Remove bare toHaveBeenCalled() checks that preceded stronger content
assertions, and strengthen the "shows manual install command" test to
verify the actual install script URL appears in output.
Affected files:
- cmd-update-cov: remove redundant consoleSpy.toHaveBeenCalled() (x2),
strengthen "shows manual install command" to check install.sh content
- update-check: remove redundant consoleErrorSpy.toHaveBeenCalled() (x2)
that were immediately followed by .mock.calls content assertions
- recursive-spawn: remove redundant logInfoSpy.toHaveBeenCalled() before
content check
- cmd-interactive: remove redundant mockIntro/mockOutro.toHaveBeenCalled()
before content checks
Co-authored-by: spawn-qa-bot <qa@openrouter.ai>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: sync README tagline with manifest (9 agents/54 → 8 agents/48 combinations) (#3119)
Co-authored-by: spawn-qa-bot <qa@openrouter.ai>
Co-authored-by: L <6723574+louisgv@users.noreply.github.com>
* docs: remove stale ZeroClaw references after agent removal (#3122)
ZeroClaw was removed in #3107 (repo 404). Two doc references were left
behind:
- .claude/rules/agent-default-models.md: table row for ZeroClaw model config
- README.md: ZeroClaw listed in --fast skip-cloud-init agent examples
Agent: code-health
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(e2e): redirect DO max_parallel log_warn to stderr (#3110)
_digitalocean_max_parallel() called log_warn which writes colored output
to stdout, polluting the captured return value when invoked via
cloud_max=$(cloud_max_parallel). The downstream integer comparison
[ "${effective_parallel}" -gt "${cloud_max}" ] then fails with
'integer expression expected', silently leaving the droplet limit cap
unapplied. Fix: redirect log_warn output to stderr so only the numeric
value is captured.
Co-authored-by: spawn-qa-bot <qa@openrouter.ai>
Co-authored-by: L <6723574+louisgv@users.noreply.github.com>
* refactor: remove stale ZeroClaw references from docs and code comments
---------
Signed-off-by: Ahmed Abushagur <ahmed@abushagur.com>
Co-authored-by: spawn-qa-bot <qa@openrouter.ai>
Co-authored-by: Ahmed Abushagur <ahmed@abushagur.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: spawn-bot <spawn-bot@openrouter.ai>
Previously buildFixScript() resolved env templates directly from
process.env, silently writing empty values when the user authenticated
via OAuth (key stored in ~/.config/spawn/openrouter.json). Now fixSpawn()
loads the saved key before building the script, matching orchestrate.ts.
Fixes#3094
Agent: code-health
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
cursor is a fully implemented agent across all 6 clouds but was missing
from the available agents list in spawn skill instructions injected onto
child VMs. This caused claude, codex, hermes, junie, kilocode, openclaw,
opencode, and zeroclaw to be unaware they could delegate work to cursor.
Signed-off-by: Ahmed Abushagur <ahmed@abushagur.com>
Co-authored-by: spawn-qa-bot <qa@openrouter.ai>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Ahmed Abushagur <ahmed@abushagur.com>
Cursor CLI requires authentication before making API calls. Without
CURSOR_API_KEY set, it falls back to browser-based OAuth which fails
because the proxy spoofs api2.cursor.sh to localhost, breaking the
OAuth callback. Setting a dummy CURSOR_API_KEY makes Cursor use the
/auth/exchange_user_api_key endpoint instead, which the proxy already
handles with a fake JWT.
Co-authored-by: spawn-bot <spawn-bot@openrouter.ai>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Cursor CLI v2026.03.25 only allows --trust in headless/print mode.
Launching interactively with --trust causes immediate exit with error.
Co-authored-by: spawn-bot <spawn-bot@openrouter.ai>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Ahmed Abushagur <ahmed@abushagur.com>
- Revert local security warning to openclaw-only (was blocking all agents)
- Update spawn skill to document how to run prompts on child VMs:
- Always use `bash -lc` (binaries in ~/.local/bin/ need login shell)
- Claude uses `-p` not `--print` or `--headless`
- Add `--dangerously-skip-permissions` for unattended child VMs
- Don't waste tokens with `which`/`find` or creating non-root users
- Sync all on-disk skill files with embedded version
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
resolveEntityKey() and checkEntity() checked manifest.agents[input] directly,
bypassing the disabled filter in agentKeys(). This let users run `spawn cursor
<cloud>` even though cursor is disabled, wasting time provisioning a VM for an
agent that can't route through OpenRouter. Now both functions check the disabled
flag and show the disabled_reason to the user.
Also removes stale cursor references from spawn skill templates injected into
child VMs.
Agent: code-health
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
The cursor installer changed its binary install location from
~/.cursor/bin/agent to ~/.local/bin/agent (as of 2026-03-25 release).
Updates:
- agent-setup.ts: fix PATH in install, launchCmd, updateCmd, and
the pathScript written to ~/.bashrc/~/.zshrc
- verify.sh: fix E2E binary check to look in ~/.local/bin first
- Bump CLI to 0.27.3
-- qa/e2e-tester
Co-authored-by: spawn-qa-bot <qa@openrouter.ai>
- Replace repeated 'SSH port closed (N/36)' with periodic updates every 5 attempts
- Add clear 'Provisioning complete. Connecting...' line before agent attach
Fixes#3053
Agent: ux-engineer
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
The skill now documents that --headless only provisions (doesn't run
the prompt), that agent binaries are at ~/.local/bin/ (not on PATH),
and that --print should be used for one-shot prompts as root instead
of fighting with permission restrictions.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace StrictHostKeyChecking=no with accept-new across all E2E cloud
drivers (aws, gcp, digitalocean, hetzner), the shared SSH_BASE_OPTS
constant, and pull-history.ts. accept-new trusts new hosts on first
connection (needed for freshly provisioned VMs) but verifies on
subsequent connections, preventing MITM attacks on reconnect.
Fixes#3031
Agent: style-reviewer
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Replace base64-into-shell interpolation with SCP-based uploadConfigFile()
for Claude Code settings.json and Cursor CLI config files. This eliminates
the attack surface of injecting encoded payloads into shell command strings.
Add chmod 600 on ~/.openclaw/openclaw.json after writing the Telegram bot
token to prevent other users on the VM from reading the token in plaintext.
Fixes#3033Fixes#3034
Agent: security-auditor
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* feat: pull child spawn history back to parent for `spawn tree`
When the interactive session ends (or headless mode completes), the
parent downloads the child VM's history.json and merges records into
local history. Before downloading, it runs `spawn pull-history` on the
child, which recursively pulls from all grandchildren — so the full
tree collapses up to the root regardless of depth.
Changes:
- Add getParentFields() — sets parent_id/depth on saveSpawnRecord calls
- Add pullChildHistory() — downloads + merges child history after session
- Add `spawn pull-history` command for recursive SSH-based history pull
- Add 11 tests for parseAndMergeChildHistory
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: trigger CI recompute
Agent: pr-maintainer
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(security): validate user/ip params before SSH exec in pull-history
Agent: pr-maintainer
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(security): use shared validators for SSH params in pull-history and delete
Replace inline regex checks in pull-history.ts with validateUsername()
and validateConnectionIP() from security.ts, matching the pattern used
across connect.ts, fix.ts, and link.ts. Also add the same validation
to delete.ts:pullChildHistory which had no SSH parameter validation.
orchestrate.ts uses the runner abstraction (not raw user@ip), so its
SSH params come from the cloud provider, not untrusted history records.
Agent: pr-maintainer
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Ahmed Abushagur <ahmed@abushagur.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
* feat: add Cursor CLI agent across all clouds
Adds Cursor's terminal-based AI coding agent (the `agent` command from
cursor.com/cli) to the spawn matrix. Routes LLM requests through
OpenRouter via --endpoint flag and CURSOR_API_KEY env var.
- manifest.json: new cursor agent entry + all 6 cloud matrix entries
- agent-setup.ts: install, configure, launch, and update definitions
- Shell scripts for all 6 clouds (local, hetzner, aws, do, gcp, sprite)
- Config: writes ~/.cursor/cli-config.json with full permissions
- Icon: cursor.png from cursor.com/apple-touch-icon.png
- All cloud READMEs updated with cursor.sh usage
- CLI version bumped to 0.26.0
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add spawn skill injection for Cursor CLI
Writes a .cursor/rules/spawn.mdc rule file with alwaysApply: true
during setup, teaching the Cursor agent how to use the spawn CLI
to provision child cloud VMs. Uses the same base64 upload pattern
as other agent config files.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Signed-off-by: Ahmed Abushagur <ahmed@abushagur.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: A <258483684+la14-1@users.noreply.github.com>
Shows a non-intrusive "⭐ Enjoying Spawn? Star us on GitHub!" message
to returning users (2+ successful spawns) after a successful spawn
session completes. Shown at most once per 30 days.
- New `maybeShowStarPrompt()` in `shared/star-prompt.ts`
- Tracks `starPromptShownAt` in `~/.config/spawn/preferences.json`
- Called after `execScript()` returns success in cmdRun, cmdInteractive,
and cmdAgentInteractive (skipped in headless mode)
- The `execScript()` return type changed from `void` to `boolean`
to indicate whether the script ran successfully
- Added 7 unit tests covering all gate conditions
Fixes#3020
Agent: issue-fixer
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Agents running on spawned VMs couldn't delete child spawns because
`spawn delete` requires an interactive terminal for the picker UI.
Added --name and --yes flags: when both are provided in non-interactive
mode, the server matching the name is deleted without prompts. This
enables agents to manage their own child VMs programmatically.
Updated all skill files to teach agents the headless delete syntax.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: A <258483684+la14-1@users.noreply.github.com>
Replace hand-constructed openrouter.json path with getSpawnCloudConfigPath("openrouter")
for single-source-of-truth path resolution. Remove unused _cloudName parameter since
the function delegates ALL cloud credentials unconditionally.
Agent: ux-engineer
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Add /^[A-Za-z0-9+/=]+$/ validation after each .toString("base64") call
in delegateCloudCredentials() and injectEnvVars(), consistent with the
pattern established in agent-setup.ts by #2988.
Agent: security-auditor
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(ux): replace download spinner with stderr logging, reset terminal before SSH handoff
Fixes two UX issues from live E2E session (#3001):
1. Download spinner (p.spinner from @clack/prompts) wrote ANSI escape codes
to stdout. When stdout is captured (E2E harness, piped output), these
sequences appeared as raw text rather than rendered colors. Replace
p.spinner() in downloadScriptWithFallback and downloadBundle with
logStep/logInfo/logError from shared/ui.ts, which write to stderr and
correctly check isTTY before emitting ANSI codes.
2. Garbled output at start of interactive session (overlapping status lines
from the remote agent's TUI) may be caused by residual ANSI state from
@clack/prompts (hidden cursor, active color attributes). Emit
ESC[?25h ESC[0m to stderr before prepareStdinForHandoff() to explicitly
restore cursor visibility and reset all attributes before the SSH session
takes over.
Agent: issue-fixer
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: resolve ANSI spinner corruption and garbled output in interactive mode (#3001)
Three root causes fixed:
1. Spinner wrote to stdout while all other CLI status output goes to stderr,
causing ANSI escape sequence interleaving and corruption when both streams
are merged on a terminal. Redirected all p.spinner() calls to process.stderr.
2. unicode-detect.ts (which sets TERM=linux for SSH sessions to force ASCII
fallback) was only imported in commands/shared.ts but not in shared/ui.ts.
Cloud module entry points (hetzner/main.ts, etc.) that import shared/ui.ts
loaded @clack/prompts without the TERM override, causing Unicode spinner
frames in environments that can't render them.
3. After an interactive SSH session ends, the remote agent's TUI (e.g. Claude
Code) may leave the terminal in raw mode with altered attributes. Added
terminal reset (ANSI attribute reset + stty sane) after spawnInteractive()
returns to prevent garbled post-session output.
Agent: ux-engineer
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
