Hermes Switch UI — Agent Connect Diagnostic

Visual decision tree for "agent unavailable" symptoms — check in order of frequency

Agent unavailable banner / chat not responding sessions won't load · "Gateway offline" · no model response Is hermes-agent process running? Check: open http://127.0.0.1:8642/health in browser → JSON payload = healthy YES NO FIX — START THE AGENT Dev: restart pnpm dev (auto-starts agent) Manual: hermes gateway run Requires API_SERVER_ENABLED=true in ~/.hermes/.env Production: restart app to re-launch agent HERMES_API_URL correct? default: http://127.0.0.1:8642 YES FIX — CORRECT THE URL Unset HERMES_API_URL (uses default) or set to correct host:port LAN: set API_SERVER_HOST=0.0.0.0 on agent NO ↓ API_SERVER_ENABLED=true set? in ~/.hermes/.env · enables HTTP API on port 8642 YES FIX — ENABLE THE API SERVER Add API_SERVER_ENABLED=true to ~/.hermes/.env Restart hermes gateway run NO ↓ API_SERVER_KEY ↔ HERMES_API_TOKEN match? if API_SERVER_KEY set, app must send matching token YES FIX — SYNC THE TOKEN Set HERMES_API_TOKEN=<same value as API_SERVER_KEY> in hermes-switchui/.env · restart app NO ↓ Binding to 0.0.0.0? HERMES_PASSWORD set? app refuses non-loopback without password guard YES FIX — SET HERMES_PASSWORD Set HERMES_PASSWORD=<strong-secret> in .env or keep HOST=127.0.0.1 (loopback only) NO ↓ Provider configured in config.yaml? agent up but chat fails → no working provider YES FIX — CONFIGURE PROVIDER Follow: Connecting your AI provider provider: manifest type in config.yaml NO ↓ Gateway capability probe successful? check [gateway] log line · mode=zero-fork expected Connected · mode: zero-fork NO CAPABILITY PROBE MODES zero-fork all core + enhanced capabilities detected enhanced-fork some optional capabilities missing portable UI-only, basic chat works, no extended APIs disconnected nothing reachable · full restart needed Fix: force re-probe from Settings → connection panel or restart agent first, then restart the app check nothing else bound to port 8642 QUICK REFERENCE Check order (most common first) ① Agent process curl http://127.0.0.1:8642/health fix: pnpm dev / hermes gateway run ② Gateway URL check HERMES_API_URL in .env default: http://127.0.0.1:8642 ③ API_SERVER_ENABLED must be true in ~/.hermes/.env activates port 8642 HTTP API ④ Token mismatch API_SERVER_KEY ↔ HERMES_API_TOKEN must be identical strings ⑤ Password guard HOST=0.0.0.0 requires HERMES_PASSWORD safety guard for non-loopback binding ⑥ No provider agent up, chat fails → config.yaml follow: Connecting your AI provider ⑦ Probe / mode check [gateway] log line for mode= target: zero-fork (full feature set) Logs locations dev: terminal running pnpm dev agent: ~/.hermes/ log files docker: docker logs <container-name> Still stuck? force re-probe from Settings panel restart agent first, then app check nothing else on port 8642 verify .env files don't disagree Color key cyan — decision / check emerald — fix action / YES path rose — symptom / NO branch violet — probe mode table

Most Common Causes

  • • Agent process not running — check port 8642 health endpoint
  • • API_SERVER_ENABLED=true missing from ~/.hermes/.env
  • • HERMES_API_URL pointing at wrong host/port
  • • Token mismatch: API_SERVER_KEY vs HERMES_API_TOKEN

Network / Remote

  • • Remote bind (HOST=0.0.0.0) without HERMES_PASSWORD
  • • Agent not bound to non-loopback: set API_SERVER_HOST=0.0.0.0
  • • Port conflict — check nothing else on 8642
  • • LAN / Tailscale: verify firewall allows port 8642

Probe Modes

  • • zero-fork — all core + enhanced OK
  • • enhanced-fork — some optional features missing
  • • portable — basic chat only, no extended APIs
  • • disconnected — nothing reachable; full restart needed
  • • Force re-probe from Settings → connection panel

hermes-switchui · Agent Connect Diagnostic · docs/troubleshooting/agent-connect.md