Skip to content
TheChatArchiveThe Chat Archive
Claudeclaude-sonnet-5· anthropicHugging Face ibragim-bad/swe_rebench_07_2026_trajectories

ISSUE DESCRIPTION Hermes Desktop 0.4.3 remote mode fails against working local Hermes…

  1. 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 on 127.0.0.1:8642, and successfully handles OpenAI-compatible API requests via curl.

    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-$
    
  2. Claude Assistant

    Now let's fix the "set-env" handler block (lines 417-425):

  3. Claude Assistant

    Now fix the "set-model-config" restart block:

  4. Claude Assistant

    There's an extra stray } at line 509 now. Let me fix that.

  5. Claude Assistant

    Now that block looks good. Let's fix start-gateway (line ~726 originally, now shifted) and stop-gateway, and the one at ~760-761.

  6. Claude Assistant

    Now edit directly with line ranges.

  7. Claude Assistant

    Now fix "set-platform-enabled" restart guard:

  8. Claude 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.

  9. Claude Assistant

    Now let's add a normalizeRemoteUrl helper and use it consistently.

  10. Claude Assistant

    No hidden characters, good. Let's use edit with line ranges directly instead.

  11. Claude Assistant

    Now let's find and fix stripTrailingSlashes usage elsewhere in the file (testRemoteConnection) since we removed the helper function.

  12. Claude 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.

  13. Claude Assistant

    Good, same pattern; normalization handled in main process is sufficient. Now let's check models.ts and default-models to see if hermes-agent custom provider config is default for remote mode setups, and check the getModelConfig for remote scenario used in chat payload.

  14. Claude Assistant

    That's fine already. Now let's check the whole repo compiles/lints. Let's run TypeScript build/lint.

  15. Claude Assistant

    No type errors. Now let's run tests related to hermes.ts / cronjobs / index.

  16. Claude Assistant

    Let's run the full test suite to check nothing broke.

  17. Claude 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.

  18. Claude Assistant

    That's just a static consistency check, already passing. Now let's write a temporary reproduction script for normalizeRemoteUrl and the gateway guard logic.

  19. Claude Assistant

    Now let's test the gateway-guard logic in index.ts to confirm remote mode doesn't spawn a local process.

  20. Claude Assistant

    Good, doesn't test normalization behavior. Fine to leave storage as-is (raw). Now let's view the final diff summary.

  21. Claude Assistant

    This looks clean. Let's run the full test suite one more time and lint to be safe.

  22. Claude 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).

  23. Claude 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).

  24. Claude Assistant

    Let's also check settings.ts's remoteUrlHint for similar clarity update.

  25. Claude Assistant

    That hint already correctly documents /health and /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.

  26. Claude Assistant

    All 435 tests pass and no type errors. Let's do a final review of the full diff.

  27. Claude Assistant

    This all looks correct and complete. Let's go through the checklist.

  28. Claude 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:

      1. The 404: Not Found errors — caused by getApiUrl() not stripping a trailing /v1 from the user-entered remote URL. When a user enters http://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 mocking getConnectionConfig() to return a /v1-suffixed URL.
      2. The spawn ... ENOENT stale-local-install error — caused by several IPC handlers (set-env, set-model-config, set-platform-enabled, start-gateway) calling restartGateway()/startGateway() (which spawn()s HERMES_PYTHON under local HERMES_HOME) whenever isGatewayRunning() returned true — but isGatewayRunning() only checked ssh mode, not pure remote mode, and reads a local gateway.pid file that can be stale/reused from a previous local install.
    • [x] Confirmed the fix resolves the errors:

      • Added normalizeRemoteUrl() (strips trailing slashes and a trailing /v1, case-insensitively) and used it consistently in getApiUrl(), testRemoteConnection(), and resolveRemoteApiKey() — verified via temp test that both URL forms now normalize identically.
      • Added !isRemoteOnlyMode() guards to every gateway start/stop/restart/status code path in index.ts so a pure remote HTTP connection never attempts to spawn a local Python gateway process, regardless of stale local state.
    • [x] Edge cases considered: Handled URLs with/without trailing slash and with/without /v1 suffix; 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 ran tsc --noEmit (no errors) and eslint (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.

Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.