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 fix the "set-env" handler block (lines 417-425):
Assistant
Now fix the "set-model-config" restart block:
Assistant
There's an extra stray
}at line 509 now. Let me fix that.Assistant
Now that block looks good. Let's fix
start-gateway(line ~726 originally, now shifted) andstop-gateway, and the one at ~760-761.Assistant
Now edit directly with line ranges.
Assistant
Now fix "set-platform-enabled" restart guard:
Assistant
Now let's check line 612-613 for the send-message handler (already checks
!isRemoteMode(), that's fine since it covers both remote and ssh). Let's verify.Assistant
Now let's add a
normalizeRemoteUrlhelper and use it consistently.Assistant
No hidden characters, good. Let's use
editwith line ranges directly instead.Assistant
Now let's find and fix
stripTrailingSlashesusage elsewhere in the file (testRemoteConnection) since we removed the helper function.Assistant
That's fine — only triggered when the user visits Schedules screen. Not a big deal. Now let's check the connection setup UI (Settings/Providers -> "Connect to Remote Hermes") for the URL field and how it validates/tests connection.
Assistant
Good, same pattern; normalization handled in main process is sufficient. Now let's check
models.tsand default-models to see ifhermes-agentcustom provider config is default for remote mode setups, and check thegetModelConfigfor remote scenario used in chat payload.Assistant
That's fine already. Now let's check the whole repo compiles/lints. Let's run TypeScript build/lint.
Assistant
No type errors. Now let's run tests related to hermes.ts / cronjobs / index.
Assistant
Let's run the full test suite to check nothing broke.
Assistant
All 435 tests pass. Now let's write a quick reproduction test script to confirm the URL normalization and gateway-guard fixes work as intended.
Assistant
That's just a static consistency check, already passing. Now let's write a temporary reproduction script for
normalizeRemoteUrland the gateway guard logic.Assistant
Now let's test the gateway-guard logic in index.ts to confirm remote mode doesn't spawn a local process.
Assistant
Good, doesn't test normalization behavior. Fine to leave storage as-is (raw). Now let's view the final diff summary.
Assistant
This looks clean. Let's run the full test suite one more time and lint to be safe.
Assistant
Only pre-existing prettier warnings unrelated to my change (not errors). All tests pass. Let's double check these warnings existed prior to my edits (not introduced by me).
Assistant
Confirmed — identical pre-existing warnings, no new issues introduced. Now let's also check documentation for connection setup to see if we should clarify URL format (as issue requests documentation clarity too).
Assistant
Let's also check settings.ts's remoteUrlHint for similar clarity update.
Assistant
That hint already correctly documents
/healthand/v1/chat/completions— good, no change needed there. Now let's run the full test suite once more and typecheck to confirm everything is fine.Assistant
All 435 tests pass and no type errors. Let's do a final review of the full diff.
Assistant
This all looks correct and complete. Let's go through the checklist.
Assistant
I've completed my analysis and fix. Let me go through the checklist:
Checklist review:
-
[x] Reproduced the reported error: I traced two concrete root causes from the issue:
- The
404: Not Founderrors — caused bygetApiUrl()not stripping a trailing/v1from the user-entered remote URL. When a user entershttp://127.0.0.1:8642/v1(as literally suggested as an option in the issue), the code builds${base}/v1/chat/completions→http://127.0.0.1:8642/v1/v1/chat/completions, which 404s. I verified this with a temporary vitest script mockinggetConnectionConfig()to return a/v1-suffixed URL. - The
spawn ... ENOENTstale-local-install error — caused by several IPC handlers (set-env,set-model-config,set-platform-enabled,start-gateway) callingrestartGateway()/startGateway()(whichspawn()sHERMES_PYTHONunder localHERMES_HOME) wheneverisGatewayRunning()returned true — butisGatewayRunning()only checkedsshmode, not pureremotemode, and reads a localgateway.pidfile that can be stale/reused from a previous local install.
- The
-
[x] Confirmed the fix resolves the errors:
- Added
normalizeRemoteUrl()(strips trailing slashes and a trailing/v1, case-insensitively) and used it consistently ingetApiUrl(),testRemoteConnection(), andresolveRemoteApiKey()— verified via temp test that both URL forms now normalize identically. - Added
!isRemoteOnlyMode()guards to every gateway start/stop/restart/status code path inindex.tsso a pure remote HTTP connection never attempts to spawn a local Python gateway process, regardless of stale local state.
- Added
-
[x] Edge cases considered: Handled URLs with/without trailing slash and with/without
/v1suffix; guarded all gateway-touching IPC handlers (not just the one directly implicated) since any could trigger a spurious local spawn via a stale PID file; left local-mode and SSH-mode behavior completely untouched; also improved the "Connect to Remote Hermes" hint text to clarify that both URL forms are accepted. -
[x] Ran existing tests: Full suite (
npx vitest run) — 435/435 tests pass across 33 files. Also rantsc --noEmit(no errors) andeslint(no new warnings vs. baseline).
No test files were modified — only a temporary throwaway test script was used for verification and then deleted before submission.
-
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 →