Connect Hermes Desktop to a Remote Server: The Guide

The most upvoted feature request in the entire Hermes Agent repository asks for one thing: install the desktop app as a thin client and connect it to a Hermes running somewhere else. Issue 38602, opened June 4, 2026, collected 68 reactions, and its own discussion contains a working answer that the official documentation does not yet cover: two environment variables, set before the app's first launch, switch Hermes Desktop into remote mode. This page walks through the mechanism, the exact steps, and the three traps recorded in the same thread.

Why the desktop app installs a second Hermes

By design, Hermes Desktop bootstraps a full local Hermes runtime on first launch whenever it finds no existing installation: the analysis in issue 38602 traces this to the app's startup code, which runs the install stages for Python, Node and the other dependencies automatically. For someone who already runs Hermes on a server, that default means a second brain on the laptop, with its own memory files and its own configuration, when all they wanted was a window into the one that already exists. Two related requests say the same thing from different angles: issue 36970, opened June 1, 2026, asked for first-class remote onboarding, and issue 37663 reported a Windows user poking through the app for a connect-to-my-VPS option.

Remote mode: the two variables

The working method, as documented inside issue 38602, is to set two environment variables on the laptop before the desktop app's first launch:

HERMES_DESKTOP_REMOTE_URL=https://your-remote-backend.example/hermes
HERMES_DESKTOP_REMOTE_TOKEN=your-session-token

With both present, the app resolves a remote backend configuration at startup and connects to it immediately, skipping the local install path entirely. The URL points at your server's Hermes backend, the process started by hermes serve. The token is the session credential for that backend.

What this means for you: the heavy part of Hermes, the gateway, the memory files, the skills, keeps living on a machine that stays on. The laptop carries only the window. Close the lid and the agent keeps working, because the agent was never on the laptop to begin with.

The three traps, recorded in the same thread

Issue 38602 lists the limitations plainly, and each one is worth reading before you start.

Trap one: the order matters. The variables must exist before the first launch. If the app starts once without them, it begins bootstrapping a local runtime on the spot.

Trap two: unsetting them wakes the installer. If the variables later disappear, the next launch attempts the local bootstrap again. Remote mode is a standing arrangement, so put the variables somewhere permanent, the system environment on Windows or the shell profile on macOS.

Trap three: the shell still installs. The desktop application itself, the Electron shell, installs normally. Remote mode skips the runtime underneath it, and there is no official client-only installer yet, which is exactly what the issue asks the project to add.

Where the tools run

One nuance for power users: in this arrangement, tool execution happens on the server. Issue 18715, open since May 2, 2026, asks for the hybrid version, a remote brain with tools running on the local machine, and describes why today's behaviour surprises people: the remote instance creates its own agent, so file operations and commands touch the server's disk. If your workflow needs the agent's hands on your laptop's files, that capability is still an open request.

The five-minute setup, in order

1. Have the remote end ready: a Hermes instance on an always-on server, with its backend reachable over HTTPS and its session token at hand.
2. Set both variables on the laptop: HERMES_DESKTOP_REMOTE_URL and HERMES_DESKTOP_REMOTE_TOKEN, in the system environment so they survive reboots.
3. Install and launch Hermes Desktop. With the variables present, the app connects to the remote backend and skips the local install.
4. Verify: the sessions, memory and skills you see are the server's. A fresh, empty agent means the app bootstrapped locally, and the variables arrived too late.
5. Keep the variables permanent. Removing them re-arms the local installer on the next launch.

The remote end can be any always-on Hermes server you control. On our managed Hermes Agent hosting the agent runs day and night on a dedicated EU server with its memory accumulating around the clock, and the 7-day free trial needs no card. For sizing the server itself, our Hermes Agent VPS hosting guide covers the practical floor.

Sources: Hermes Agent issues 38602 (68 reactions, including the remote mode workaround and its limitations), 36970, 37663 and 18715, all read on August 29, 2026.