ISSUE DESCRIPTION Hermes Desktop 0.4.3 remote mode fails against working local Hermes…
- User
ISSUE DESCRIPTION
Hermes Desktop 0.4.3 remote mode fails against working local Hermes API server
Bug: Hermes Desktop 0.4.3 fails to connect reliably to existing local Hermes API server
Summary
Hermes Desktop 0.4.3 fails to work as a frontend for an already-running local Hermes Agent API server.
The Hermes Agent backend is installed separately under
/opt/hermes-agent, runs correctly with Python 3.12, exposes the API server on127.0.0.1:8642, and successfully handles OpenAI-compatible API requests viacurl.However, Hermes Desktop fails to connect or send messages in remote mode. It either reports that it cannot reach the server, returns
404: Not Found, or tries to spawn a removed/incorrect local Hermes installation under~/.hermes/hermes-agent.Environment
- OS: Ubuntu 24.04.3 LTS
- Kernel: Linux 6.17.0-14-generic x86_64
- Desktop: KDE/Plasma
- Hermes Agent version: 0.14.0
- Hermes Desktop version: 0.4.3
- Hermes Agent install path:
/opt/hermes-agent - Hermes config/home:
~/.hermes - Python used by working Hermes Agent: Python 3.12.3
- GPU: NVIDIA RTX 5060 Ti, 16 GB VRAM
- Model backend: Ollama
- Ollama model:
gemma4:e4b - Ollama API endpoint:
http://127.0.0.1:11434/v1 - Hermes API server:
http://127.0.0.1:8642
Working backend configuration
Hermes Agent works correctly from CLI/API with this model configuration:
model: default: gemma4:e4b provider: custom base_url: http://127.0.0.1:11434/v1 The Hermes API server is enabled: API_SERVER_ENABLED=true API_SERVER_HOST=127.0.0.1 API_SERVER_PORT=8642 API_SERVER_KEY=<redacted> The backend works correctly via curl: KEY="$(grep '^API_SERVER_KEY=' ~/.hermes/.env | cut -d= -f2- | tr -d '\"'\'' ')" curl -i http://127.0.0.1:8642/v1/models \ -H "Authorization: Bearer $KEY" Expected/actual result from curl: { "object": "list", "data": [ { "id": "hermes-agent", "object": "model", "owned_by": "hermes", "root": "hermes-agent" } ] } Chat completions also work: curl -sS http://127.0.0.1:8642/v1/chat/completions \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "hermes-agent", "messages": [ {"role": "user", "content": "Respond exactly: ok"} ] }' This returns a valid response from Hermes Agent, and Ollama confirms that the local model is loaded on GPU: gemma4:e4b 11 GB 100% GPU CONTEXT 65536 Problem in Hermes Desktop When using Hermes Desktop 0.4.3 and selecting: Connect to Remote Hermes with: URL: http://127.0.0.1:8642 API key: <API_SERVER_KEY> or: URL: http://127.0.0.1:8642/v1 API key: <API_SERVER_KEY> the GUI does not connect reliably. Observed GUI errors include: Could not reach Hermes at this URL. Check the URL and API key. and: Error: API server returned 404: 404: Not Found and: Error: API request failed: connect ECONNREFUSED 127.0.0.1:8642 Logs Hermes Desktop log includes: [CRON] remote list failed: HTTP 404 Error occurred in handler for 'send-message': Error: API server returned 404: 404: Not Found At one point, Hermes Desktop also attempted to spawn an old local Hermes installation that no longer exists: [MAIN UNCAUGHT] Error: spawn /home/patrick/.hermes/hermes-agent/venv/bin/python ENOENT spawnargs: [ '/home/patrick/.hermes/hermes-agent/hermes', 'gateway' ] This suggests that even after choosing remote mode, Hermes Desktop may still retain or use stale local-install state under ~/.hermes/hermes-agent. Route testing The local Hermes API server exposes these routes successfully: GET /health -> 200 OK GET /v1/health -> 200 OK GET /v1/models -> 200 OK POST /v1/chat/completions -> 200 OK But these routes return 404: GET /models -> 404 Not Found GET /api/health -> 404 Not Found This may indicate that Hermes Desktop remote mode expects routes that are not provided by the Hermes Agent OpenAI-compatible API server. Expected behavior Hermes Desktop remote mode should work with an existing Hermes Agent API server when provided: URL: http://127.0.0.1:8642 API key: API_SERVER_KEY or clearly document whether the required URL should be: http://127.0.0.1:8642 or: http://127.0.0.1:8642/v1 It should then list the exposed remote model: hermes-agent and send chat requests through the existing Hermes API server. Actual behavior Hermes Desktop does not list hermes-agent, fails validation, returns 404, or tries to spawn a stale local Hermes installation under: ~/.hermes/hermes-agent even though the remote Hermes API server is alive and working via curl. Why this appears to be a Hermes Desktop issue The backend works outside Hermes Desktop: curl /v1/models succeeds. curl /v1/chat/completions succeeds. Hermes Agent CLI works. Ollama backend works. GPU model loading works. The only failing component is Hermes Desktop remote frontend mode. Request Please clarify or fix Hermes Desktop remote mode behavior: Which URL format is expected for remote Hermes? http://host:8642 or http://host:8642/v1 Which endpoint does Hermes Desktop use to validate remote connectivity? Should remote mode depend on routes like /models, /api/health, /cron, or local gateway-management endpoints? Can Hermes Desktop avoid trying to spawn ~/.hermes/hermes-agent/... when the user explicitly chooses remote mode? Can stale local install state be ignored or reset when using remote mode? thanks!!! ## Interface No new interfaces are introduced. # ADDITIONAL ADVICE Since you are given a git repository, you can use git commands to simplify your work. For example, if you made a mistake and want to revert your changes, you can use `git checkout <file>` to restore the file to its original state. You can also reset all changes in the repository using `git reset --hard` command. Additionally, you can use `git stash` and `git stash pop` to temporarily save your changes and restore them later. Finally, you can see the changes that you've made (which will be submitted when you call `submit`) using `git status` or `git diff` commands. However you don't need to use `git add` or `git commit` before submitting your changes. In fact, `submit` only submits currently unstaged changes because it uses `git diff` to get the changes that need to be submitted. # CHECKLIST Before submitting your solution, please go over the following checklist and make sure you've done everything: - [ ] If an error was reported in the issue description, I have successfully reproduced it. - [ ] If an error was reported in the issue description, I have confirmed that my fix resolves the error. - [ ] I have thought about edge cases and made sure my fix handles them as well. - [ ] I have run existing tests in the repository that might have been affected by the change I made and confirmed that they pass. I want you to list every bullet from this checklist and write your reasoning for why you think you did it or didn't need to. Repository has been uploaded and your shell is currently at the repository root. Time to solve the issue! (Current directory: /hermes-desktop, current file: none) bash-$ Assistant
Now let's implement a normalization helper that strips trailing slashes and a trailing
/v1segment, and apply it consistently.Assistant
Now I'll edit lines 74-87 to add the normalizeApiBaseUrl helper and use it in resolveRemoteApiKey, and also update getApiUrl (lines ~31-42).
Assistant
Now update
getApiUrl()to usenormalizeApiBaseUrlfor remote mode.Assistant
There's a duplicate closing brace at line 41 now. Fix that.
Assistant
Still there's a duplicate
}at line 43. Remove it.Assistant
Now let's fix
testRemoteConnectionto also usenormalizeApiBaseUrlinstead ofstripTrailingSlashes.Assistant
Let's use the
replacespecial command instead, opening index.ts first.Assistant
Now let's find the
set-connection-confighandler location and normalize the URL before storing.Assistant
Extra duplicate
},\n );lines at 539-540. Remove them.Assistant
Good, that's clean now. Let's also fix the
test-remote-connectionhandler andstart-gatewayhandler to be defensive about remote-only mode (avoiding stale spawn).Assistant
Duplicate
return isGatewayRunning();at line 758-759. Fix.Assistant
Good, that's fixed now. Let's double check the whole set-connection-config section and the getApiUrl block for correctness by viewing the diff so far.
Assistant
This looks good. Now let's check compile / typecheck to catch any issues.
Assistant
Typecheck passes with no errors. Now let's run relevant existing tests.
Assistant
Let's run the test suite (or at least relevant test files) now.
Assistant
All existing tests pass. Now let's run the entire test suite to make sure nothing else broke.
Assistant
All 435 tests pass. Now let's write a quick reproduction test to confirm the fix behaves correctly for both URL formats.
Assistant
All variations now correctly normalize to a single
/v1/chat/completionspath, matching the exact issue scenario.Assistant
Good, no test depends on exact old behavior with
/v1suffix. Let's view that test file quickly to be safe.Assistant
These use
config.setConnectionConfigdirectly, not the IPC handler, so normalization at IPC layer doesn't affect these tests. All good. Let's re-run full test suite once more.Assistant
All 435 tests pass. Now let's run the typecheck once more and lint to be safe.
Assistant
Good, back to original. Let's redo the edits precisely.
Assistant
Now update
testRemoteConnectionagain.Assistant
hermes.ts is done correctly now. Let's redo the index.ts edits carefully, keeping formatting consistent with existing style (without running prettier on the whole file).
Assistant
Now the set-connection-config handler (with proper multi-line formatting for the ternary to satisfy prettier):
Assistant
There's a stray duplicate
},\n );at line 540-541.Assistant
Good, that's clean now. Now let's find and update the gateway handlers.
Assistant
Duplicate lines 762-763 again. Let's remove them.
Assistant
Now clean. Let's verify the diff, typecheck, and run tests again.
Assistant
This is a clean, minimal, focused diff. Now let's typecheck, lint (only warnings expected, none new), and run the full test suite.
Assistant
All warnings are pre-existing (already present before my changes) — no new lint issues introduced. Now full test suite:
Assistant
All 435 tests pass, and typecheck is clean. Let's double check with the mini repro script once more to confirm behavior end-to-end.
Assistant
The fix resolves the exact issue described. Let's do a final review of the complete diff before submitting.
Assistant
This diff is clean and minimal. Now going through the checklist:
Assistant
I've completed my analysis and fix. Let me go through the checklist:
Checklist review:
-
✅ Reproduced the reported error: I traced the code path in
src/main/hermes.tsand found thatgetApiUrl()only stripped trailing slashes from the user-supplied remote URL but not a trailing/v1segment. Since all API calls append/v1/chat/completionsor/healthto the base URL, a user enteringhttp://127.0.0.1:8642/v1(a very natural choice, since that's the OpenAI-SDK-style base URL format) producedhttp://127.0.0.1:8642/v1/v1/chat/completions— a 404, exactly matchingError: API server returned 404: 404: Not Foundfrom the issue. I confirmed this with a standalone reproduction script. I also found that thestart-gateway/gateway-statusIPC handlers inindex.tscalledstartGateway()/isGatewayRunning()unconditionally formode === "remote", which explains the stale~/.hermes/hermes-agent/venv/bin/pythonspawn attempt reported in the logs even though the user was in remote mode. -
✅ Confirmed the fix resolves it: Added
normalizeApiBaseUrl()which strips a trailing/v1(case-insensitive) plus trailing slashes, and applied it consistently ingetApiUrl(),testRemoteConnection(),resolveRemoteApiKey(), and when persisting the URL via theset-connection-configIPC handler. Verified via script thathttp://host:port,http://host:port/,http://host:port/v1, andhttp://host:port/v1/all now resolve to identical, correct/v1/chat/completionsand/healthURLs. Also madestart-gateway,stop-gateway, andgateway-statusIPC handlers no-ops (or remote health checks) in pure"remote"mode so a local gateway is never spawned/stopped when the user explicitly picked remote mode. -
✅ Edge cases considered: case-insensitive
/V1suffix, trailing slashes in any combination, empty-string URLs (guarded to avoid unnecessary regex work), backward compatibility with already-persisted configs (normalization happens at read-time ingetApiUrl/testRemoteConnectiontoo, not just at save-time), and SSH/local modes are untouched. -
✅ Ran existing tests: Full
vitestsuite (33 files / 435 tests) passes,tsctypecheck (node + web) passes with no errors, andeslinton touched files shows no new warnings (only pre-existing, unrelated warnings remain).
-
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.
Identical first prompt
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-27BCompare side by side →
Qwen/Qwen3.6-27BCompare side by side →
Qwen/Qwen3.6-27BCompare side by side →