Hermes Desktop: The CLI You Can See

Not a Separate Product

The most important thing to understand about the Hermes Desktop app is what it is not. It is not a stripped-down consumer version of Hermes. It is not a simplified interface that hides the power features. It is not a different product that happens to share a name.

The Desktop app is the same Hermes agent you use from the terminal, wrapped in a native application with a graphical interface. Same configuration files. Same API keys. Same sessions and conversation history. Same skills library. Same memory system. Same tool execution. If you configure a provider in the CLI, it is immediately available in the Desktop app. If you start a conversation in the Desktop and switch to the CLI, you can continue the same session in your terminal.

The Desktop app adds a layer on top of the agent -- a visual interface for things that are cumbersome in a terminal -- but it does not replace or duplicate the agent underneath. This distinction matters because it means learning the Desktop app is additive. Every skill or configuration pattern you already know from the CLI works identically in the Desktop.

The Technical Architecture

Understanding why the Desktop and CLI are identical underneath requires understanding how the Desktop app is built.

When you launch the Desktop app, it does two things: it starts a headless hermes serve backend process running locally on your machine (the same backend you can start manually from the terminal), and it opens an Electron application window that contains a React-based chat interface.

The Electron window communicates with the hermes serve process via JSON-RPC/WebSocket -- the same protocol any external program can use to connect to a Hermes gateway. The React interface is essentially a sophisticated client for the Hermes API, built directly into the app.

This architecture has several implications. The Desktop app installs the Hermes Agent runtime into ~/.hermes/ on first launch -- the same directory the CLI uses. It reads from and writes to the same configuration files. It shares the same process pool. When the Desktop app is closed, the backend process stops (unless you have configured it to run as a persistent service).

Installation

The Desktop app runs on all three major platforms. Download it from the official Hermes site and install using the standard mechanism for your platform.

On macOS, you get a standard .dmg file. Open it, drag the app to Applications, and launch it. The first launch installs the Hermes Agent runtime if it is not already present. If you already have Hermes installed via the CLI, the Desktop app finds the existing installation and uses it -- no duplication.

On Windows 10/11, the installer walks through a standard setup wizard. Windows has a few features that are not available compared to macOS and Linux, but the core functionality is fully supported. Check the Hermes platform support documentation for the current list of Windows-specific limitations.

On Linux, the .AppImage or .deb package installs and runs on distributions that use glibc and systemd. Ubuntu is the most tested distribution. WSL2 (Windows Subsystem for Linux) is also supported and behaves identically to native Linux.

First-Run Onboarding

When you launch the Desktop app for the first time, you are walked through a brief onboarding flow. It asks you to configure a provider and add an API key. You can skip this and enter the app immediately -- useful if you already have Hermes configured from the CLI and just want to start chatting. The Desktop app picks up your existing configuration automatically.

If you are setting up Hermes for the first time via the Desktop app (no prior CLI installation), the onboarding is the right starting point. Add at least one API key during onboarding, then come back to the Settings panel to configure additional providers, models, and preferences at your own pace.

After onboarding, you land in the main chat interface. The app is fully functional immediately -- you can start a conversation right away. The remaining lessons in this track cover the individual features of the interface in detail. This first lesson is just the foundation: what the app is, how it is built, and how to get it running.

When to Use the Desktop vs. the CLI

Both interfaces run the same agent, so the choice between them is about workflow, not capability. Here is a practical guide:

Use the Desktop app when:

• You are doing exploratory work and want to see tool outputs, file contents, and web pages rendered side by side with the conversation
• You want a GUI for managing providers, models, and skills without editing YAML
• You are working on a project and want the file browser to track what the agent is doing to your files in real time
• You prefer visual feedback over scrolling terminal output

Use the CLI when:

• You are already in a terminal and do not want to context-switch to a GUI
• You are running batch jobs or automated scripts that do not need a visual interface
• You are on a remote server via SSH where the Desktop app is not practical
• You are comfortable with terminal tools and prefer the composability of CLI arguments

Many developers use both regularly, switching between them based on the task. Short automated tasks go to the CLI. Exploratory and interactive work goes to the Desktop. The shared configuration and session history make the switch seamless.

Version Updates

The Desktop app includes an auto-update mechanism that checks for new versions and notifies you when one is available. Unlike the CLI (hermes update), the Desktop app manages its own update lifecycle through the system's native app update conventions. On macOS, this is Sparkle. On Windows, it is the WiX installer's update mechanism.

The Hermes Agent runtime inside ~/.hermes/ is updated independently from the Desktop application shell. You may see prompts to update the runtime even on an up-to-date Desktop app version. Keeping both updated ensures you have the latest features and security fixes in both the interface and the agent core.