Desktop: add first-class remote-client onboarding for existing Hermes instances

[hermes-jeffrolc]

Feature Description

Add first-class remote-client onboarding to Hermes Desktop so a user can install the native app and connect it to an existing Hermes dashboard/TUI/API backend without bootstrapping a second local Hermes install.

Motivation

The current macOS Desktop installer flow appears local-first: launching the downloaded DMG shows a setup/bootstrap screen with an "Install Hermes" action. For users who already run Hermes on a server or service machine and only want a desktop client, this is confusing and makes remote mode feel unsupported even though the desktop code can connect to a remote backend when configured manually.

This matters for multi-device users who want:

• Hermes running as one durable gateway/backend on a home server or service Mac.
• A native desktop client on a laptop/workstation.
• No duplicate local Hermes install, duplicate config, or accidental local bootstrap.

Proposed Solution

Add a visible Desktop startup path such as:

1. "Use existing Hermes instance" / "Connect to remote Hermes"
2. Prompt for:
   • Dashboard/backend URL
   • Session token/API token or pairing code
3. Validate:
   • GET /api/status or equivalent health endpoint
   • WebSocket /api/ws connectivity when TUI/chat is enabled
4. Persist the connection in Desktop app settings/keychain.
5. If remote validation fails, show actionable errors instead of falling back to local install/repair.

A pairing flow would be even better:

• Desktop shows a pairing code.
• Existing Hermes gateway/dashboard approves it.
• Desktop receives the correct URL/token securely.

Expected UX

The user should be able to download the native Desktop app, open it, choose "Connect to existing Hermes", enter or pair with their remote Hermes endpoint, and start using the desktop client.

Current Workaround

Remote mode appears possible through environment variables such as HERMES_DESKTOP_REMOTE_URL and HERMES_DESKTOP_REMOTE_TOKEN, but that is not discoverable or appropriate for normal users installing from a DMG.

Alternatives Considered

• Use the web dashboard directly: works, but loses native desktop app affordances.
• Run a second local Hermes install: not desired for users who already operate a central gateway/backend.
• Manually launch the app with environment variables: workable for operators, not a product-quality onboarding path.

[hermes-jeffrolc]

Related: #18715 covers split-runtime/local-tool execution for remote Hermes. This issue is narrower: Desktop install/onboarding should expose a supported "connect to existing Hermes" path instead of forcing/discovering local bootstrap.

[oddm643]

Great write up. Exactly what’s needed, yes. +1 thanks guys!

[konsisumer]

This issue appears to describe the same problem as #37663, #37876, #38519, #38602. Maintainer might want to consolidate or pick one as canonical.

[randomsnowflake]

Temporary remote-only macOS workaround, without clicking "Install Hermes":

What worked was running the Electron desktop shell from a local hermes-agent source checkout and pointing it at my existing remote hermes dashboard through an SSH tunnel.

Full steps

1. Clone Hermes Agent locally

Pick any local folder. For example:

mkdir -p ~/Code
cd ~/Code
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

2. Install desktop dependencies

From the repo root:

cd ~/Code/hermes-agent
npm install

3. Make sure the remote Hermes dashboard is running

On your server/VPS, you need a hermes dashboard process, not just the gateway.

For example:

hermes dashboard --no-open --host 127.0.0.1 --port 9119

Or run it through systemd/tmux/whatever you use.

4. Open an SSH tunnel from your Mac

On your Mac:

ssh -fN \
  -o ExitOnForwardFailure=yes \
  -L 9119:127.0.0.1:9119 \
  -L 8642:127.0.0.1:8642 \
  user@your-server

Verify:

curl -fsS http://127.0.0.1:9119/api/status

You should see JSON from your remote Hermes install.

5. Start the Desktop renderer

Terminal 1:

cd ~/Code/hermes-agent/apps/desktop
npm run dev:renderer

Leave it running.

6. Launch Electron against the remote backend

Terminal 2:

cd ~/Code/hermes-agent/apps/desktop

export HERMES_DESKTOP_REMOTE_URL=http://127.0.0.1:9119
export HERMES_DESKTOP_DEV_SERVER=http://127.0.0.1:5174
npm run dev:electron

If your build expects a dashboard session token, also set:

export HERMES_DESKTOP_REMOTE_TOKEN="$(ssh user@your-server 'grep HERMES_DASHBOARD_SESSION_TOKEN ~/.hermes/dashboard.env | cut -d= -f2')"

So the full token-based launch becomes:

cd ~/Code/hermes-agent/apps/desktop

export HERMES_DESKTOP_REMOTE_URL=http://127.0.0.1:9119
export HERMES_DESKTOP_REMOTE_TOKEN="$(ssh user@your-server 'grep HERMES_DASHBOARD_SESSION_TOKEN ~/.hermes/dashboard.env | cut -d= -f2')"
export HERMES_DESKTOP_DEV_SERVER=http://127.0.0.1:5174

npm run dev:electron

Expected log lines:

[hermes] [boot] Connecting to remote Hermes backend at http://127.0.0.1:9119
[hermes] [boot] Remote Hermes backend is ready

This avoids installing a second local Hermes Agent and uses the existing server-side instance. It is obviously not a good end-user flow, but it unblocks remote-only users until the macOS installer has a first-class "connect to existing Hermes" onboarding path.

[deyil]

I’m hitting this exact UX problem on macOS with a real remote-client setup.

Setup:

• Hermes backend/dashboard runs on a headless Mac mini.
• Hermes dashboard is installed as a macOS system LaunchDaemon and starts before user login.
• Dashboard listens only on 127.0.0.1:9119 for safety.
• The iMac runs only Hermes Desktop as a native client.
• Access path is an SSH/Tailscale tunnel:

iMac 127.0.0.1:9120 -> Mac mini 127.0.0.1:9119

I manually wrote the Desktop connection config on the iMac:

{
  "mode": "remote",
  "remote": {
    "url": "http://127.0.0.1:9120",
    "authMode": "token",
    "token": {
      "encoding": "plain",
      "value": "<redacted>"
    }
  },
  "profiles": {}
}

The remote backend is reachable through the tunnel, and the config exists, but when launching Hermes Desktop for the first time, the app still shows only the initial “Install Hermes” screen.

From a user perspective this is confusing because the goal is not to install/run a second Hermes backend locally, but to use the native Desktop app as a client for an existing Hermes instance.

Expected UX:

• First launch should offer:
  • Install Hermes locally
  • Connect to existing Hermes instance
• The remote path should allow entering:
  • backend URL
  • token/pairing code
• Ideally it should validate /api/status and WebSocket connectivity.
• If remote config already exists in connection.json, the app should either use it or clearly explain why local bootstrap is still required.

This would make the documented Remote Gateway mode much more discoverable and avoid the impression that remote Desktop mode is unsupported.

[konsisumer]

These issues look like facets of one underlying problem: #36970, #37713, #37876.

They were grouped by a semantic pass as different symptoms of one underlying problem in comp/desktop. A single coordinated fix may resolve them together — flagging for visibility; no action has been taken on the individual issues.

Automated root-cause grouping. Reply to correct if these are unrelated.