[Bug]: hermes fails on sprite.dev — user forced to switch clouds

[la14-1]

What happened?

User report via Slack (Andrew, 2026-05-12 → 2026-05-13):

[shares terminal screenshot of hermes failing on sprite — HERMES_AGENT watermark visible]
KP? should i not use sprite.dev?

(next day, after switching)
switched to digitalocean
almost works, but your script is outdated. hermes dashboard isn't a command ^

So spawn run hermes on sprite.dev failed badly enough that Andrew abandoned the cloud and moved to DigitalOcean. The companion DO bug is filed separately as #3407.

What we know

• Cloud: sprite (sprite.dev managed VMs)
• Agent: hermes
• The exact error text is not legible in the forwarded screenshot — we need Andrew (or the next person who can repro) to share the full output.
• Hermes is wired up on sprite via sh/sprite/hermes.sh → packages/cli/src/sprite/main.ts → shared agent-setup.ts → agents.hermes.
• Hermes install on sprite uses the same path as every other cloud:

  curl --proto '=https' -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-setup
  

  with a 600s timeout. This is the heaviest install in the matrix (uv + Python venv + many pip deps + Node) and has timed out on cheaper/network-constrained clouds before (see closed bug: hermes fails on hetzner/gcp/digitalocean — mini-swe-agent pip install SSH connection timeout #2955).

Likely suspects on sprite specifically

1. Install timeout / transient network blip — hermes's install.sh is long; sprite VMs can be slower than DO/Hetzner during the uv+pip phase.
2. Tunnel handling differs — sprite uses the sprite-console IP sentinel and skips the SSH tunnel branch in connect.ts:303, so the dashboard tunnel never gets established even when startHermesDashboard() succeeds. The user wouldn't see a usable dashboard URL on sprite.
3. Keep-alive interaction — sprite's installSpriteKeepAlive + startLocalKeepAlive may interact poorly with the long-running hermes install (e.g. session reset mid-install).
4. Dashboard preLaunch — agents.hermes.preLaunch = startHermesDashboard runs on every cloud including sprite; if it errors on sprite the user sees a confusing "Hermes web dashboard failed to start" warning even though the TUI itself works.

Asks

• From Andrew (or Slack thread): the full terminal output of the failing spawn run hermes on sprite — paste of the red error, last ~50 lines.
• For us to do once we have the error:
  • Reproduce on a fresh sprite VM and capture ~/spawn-install.log (or the equivalent install log) + /tmp/hermes-dashboard.log if the dashboard launched.
  • Bump the hermes install timeout on sprite if it's a timeout, or surface the actual install failure instead of a generic timeout.
  • Skip startHermesDashboard() on clouds that don't get the SSH tunnel (sprite), or wire sprite into the dashboard piping path so the user actually has a dashboard URL.
  • Document hermes-on-sprite as known-working in sh/sprite/README.md once verified.

Reference

• sh/sprite/hermes.sh
• packages/cli/src/sprite/main.ts
• packages/cli/src/shared/agent-setup.ts:1315-1361 — hermes config
• packages/cli/src/shared/agent-setup.ts:713-754 — startHermesDashboard
• packages/cli/src/commands/connect.ts:303 — sprite-console branch skipping tunnel
• Companion DO bug: [Bug]: hermes on digitalocean fails — hermes dashboard reported as not a command #3407
• Slack screenshot from Andrew (sprite hermes fail, 2026-05-12 18:27 + DO follow-up 2026-05-13 07:55)

---

Filed from Slack by SPA

[la14-1]

Root cause confirmed (from Andrew)

the error was that -skip-console is deprecated and there's a new command on sprite for it

The sprite CLI (now v0.0.1-rc43 from https://sprites.dev/install.sh) has rejected several single-dash long flags and renamed/deprecated commands. Our packages/cli/src/sprite/sprite.ts and packages/cli/src/commands/connect.ts still use the old forms, so spawn run hermes (and every other agent) fails on sprite at the sprite create step before the agent install ever runs.

Specific breakages found by diffing our calls vs sprite <cmd> --help

Where	Old (broken)	New
sprite/sprite.ts:148	sprite version	sprite --version (subcommand removed)
sprite/sprite.ts:321	sprite create -skip-console	sprite create --skip-console
sprite/sprite.ts:429	sprite url -s NAME	sprite info -s NAME (url is deprecated, "use 'sprite info' to view")
sprite/sprite.ts:605	sprite exec ... -file SRC:DST	sprite exec ... --file SRC:DST
sprite/sprite.ts:784	sprite exec -s NAME -tty	sprite exec -s NAME --tty
commands/connect.ts:268,275	sprite exec -s NAME -tty -- bash …	sprite exec -s NAME --tty -- bash …

Tests that pin the old flag literals also need updating:

• __tests__/cmd-connect-cov.test.ts:247 — expect(args).toContain("-tty")
• __tests__/sprite-keep-alive.test.ts:207, 221 — expect(capturedArgs).toContain("-tty") / .not.toContain("-tty")

The first user-visible failure is on sprite create -skip-console NAME (the very first remote call after auth), which matches Andrew's "KP? should i not use sprite.dev?" report — every cloud-init step after that would never run.

Filing fix in a PR.

[la14-1]

Bug acknowledged — hermes on sprite.dev fails due to sprite CLI flag breaking changes. Teammates are actively working on a fix this cycle.

-- refactor/community-coordinator

[la14-1]

Fix in #3409 — branch policy requires a review before I can merge. CI is green: Biome / Unit Tests / Mock Tests / ShellCheck / macOS Compatibility all pass.