Repository navigation
Description
Bug Description
Hermes Desktop (macOS, Apple Silicon) is stuck in a permanent install loop. The first-launch bootstrap completes successfully, but on every relaunch the app re-shows the "Install Hermes" screen instead of opening the chat UI, and reports "Hermes couldn't start" with Hermes backend did not become ready: connect ECONNREFUSED 127.0.0.1:9130. Reinstalling/repairing completes successfully each time but never breaks the loop.
Steps to Reproduce
On a macOS machine where the system Python (/usr/bin/python3) is older than 3.10 — confirm with /usr/bin/python3 --version (mine reports 3.9.x). Stock macOS ships 3.9, so this is the default state on many Macs without a newer Python on PATH.
Install Hermes Desktop (arm64) and let first-launch bootstrap complete. The bootstrap log ends with ✓ Installation Complete! and a valid install at ~/.hermes/hermes-agent (venv = Python 3.11.15).
Quit and relaunch the Hermes Desktop app.
Observe: instead of opening to chat, the app shows the "Install Hermes" screen again (and/or "Hermes couldn't start — connect ECONNREFUSED 127.0.0.1:9130").
Run the install/repair again → it completes successfully again → relaunch → same install prompt. Infinite loop; reinstalling never breaks out of it.
What's actually happening (from ~/.hermes/logs/desktop.log, first lines of each boot):
Ignoring system Python /usr/bin/python3: hermes_cli is not importable; falling through to bootstrap.
[bootstrap] no Hermes install found; starting first-launch bootstrap
The install-detection probe imports hermes_cli using system python3 (3.9), which fails on str | None syntax (PEP 604, 3.10+), so the app decides Hermes isn't installed and re-bootstraps every launch.
Minimal confirmation the install itself is fine — only the interpreter choice is wrong:
Fails (system 3.9, the path the app's probe takes):
/usr/bin/python3 -c "import sys; sys.path.insert(0, '$HOME/.hermes/hermes-agent'); import hermes_cli.main"
→ TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
Works (bundled venv 3.11 — what the app should use):
~/.hermes/hermes-agent/venv/bin/python ~/.hermes/hermes-agent/hermes_cli/main.py gateway run --replace
→ "⚕ Hermes Gateway Starting…" (runs cleanly)
Expected Behavior
After the bootstrap install completes successfully, relaunching Hermes Desktop should open directly to the chat interface, with the background gateway running and reachable on its local port (e.g. 127.0.0.1:9130). The "Install Hermes" first-launch screen should not reappear once a valid install exists, and the app should not fall into a connect/ECONNREFUSED retry loop.
Actual Behavior
After the bootstrap install completes successfully (✓ Installation Complete! in the bootstrap log), relaunching Hermes Desktop does not open the chat UI. Instead:
The app displays the "Install Hermes" first-launch screen again, as if no install exists.
When it attempts to connect, it shows "Hermes couldn't start — The background gateway didn't come up" with error Hermes backend did not become ready: connect ECONNREFUSED 127.0.0.1:9130.
The app retries the connection in a tight loop, logging Resolving Hermes backend → Connecting to remote Hermes backend at http://127.0.0.1:9130 → Desktop boot failed: ... ECONNREFUSED repeatedly, never succeeding.
Running install/repair again completes successfully again, but the next launch returns to the same "Install Hermes" screen. The loop is permanent — reinstalling never resolves it.
Nothing is ever listening on 127.0.0.1:9130 (lsof -i :9130 returns empty), because the gateway never actually starts: the launcher invokes system /usr/bin/python3 (3.9), which fails to import hermes_cli on str | None syntax, so the backend process dies before binding the port.
Affected Component
Setup / Installation
Messaging Platform (if gateway-related)
No response
Debug Report
Debug report uploaded:
Report https://paste.rs/G42Gf
agent.log https://dpaste.com/2VV9K6QXD
gateway.log https://paste.rs/AFvEf
desktop.log https://dpaste.com/CAQANR34JOperating System
MacOS 26.5.1 (25F80)
Python Version
3.12.13
Hermes Version
0.16.0 (internal build 0.15.1)
Additional Logs / Traceback (optional)
Workaround attempted: Installed Python 3.12.13 via Homebrew and confirmed it wins PATH (python3 --version → 3.12.13, /opt/homebrew/bin/python3 listed first in which -a python3). Hermes Desktop still shows "Install Hermes" on relaunch — confirming the launcher hardcodes /usr/bin/python3 rather than resolving via PATH. No user-side workaround exists.Root Cause Analysis (optional)
The root cause is in the desktop launcher's install-detection: it probes system /usr/bin/python3 (3.9) to import hermes_cli, which fails because the code uses str | None syntax (PEP 604, Python 3.10+) — hermes_cli/main.py:207 raises TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'. Because the import fails, the app concludes Hermes isn't installed and re-bootstraps, regardless of the working install present. The gateway never starts (nothing listens on 9130). Running the gateway with the bundled venv Python (3.11) works perfectly, confirming only the launcher's interpreter selection is at fault.
Proposed Fix (optional)
No response
Are you willing to submit a PR for this?
- I'd like to fix this myself and submit a PR
Activity
m0st4f4-hub commentedon Jun 11, 2026
Native Windows 11 — the auto-repair loop is brutal here
Reproducing on Windows 11, packaged
Hermes.exe(apps/desktop/release/win-unpacked/):If
.hermes-bootstrap-completeis missing — even when the venv,app.asar,web_dist, andbin/hermes.EXEare all valid and locally bootinghermes dashboardworks —Hermes.exedecides the install is "incomplete" and runs the bootstrap installer again. On Windows that means:npm ciover the entire workspace (~hundreds of MB ofnode_modules).npm run packfor the desktop workspace.0.27.7vs0.28.0wall every time, because lockfile state is reset.For a user on tight disk (5.9 GB free in my case), every loop eats hundreds of MB more in temp/
node_moduleschurn before failing, and there's no way out from the GUI.Workaround that worked end-to-end on Windows
hermes dashboard --profile <name>from a regular PowerShell — this needs PR fix(cli): skip dashboard re-exec on Windows to avoid execvpe segfault #44355'ssys.platform == "win32"guard or it hard-crashes viaos.execvpe. With the guard, the dashboard runs in-place, buildsweb_dist, and exits cleanly (~50 s on warm cache)..hermes-bootstrap-completeat the install root with the fieldsmain.cjsactually validates:{ "schemaVersion": 1, "pinnedCommit": "<git rev-parse HEAD of the install>", "pinnedBranch": "<branch>", "completedAt": "<ISO8601>", "desktopVersion": "0.14.0" }Hermes.exe— it now skips bootstrap,[boot] Resolving Hermes runtime→[boot] Hermes backend is readyin seconds.Why PR #43983 matters on Windows
PR #43983's
active-install.cjsheuristic ("trust an install whosehermes.EXE+app.asar+ venv are all present, even without a marker") is exactly what's needed here so users don't have to manually forge the marker. Strongly +1 from a Windows perspective — please consider merging or carrying forward.(For reference: with all three carried commits #44024, #44355, #43983 the install + first-launch is reliable on native Windows. Without them, every Windows install fails into a loop that consumes more disk on each retry — and anyone on a tight C: drive can't recover without manual surgery.)
rod-nxtlevel commentedon Jun 17, 2026
macOS variant: bootstrap failure cascading into retry loop (Electron download)
Reporting an additional failure path on macOS (Apple Silicon, Hermes v0.16.0, git-installed) that produces the same "Install Hermes" loop symptom but with a different root cause than the Python 3.9 detection issue.
Failure chain
hermes updatestashes and loses.hermes-bootstrap-complete— the update process detected local changes (carried PR commits), stashed them, and the marker wasn't restored. This is fixed byb459bac02(gitignoring the marker), but the damage was already done on this install.Electron binary can't be downloaded from GitHub — the bootstrap installer runs
npm run packinapps/desktop/, which callselectron-builder --dir. This fails becausenode_modules/electron/distdoesn't exist (GitHub download blocked/rejected):The bootstrap's built-in mirror retry (
npmmirror.com) also failed on this run — theELECTRON_MIRRORmechanism in the bootstrap installer appears less robust than a directnpm install electron@40.10.2with the mirror env var.This is partially addressed by
d1ecebcbfwhich adds Electron mirror retry logic, but the bootstrap still failed 3x across multiple attempts..hermes-bootstrap-completemarker + failed bootstrap state = infinite retry loop — on every Desktop launch,Hermes-Setupdetects the failed state and re-runs the installer. Since Electron still can't download, it fails again. The user sees two windows: the working Hermes Desktop (from a previously-built app) AND a second "Install Hermes" window fromHermes-Setupretrying in the background.Evidence — Hermes-Setup running alongside Desktop
Workaround (manual recovery)
The only way out is to:
Install Electron manually via mirror:
Rebuild Desktop:
Kill the rogue
Hermes-SetupprocessManually create the bootstrap-complete marker to prevent re-trigger:
{ "schemaVersion": 1, "pinnedCommit": "<HEAD commit>", "pinnedBranch": "main", "completedAt": "<ISO8601>", "desktopVersion": "0.16.0" }(written to
~/.hermes/hermes-agent/.hermes-bootstrap-complete)Proposed fixes (beyond what's already merged)
Three existing fixes address pieces of this:
b459bac02hermes updated1ecebcbfapp.asar+ venv exist, even without markerRemaining gap: If the bootstrap fails for any reason (Electron, network, npm, lockfile, etc.), the user is trapped in the "Install Hermes" window with no escape path:
Hermes-Setupretries the installer in a second window.app.asar, working venv, and functional gateway connection already exist, even without the marker. PR fix(desktop): trust bundled venv install without marker (#43913) #43983's heuristic is exactly what's needed here.Strong +1 on merging PR #43983. Additionally, the bootstrap should implement a maximum retry count (e.g. 2-3 attempts) before surfacing a "skip and launch anyway" option in the GUI, rather than looping indefinitely.