Hermes Desktop remote gateway mode flaps back to local backend after successful remote readiness

[pinoymt]

Environment

• Windows desktop app
• Remote Hermes backend hosted on VPS over Tailscale
• Remote URL: http://:8642/v1

Summary
Hermes Desktop successfully reaches and validates the remote backend, but the app does not remain attached to it. After reporting the remote backend as ready, the desktop app restarts the connection and starts the local Windows backend instead. The UI then returns to the error screen:

• Hermes couldn't start
• Could not connect to Hermes gateway

Observed behavior
From desktop.log:

[hermes] [boot] Connecting to remote Hermes backend at http://xxxxx:8642/v1
[hermes] [boot] Remote Hermes backend is ready
[hermes] [boot] Restarting desktop connection
[hermes] [boot] Finding an open local port
[hermes] [boot] Starting Hermes backend via Hermes at C:\Users<redacted>\AppData\Local\hermes\hermes-agent
[hermes] Hermes Web UI → http://127.0.0.1:9120
[hermes] [boot] Hermes backend is ready. Finalizing desktop startup
[hermes] [boot] Restarting desktop connection
[hermes] Hermes backend exited (SIGTERM)
[hermes] [boot] Connecting to remote Hermes backend at http://:8642/v1
[hermes] [boot] Remote Hermes backend is ready

This repeats. The app appears to flap between:

• remote backend mode
• local gateway/backend mode

Expected behavior
If the remote backend is reachable and reports ready, Desktop should stay attached to the remote backend and proceed normally without restarting into local backend mode.

Actual behavior
Desktop confirms:

• Remote Hermes backend is ready

But then immediately:

• restarts desktop connection
• starts local backend on 127.0.0.1:9120
• shows gateway startup failure UI again

What was verified
Remote VPS side was tested and is working:

• API listener active on 0.0.0.0:8642
• GET /health returns 200 OK
• GET /v1/models works with auth
• Added compatibility for desktop-style probing:
  • accepts X-Hermes-Session-Token
  • serves GET /v1/api/status
• Windows client can reach the VPS over Tailscale
• Desktop logs explicitly show:
  • Connecting to remote Hermes backend at http://:8642/v1
  • Remote Hermes backend is ready

This strongly suggests the remaining failure is in the Desktop app’s startup/state logic rather than backend connectivity.

Related notes
Earlier issues were fixed during testing:

• initial ECONNREFUSED
• initial 404 on remote path
• local Windows Hermes install dependency issue (annotated_doc) was repaired

After those fixes, the current remaining issue is specifically the Desktop app switching away from the successful remote connection.

Potential cause
Desktop may be incorrectly:

• falling back to local gateway after remote readiness
• running both remote and local boot paths concurrently
• treating local gateway as mandatory even when remote backend is healthy
• resetting renderer/bootstrap state after successful remote handshake

User-visible symptom
Error screen:

• Hermes couldn't start
• The background gateway didn’t come up
• Could not connect to Hermes gateway

Even though the log shows:

• Remote Hermes backend is ready

[bxmarshall]

I can reproduce this on Windows with v0.15.1. Same behavior — backend says "Remote Hermes backend is ready" but renderer loops on repair/reset indefinitely. Quick workaround: opening the dashboard URL directly in a browser works fine, so the remote backend itself is healthy. Desktop log attached.

[hermes] [boot] Connecting to remote Hermes backend at http://X.X.X.X:8643
[hermes] [boot] Remote Hermes backend is ready
[hermes] [bootstrap] repair requested by renderer; clearing marker + latched failure
[hermes] [boot] Restarting desktop connection
[hermes] [boot] Connecting to remote Hermes backend at http://X.X.X.X:8643
[hermes] [boot] Remote Hermes backend is ready
[hermes] [bootstrap] reset requested by renderer; clearing latched failure

[qizhen2021]

Reproduced on v0.16.0 (2026.6.5) — Windows Desktop + Mac remote gateway over Tailscale

Setup:

