[Bug]: hermes on digitalocean fails — `hermes dashboard` reported as not a command

[la14-1]

What happened?

User reports via Slack (Andrew, on DigitalOcean):

switched to digitalocean
almost works, but your script is outdated. hermes dashboard isn't a command ^

So spawn run hermes on a DigitalOcean droplet "almost works", but somewhere in the flow the user sees an error that hermes dashboard is not a valid command — most likely surfaced by argparse from the hermes CLI itself.

Where we invoke hermes dashboard

In packages/cli/src/shared/agent-setup.ts → startHermesDashboard() we run, in the background:

export PATH=\"\$HOME/.local/bin:\$HOME/.hermes/hermes-agent/venv/bin:\$PATH\"
hermes dashboard --port 9119 --host 127.0.0.1 --no-open

…and tail the resulting /tmp/hermes-dashboard.log if it doesn't come up within 60s. The launch is wrapped in asyncTryCatch so failures only emit a warn log (Hermes web dashboard failed to start — TUI still available), but the underlying argparse error from hermes is what Andrew is quoting.

Likely causes

hermes dashboard IS a valid subparser in NousResearch/hermes-agent main (see hermes_cli/main.py — dashboard_parser = subparsers.add_parser(\"dashboard\", ...)), so the install must be picking up an older or partial copy on DigitalOcean:

1. The hermes installer (install.sh --skip-setup) installs from main, but our flow may be racing — dashboard launch happens before install fully completes, or the venv hasn't refreshed entrypoints.
2. fastapi/uvicorn aren't in the venv → cmd_dashboard exits 1 with an import error message (not the same string the user quoted, but possibly the source).
3. Stale/mixed install where the binary script under ~/.hermes/hermes-agent/venv/bin/hermes predates the dashboard subcommand (Apr 13 rename from hermes web).
4. PATH resolves to a different hermes (e.g. /usr/local/bin/hermes from an older system install) than the venv-installed one.

What to investigate / fix

• Reproduce on DigitalOcean (spawn run hermes on a fresh droplet) and capture:
  • which hermes, command -v hermes, head -1 \$(command -v hermes)
  • hermes --version
  • cat /tmp/hermes-dashboard.log
  • hermes --help (to confirm dashboard is listed)
• If the dashboard subcommand is genuinely missing on the installed version, force-pin a known-good ref in our install.sh invocation, or run hermes update after --skip-setup.
• If fastapi/uvicorn import fails, ensure the dashboard extras get installed (or call hermes dashboard --skip-build once the dist is prebuilt).
• Consider gating startHermesDashboard() behind a probe: hermes dashboard --help >/dev/null 2>&1 before launching, so we never surface confusing errors in the user's session.
• Also pipe the failure output back to the user via logWarn so we don't silently swallow the real cause.

Reference

• packages/cli/src/shared/agent-setup.ts:713-754 — startHermesDashboard
• packages/cli/src/__tests__/hermes-dashboard.test.ts
• Slack screenshot from Andrew (DigitalOcean, 2026-05-13)

---

Filed from Slack by SPA

[la14-1]

Bug acknowledged — hermes on DigitalOcean fails because hermes dashboard is not a valid command. Teammates are actively working on a fix this cycle.

-- refactor/community-coordinator

[la14-1]

Per Andrew's call, I shipped option 1 first: surface the actual cause instead of swallowing it.

PR #3413 — startHermesDashboard() now installs an EXIT trap that, on any non-zero exit, dumps a banner-delimited diagnostic block to stderr (which is inherited live to the spawn output):

──── Hermes dashboard diagnostic ────
hermes binary: /home/.../venv/bin/hermes
hermes version: Hermes Agent v0.13.0 (2026.5.7)
hermes subcommands: includes "dashboard"        # or: NOT in --help output
─── /tmp/hermes-dashboard.log (last 30 lines) ───
<actual hermes process output>
─────────────────────────────────────

The trap is cleared on success so it stays quiet when things work. The TS-side warning now also includes the underlying error message and points users at the diagnostic block.

This issue stays open until we get a real diagnostic from the next user (or Andrew on his next DO run) — at which point we'll have a concrete cause to fix.

[la14-1]

Two fixes in progress for this issue:

• fix(hermes): gate dashboard launch behind capability probe #3410 — gates dashboard launch behind a capability probe
• fix(hermes): surface dashboard launch failures with a real diagnostic block #3413 — surfaces dashboard launch failures with diagnostic output

-- refactor/community-coordinator

[la14-1]

Fix in #3413.

-- refactor/community-coordinator