Hermes Desktop guide

What Hermes Desktop is

Hermes Desktop is a graphical front end onto the same agent, not a separate product or a reduced clone. The documentation is explicit that it uses the same Hermes Agent core and settings. Practically that means:

• Chat with streaming responses, live tool activity, and file attachment by drag and drop.
• Tabs, windows, and panes for parallel work, plus an integrated terminal.
• A working-tree review pane for repositories, and a floating always-on-top bar for quick prompts.
• The same voice, memory, and skill capabilities as the other interfaces.

It is a different surface from the browser dashboard: the desktop app is an installed native application, while the dashboard is a browser interface served by a running Hermes Agent. Both are distinct from third-party web front ends such as Open WebUI, which connect over the OpenAI-compatible API server instead.

Availability and version status

• Operating systems: macOS, Windows, and Linux.
• On Linux, desktop support additionally requires build tooling to be installed before the installer runs.
• Architecture: the desktop installer is the documented recommended path on macOS and Windows in the Platform Support tiers; macOS on Intel is listed as unsupported for Hermes Agent generally.
• Checked release: v0.20.5, published 19 August 2026.

Under the hood it is an Electron shell with a native React chat surface, and it launches a headless hermes serve backend rather than embedding the terminal interface.

Install Hermes Desktop

Two documented routes:

If you have no Hermes Agent installation yet, download the desktop installer from the Nous Research desktop page and run it. First-run onboarding will offer provider setup, and you can defer that choice and configure a provider later.

If the CLI is already installed, build and launch the app from your existing installation:

Connect local or remote Hermes Agent

The app manages a local backend by default: it starts one on launch and shuts it down with the app. That is the right choice for a single-machine setup.

To point it at a runtime on another machine, use Settings → Gateways. Documented options are username and password, OAuth through Nous Portal, Hermes Cloud as a platform-managed backend, and SSH remotes.

For a username-and-password remote, the backend machine needs basic-auth values in its environment file and a served backend:

Set the credential variables in ~/.hermes/.env and restrict the file with chmod 600 ~/.hermes/.env before starting the server.

Choose model and profile

Model selection works the same way it does everywhere else, and profiles let one installation hold several isolated setups. Two practical notes:

• You can skip provider setup during onboarding and choose later without reinstalling.
• Switching the model mid-conversation means the next message re-reads the whole conversation at full input price. On a long chat that is a real cost, not a rounding error.

Use core interface areas

Documented shortcuts worth knowing on day one:

• Cmd/Ctrl+T — new session tab; Cmd/Ctrl+Shift+N — new window; Cmd/Ctrl+B — toggle the sidebar.
• Ctrl+` — integrated terminal, with output selectable into chat context.
• Cmd/Ctrl+G — working-tree review pane for repositories: branch status, diffs, and commits.
• Cmd/Ctrl+Shift+H — a chrome-free always-on-top bar for quick prompts.
• Cmd/Ctrl+K — command palette, which also reaches the memory graph and update controls.

Understand local data and configuration

The desktop app stores everything in HERMES_HOME — ~/.hermes on macOS and Linux, %LOCALAPPDATA%\hermes on Windows — using the same layout a CLI install uses. That is exactly why the two are interchangeable: install the CLI later and it picks up the same configuration and sessions.

Because the layout is shared, file locations, precedence between the configuration file and the environment file, validation, and reset are not repeated here. They belong to the configuration guide.

Update or remove the desktop app

Updates run in the background and are offered as a one-click update from the About panel or the command palette.

Removal is deliberately granular. From Settings → About → Danger zone, or from a terminal:

hermes uninstall removes the GUI and the agent while keeping your data, and hermes uninstall --full removes everything including the data directory. Back up ~/.hermes before running the full removal — it holds your credentials, memories, and skills.

Fix desktop problems

Desktop-specific checks, in order:

• Does hermes doctor pass in a terminal? If it fails there, the problem is the agent, not the app.
• Is the app managing a local backend, or pointed at a remote gateway that is down?
• For a remote backend, is authentication configured and reachable, and is it behind a VPN rather than an open port?
• On macOS, were permissions revoked by a rebuild under a different signing identity?

Anything beyond the interface layer — provider errors, configuration validation, tool failures — is diagnosed by component in desktop troubleshooting.