Skip to content

[Bug]: Desktop install loop on macOS — launcher uses system python3 (3.9) instead of bundled venv, hermes_cli import fails, gateway never starts #43913

Open

Description

@dtlb324

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/CAQANR34J

Operating 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

  1. added
    type/bugSomething isn't working
    comp/cliCLI entry point, hermes_cli/, setup wizard
    P3Low — cosmetic, nice to have
    on Jun 11, 2026
  2. m0st4f4-hub commented on Jun 11, 2026

    @m0st4f4-hub

    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-complete is missing — even when the venv, app.asar, web_dist, and bin/hermes.EXE are all valid and locally booting hermes dashboard works — Hermes.exe decides the install is "incomplete" and runs the bootstrap installer again. On Windows that means:

    For a user on tight disk (5.9 GB free in my case), every loop eats hundreds of MB more in temp/node_modules churn before failing, and there's no way out from the GUI.

    Workaround that worked end-to-end on Windows

    1. Run hermes dashboard --profile <name> from a regular PowerShell — this needs PR fix(cli): skip dashboard re-exec on Windows to avoid execvpe segfault #44355's sys.platform == "win32" guard or it hard-crashes via os.execvpe. With the guard, the dashboard runs in-place, builds web_dist, and exits cleanly (~50 s on warm cache).
    2. Hand-write .hermes-bootstrap-complete at the install root with the fields main.cjs actually validates:
      {
        "schemaVersion": 1,
        "pinnedCommit": "<git rev-parse HEAD of the install>",
        "pinnedBranch": "<branch>",
        "completedAt": "<ISO8601>",
        "desktopVersion": "0.14.0"
      }
    3. Launch Hermes.exe — it now skips bootstrap, [boot] Resolving Hermes runtime → [boot] Hermes backend is ready in seconds.

    Why PR #43983 matters on Windows

    PR #43983's active-install.cjs heuristic ("trust an install whose hermes.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.)

  3. rod-nxtlevel commented on Jun 17, 2026

    @rod-nxtlevel

    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

    1. hermes update stashes 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 by b459bac02 (gitignoring the marker), but the damage was already done on this install.

    2. Electron binary can't be downloaded from GitHub — the bootstrap installer runs npm run pack in apps/desktop/, which calls electron-builder --dir. This fails because node_modules/electron/dist doesn't exist (GitHub download blocked/rejected):

    2026-06-17T18:48:09.665375Z ERROR hermes_bootstrap_lib::bootstrap: bootstrap FAILED stage=Some("desktop") error=exit code 1
    
      ⨯ The specified electronDist does not exist:
      /Users/.../node_modules/electron/dist. Please provide a valid path
      to the Electron zip file...
    

    The bootstrap's built-in mirror retry (npmmirror.com) also failed on this run — the ELECTRON_MIRROR mechanism in the bootstrap installer appears less robust than a direct npm install electron@40.10.2 with the mirror env var.

    This is partially addressed by d1ecebcbf which adds Electron mirror retry logic, but the bootstrap still failed 3x across multiple attempts.

    1. No .hermes-bootstrap-complete marker + failed bootstrap state = infinite retry loop — on every Desktop launch, Hermes-Setup detects 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 from Hermes-Setup retrying in the background.

    Evidence — Hermes-Setup running alongside Desktop

    $ pgrep -la Hermes-Setup
    74478 /Applications/Hermes.app/Contents/MacOS/Hermes-Setup
    
    # Meanwhile the Desktop IS running and connected:
    $ pgrep -la Hermes | grep -v Helper | grep -v Setup
    74429 Hermes
    
    # Bootstrap retries keep triggering:
    2026-06-17T20:48:22Z  INFO  Hermes installer starting mode=Install
    2026-06-17T20:52:49Z  INFO  Hermes installer starting mode=Install
    2026-06-17T20:53:03Z  INFO  Hermes installer starting mode=Install
    

    Workaround (manual recovery)

    The only way out is to:

    1. Install Electron manually via mirror:

      cd ~/.hermes/hermes-agent/apps/desktop
      ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/" npm install electron@40.10.2
    2. Rebuild Desktop:

      CSC_IDENTITY_AUTO_DISCOVERY=false hermes desktop --build-only
    3. Kill the rogue Hermes-Setup process

    4. Manually 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:

    Commit What it fixes
    b459bac02 Marker no longer stashed by hermes update
    d1ecebcbf Electron retries via mirror when GitHub download fails
    PR #43983 Heuristic: trust install if app.asar + venv exist, even without marker

    Remaining 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:

    1. No "skip / launch anyway" option in the GUI — the Desktop clearly works (connected to remote gateway, chat functional) while Hermes-Setup retries the installer in a second window.
    2. No retry limit — the bootstrap retries indefinitely (observed 3+ retries in one session, and it would continue across restarts).
    3. No detection of a functional existing installation — the Desktop should be able to detect that a valid 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P3Low — cosmetic, nice to havearea/install-updateInstaller, updater, packaging, wheels, doctorcomp/cliCLI entry point, hermes_cli/, setup wizardtype/bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions