Connect Hermes agents on several machines with Hermes Desktop

How does Hermes Desktop connect to several machines?

Hermes Desktop keeps a registry of named connections, one per Hermes backend, and lets you use the agents on all of them from one window. Each registered gateway opens its own backend connections on demand, and agents on one machine keep working in the background while you look at another.

The registry lives on the Settings → Gateways page. You can also reach it from the plug button at the right end of the sidebar profile rail ("Connect another Hermes gateway…") or by pressing Cmd/Ctrl+K and typing Gateways. There are four kinds of connection:

The app organizes everything as gateway, then profile, then sessions. A gateway is a machine or hosted backend, and profiles are the separate agents that live on it. This is different from running several gateways on one machine, which the docs cover under multi-profile gateways.

What do you need on the remote machine?

The remote machine needs Hermes installed and, for a Remote gateway connection, a running hermes serve backend that your desktop can reach. The desktop app attaches to that backend but does not start it. SSH connections are the exception: the app starts the dashboard over the tunnel when you first open an agent there.

For a Remote gateway, protect the backend with an auth provider:

• OAuth (Nous Portal) is the docs' choice for anything reachable beyond your own network, such as a VPS or public host. Register the dashboard with hermes dashboard register, then use "Sign in with Nous Research" in the app.
• Username and password is for a trusted LAN or a VPN such as Tailscale only. Never expose a password-protected backend directly to the internet.

The username and password setup on the remote machine looks like this:

SECRET=$(openssl rand -base64 32)
cat >> ~/.hermes/.env <<EOF
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$SECRET
EOF
chmod 600 ~/.hermes/.env

# Bind to the machine's Tailscale IP so only your tailnet can reach it
hermes serve --host <tailscale-ip> --port 9119

The stable secret keeps you signed in across backend restarts. Binding to anything other than loopback turns on the backend's auth gate. Keep hermes serve running under systemd, tmux or another process manager, and if you run it under systemd, give the unit EnvironmentFile=%h/.hermes/.env. If the remote machine also serves Telegram, Discord or other channels, its messaging gateway is a separate process that you start and keep running on its own.

How do you add a connection in Hermes Desktop?

Open Settings → Gateways, click Add connection, fill in the form, save, then click Test.

1. Pick the kind: Remote gateway, SSH or Hermes Cloud. Local is disabled because the app already manages one local entry, and Hermes Cloud sends you to the cloud sign-in flow at the top of the page.
2. Enter a Name. This is the device name shown everywhere the instance appears, such as "Homelab" or "VPS". It must be unique, ignoring case, and at most 64 characters.
3. For a Remote gateway, enter the Gateway URL of the hermes serve backend, for example http://homelab.lan:9119, and choose Session token or OAuth.
4. For SSH, enter the SSH host as user@host:22 (user and port are optional). Fill Hermes path only if the remote shell cannot find hermes.
5. Click Save connection, then Test, and wait for the "Reachable" message. The test checks both the HTTP and the WebSocket side, so a pass means chat will work.

You can edit a connection with the pencil button or remove it with the trash button. Removing a connection does not touch the instance itself. One connection is always marked Primary, which is the fallback for calls that do not name a gateway.

Why use an SSH connection for a VPS?

For a VPS, the SSH connection kind is usually the simplest safe choice. It uses the SSH key you already use for the server, the app opens the tunnel and starts the dashboard for you, and it adopts a dashboard token over that tunnel. You do not have to expose a hermes serve port to the internet yourself or manage a separate dashboard password.

SSH connections also stay quiet until you need them. They connect on demand the first time you open an agent there, and hovering over an SSH agent never opens a tunnel.

A few SSH details from the docs:

• If Test reports "Hermes is not installed on the remote host" even though it is, the remote's non-interactive shell does not have hermes on its PATH. Put the full path, such as /opt/hermes/bin/hermes, in the Hermes path field.
• If the server was reinstalled and its host key changed, SSH fails closed. Confirm the change is expected, run ssh-keygen -R <host>, then click Retry.
• On Windows, the app uses the built-in OpenSSH client and falls back to Git for Windows' ssh.exe. You can set another client with desktop.ssh_path in config.yaml.

How are agents on different machines named?

Every profile on every connected machine counts as an agent, and Hermes Desktop names them so they never get confused. When the same profile name exists on more than one gateway, the handle becomes @name-device. A research profile on the connection named Homelab appears as @research-homelab. A profile name that is unique across all gateways keeps its bare name.

Opening an agent connects to its own gateway. Its chats, sessions and memory stay on the machine that owns the profile, exactly as if you were using that machine directly. Switch gateways from the Sessions sidebar. The session list, messaging channels, cron jobs, settings, files and memory all follow the active gateway and profile. On the Capabilities page, the Configuring selector lets you change one machine's skills, toolsets and MCP servers without switching your current workspace.

Do agents on different machines delegate to each other automatically?

No. Direct bot mentions and delegation stay on the agent's own gateway by default. The docs explain why: crossing from one backend to another changes the filesystem, credentials, tools and trust context, so cross-gateway work should be an explicit bridge, not a side effect of sharing one Desktop window.

Sessions show one active gateway at a time for the same reason. Bot Mode can list agents from every gateway in one roster, but opening a bot still activates that bot's own gateway and profile. The kanban board is also single-host by design, so a board on your laptop does not dispatch work to your VPS.

How are connection tokens stored?

Remote gateway session tokens and OAuth tokens are stored in the desktop app's user-data directory as owner-only files (mode 0600). They are handled by the app's main process, and the interface and plugins never see the token bytes.

By default these tokens are not run through the operating-system keychain. If you want encryption at rest on top of the file permissions, turn on "Encrypt saved secrets with the OS keychain" in the gateway settings. It uses Keychain on macOS, DPAPI on Windows and the session keyring on Linux. The registry file, connections.json, holds only labels, URLs and hosts, and the plugin SDK's host.connections() returns labels and kinds but never token material.

On the remote side, remember that the backend reads and writes that machine's .env and can run agent commands. Treat its login like an SSH key.

How do you update every machine at once?

Use Update all instances on Settings → Gateways, which appears once you have more than one connection. It runs hermes update on every eligible connection in parallel. The local runtime updates through the app's own update flow, Remote and SSH machines update themselves, and Hermes Cloud instances are skipped because the platform manages their versions. Each machine reports its own result, so one unreachable server does not stop the rest.

How do you troubleshoot a connection?

Start with Test on the connection row, then check the most common causes:

• Connection test failed: check that hermes serve is running on the remote host, the port is open and the token is current.
• An agent shows but will not open: HTTP works but the WebSocket is blocked. A proxy, firewall or origin guard is likely blocking /api/ws.
• Connection refused or timing out: the backend is bound to 127.0.0.1, the default, or a firewall is blocking the port.
• Signed out on every restart: set HERMES_DASHBOARD_BASIC_AUTH_SECRET to a stable value.
• An SSH machine shows "connect-on-demand": this is expected until you open one of its agents.

FAQ

Sources

• Connecting Desktop to Many Hermes Instances
• Hermes Desktop (connecting to a remote backend)
• Running Many Gateways at Once
• Kanban: Multi-Agent Profile Collaboration