• Windows 11 Desktop (Electron) → Mac mini gateway via Tailscale (http://100.72.93.50:8642)
• Mac gateway running v0.16.0, API server confirmed healthy on 0.0.0.0:8642
• dashboard.public_url set on Mac; desktop.json on Windows set to connectionMode: "remote"

Observed:
Desktop.log only shows local backend startup — no remote connection attempt is ever made:

[hermes] [boot] Starting Hermes backend via Hermes at C:\Users\...\hermes-agent
[hermes] Hermes Web UI → http://127.0.0.1:9120
[hermes] [boot] Hermes backend is ready. Finalizing desktop startup

This repeats on every launch. The "远程网关" (Remote Gateway) UI shows the URL but reports "暂时无法访问此网关".

Verified externally:

• curl http://100.72.93.50:8642/health → {"status":"ok","platform":"hermes-agent","version":"0.16.0"} ✅
• curl http://100.72.93.50:8642/v1/models → valid response ✅
• Mac gateway logs show zero incoming connections from the Windows machine
• Tested with Clash Verge proxy fully disabled + --no-proxy-server flag — same result

Additional data points:

• desktop.json with connectionMode: "remote" is not overwritten by the app on startup (file persists), but appears to be ignored
• web.backend in config.yaml is also ignored
• The GUI "保存并重连" button does not trigger a remote connection attempt
• No authentication configured on the Mac gateway (basic_auth fields empty)

Conclusion: The Desktop Electron app never reads desktop.json's connectionMode at boot. It always launches a local backend regardless of the remote gateway UI setting. This appears to be a missing integration between the GUI toggle and the actual boot logic.

Workaround: Access the Mac's Hermes directly via browser at http://100.72.93.50:9120 — works perfectly.

[seigi-kbd]

Confirming this on Windows → Linux over plain LAN (not Tailscale), so the flap-to-local isn't transport-specific. Both client and gateway are on the latest main (commit 6b76284c7). Adding the server-side gateway logs the original report couldn't capture — they pin the failure on the desktop client's boot handshake rather than backend connectivity.

Setup

• Desktop (client): Windows, latest main, packaged Electron
• Gateway (remote): Ubuntu 24.04, latest main, hermes dashboard --host 0.0.0.0 --port 9119, dashboard Basic auth (LAN)
• Same Connecting to remote backend → Remote Hermes backend is ready → Restarting desktop connection → Starting Hermes backend (local) → SIGTERM → … flap as the OP.

1. The WS is actually accepted server-side, and Basic-auth ws-tickets are minted (so on current builds this is not the always-4403 of #38412 — the ticket path passes admission):

dashboard-auth.log: {"event":"ws_ticket_minted","provider":"basic","user_id":"<user>","ip":"192.168.0.32"}
agent.log: tui_gateway.ws: ws accepted peer=192.168.0.32:53648
agent.log: tui_gateway.ws: ws closed peer=192.168.0.32:53648 reason=client_disconnect(code=1006) messages=420 ...

Sessions even stay up for tens of minutes when the boot handshake happens to win the race (one ran 51 min / 420 messages).

2. Every close is client-initiated — the gateway never closes the socket:

ws closed ... reason=client_disconnect(code=1001)
ws closed ... reason=client_disconnect(code=1006)
ws closed ... reason=client_disconnect(code=1012)

3. The desktop renderer times out its own boot handshake, then flaps to local:

[renderer] Error invoking remote method 'hermes:api': Error: Timed out connecting to Hermes backend after 15000ms
[boot] Restarting desktop connection
[boot] Starting Hermes backend via existing Hermes CLI ... → HERMES_DASHBOARD_READY port=49459   (local fallback)

4. It's a client give-up, not server slowness. On one disconnect the gateway had already computed the response but the client was already gone:

tui_gateway.ws: ws response send failed peer=192.168.0.32 id=10 method=setup.runtime_check
tui_gateway.ws: ws closed ... reason=send_failed_after_response

And setup.runtime_check → resolve_runtime_provider() measures ~0.05 s on the gateway, so the 15 s hermes:api timeout is not backend latency.

5. Also hit the "no session token is saved" boot loop on the same setup:

[boot] Desktop boot failed: Remote Hermes gateway is selected, but no session token is saved. Open Settings → Gateway and save a token, or switch back to Local.

(matches the safeStorage token-validator discussion in #38412.)

Net: server, network, WS admission, and Basic auth are all healthy; the remaining failure is the desktop's 15 s hermes:api boot-handshake timeout + the spawn-local → SIGTERM → connect-remote boot churn, exactly as the OP suspected. Still reproducible on latest main. Happy to capture a full tui_gateway.ws trace for a single connect attempt if that would help.

[cesto77]

Reproducing this on Windows 11 (Hermes Desktop 0.15.1) → Linux server (192.168.100.252) with hermes dashboard --host 0.0.0.0 --port 9119 --no-open --insecure running on the server side. Same "Remote Hermes backend is ready" then "Cached remote Hermes backend failed liveness probe; dropping stale connection." loop, then the dialog switches to "Could not connect to Hermes gateway" and the user is stuck.

What I see in desktop.log (timestamps trimmed):

[hermes] HERMES_DASHBOARD_READY port=65173
[hermes] [boot] Hermes backend is ready. Finalizing desktop startup
[hermes] Hermes backend exited (SIGTERM)
[hermes] [boot] Connecting to remote Hermes backend at http://192.168.100.252:9119
[hermes] [boot] Remote Hermes backend is ready
[hermes] Cached remote Hermes backend failed liveness probe; dropping stale connection.
[hermes] [boot] Desktop boot failed: Hermes backend did not become ready: connect ECONNREFUSED 192.168.100.252:9119

(I did see the local-backend SIGTERM → remote-connect path trigger — looks like the desktop's local backend is being killed even when remote mode is configured, then the remote one can't be reached reliably.)

On the server side, the remote hermes dashboard is answering 200 OK on / and 127.0.0.1:9119 is reachable from the LAN, but /api/auth/ws-ticket and /api/ws both return 401 Unauthorized to the desktop client (and to a manual curl POST from the same Windows box, so it's not CORS). I think the desktop's WS probe and the OAuth-style ticket mint are doing a session-token roundtrip that only works when the local subprocess mints the token and the SPA reads it back via the injected __HERMES_SESSION_TOKEN__ — which we never see over the wire in remote mode.

Constraints / what rules out workarounds for me:

• I will not run any Hermes backend on the Windows box (memory, skills, and Telegram bot all live on the Linux server; the desktop is a thin client).
• The server is on a private LAN, no public hostname / no TLS reverse proxy available.

Anyone else in the same boat, or is there a documented sequence to put a hermes dashboard into a state where a packaged Electron remote-client can mint a WS ticket without spawning the local backend? Happy to capture more logs / try config options if it helps narrow this down. Tracking also #38115, #38412, #40442, #44337.

[Paddypaletti]

Same issue on Windows 11 with Hostinger VPS setup.