How to Use Hermes Desktop Like a Boss: Everything You Need to Know About the Hermes Agent App

I’ve been using Hermes Agent for months. CLI chat, the TUI, Telegram gateway, cron jobs, the whole stack. When Hermes Desktop first showed up, I figured it was just a web dashboard wrapped in an Electron shell, something I’d open once, nod at, and go back to my terminal.

I was wrong.

Hermes Desktop is the same agent in a purpose-built native GUI. Same config, same API keys, same sessions, same skills, same memory. It runs on macOS, Windows, and Linux. You can start a session on Desktop, walk away, and pick it up on the CLI from a different machine. The official docs say it’s the recommended install path, and after a few weeks of using it daily, I get why.

Here is the full tour: what it does, how to install it, every feature worth knowing about, and when you’d pick Desktop over the CLI or TUI.

What Hermes Desktop Actually Is

Hermes Desktop is a native Electron app that wraps the full Hermes Agent runtime. It’s not a separate product, not a “desktop app” that talks to a cloud service, and definitely not a cut-down version. It runs the same agent you get from hermes chat or hermes --tui, with the same config file, the same session database, the same installed skills, and the same memory.

The package that ships from the download page is just the Electron shell. On first launch, it provisions the full agent runtime into your Hermes data directory, the same ~/.hermes (or %USERPROFILE%\\.hermes on Windows) that a CLI install uses. Everything is interchangeable.

Hermes has several frontends that all talk to the same agent:

• Desktop App: the native GUI covered on this page
• CLI (hermes): prompt-toolkit terminal interface
• TUI (hermes --tui): modern React terminal UI with overlays
• Web Dashboard (hermes dashboard): browser admin panel with an embedded chat tab
• Messaging Gateway: Telegram, Discord, Slack, and 15+ other platforms

They all share state. A session you start in Desktop shows up in hermes sessions list on the CLI. A session you start on Telegram keeps going if you pick it up in Desktop. You don’t have to pick one. Pick whichever fits the moment. (My full Hermes Agent review covers what the agent itself can do; this guide is about the Desktop surface.)

How to Install Hermes Desktop

There are two paths depending on where you’re starting from.

Fresh install (no Hermes yet)

Download the prebuilt installer from the Hermes Desktop download page. Pick your platform:

• macOS: DMG installer
• Windows: NSIS/MSI .exe installer
• Linux: AppImage, deb, or rpm

The first launch provisions Python (via uv), Node.js, ripgrep, ffmpeg, and the full agent runtime automatically. You don’t need to install anything beforehand.

Add Desktop to an existing Hermes install

If you already have the Hermes CLI, it’s one command:

hermes desktop

That builds the Electron app from your current source install and launches it. It uses your existing config, keys, sessions, and skills. Nothing extra to configure. (If you’re looking for a deeper Hermes workflow, wiring it to Obsidian and NotebookLM for long-term memory, I covered that here.)

The hermes desktop command has a few useful flags:

If you’re on Windows and want a more familiar install experience, the desktop installer .exe handles everything under the hood and shares the same %LOCALAPPDATA%\\hermes data directory with any CLI install you already have. They coexist cleanly.

First Launch and Onboarding

The first time you open Hermes Desktop, it shows a startup overlay that walks you through picking a provider and model. If you’re not ready to choose, there’s a “Choose provider later” option that gets you into the app immediately.

Behind the scenes, that first boot is installing the Hermes Agent runtime into your Hermes home directory. If something goes wrong, the app surfaces recovery options: retry, repair install, or switch to a local gateway. The boot logs live at HERMES_HOME/logs/desktop.log, and you can tail them from the CLI with:

hermes logs gui -f

The Chat Experience

Chat is the center of the app, and it’s where Desktop shines compared to the terminal.

Streaming responses with live tool activity. When Hermes runs a tool, reading a file, searching the web, or running a command, you see the tool call appear in real time with a structured summary. You don’t have to imagine what the agent is doing; you watch it work.

Side-by-side preview rail. The right panel renders web pages, files, and tool outputs while you keep chatting. If the agent edits a file, you can preview it without leaving the chat. If it opens a web page, the rendered page shows up alongside the conversation.

Drag and drop files. Drop a file into the chat area to attach it to your next message. No need to type paths or copy-paste content.

Composer history and queue editing. Press up/down arrow keys in the empty composer to cycle through recent prompts. Edit messages you’ve queued up before they’re sent. Useful when you want to tweak a prompt before it goes out.

The status bar along the bottom shows live session state. There’s an inline model picker so you can switch models on the fly without opening settings. There’s also a per-session YOLO toggle. Flip it on if you want Hermes to skip dangerous-command prompts for that session. Know what you’re turning off before you use it.

File Browser

The file browser lets you explore and preview the working directory without leaving the app. It’s useful when you’re following along as the agent reads, writes, and edits files, and you can see what changed in real time.

Set the initial project directory when you launch:

hermes desktop --cwd /path/to/your/project

Or set the HERMES_DESKTOP_CWD environment variable.

Voice Mode

Hermes Desktop supports the same voice mode available in the CLI and TUI. You can talk to Hermes and hear it back. On macOS, the OS prompts for microphone access the first time you use it.

Configure speech-to-text and text-to-speech providers in Settings. You’ll need the voice extras installed if you want local speech-to-text:

# From the Hermes install directory
cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"

Settings and Configuration

One of the biggest advantages of Desktop over the CLI is having a real settings UI instead of editing YAML files. Here is what you can configure without ever touching a terminal.

Providers. The providers panel shows every supported inference provider with an accounts-style UX. Sign in with OAuth for providers that support it: Nous Portal, xAI Grok, MiniMax, Google Gemini. The app handles the browser sign-in flow for you. API keys go in through a paste interface.

Model settings. Pick your main provider and model from the full catalog, the same one the CLI uses, not a curated subset. Configure auxiliary models for specific tasks: vision analysis, web extraction, context compression, title generation, MCP tool routing, and skill curation.

Tools and Keys. Manage API keys for individual tools in one place. The app also exposes tool-backend install steps. You can run a post-setup installer directly from the GUI instead of dropping to a terminal.

MCP servers. Add, edit, and remove stdio and HTTP MCP servers from a form interface. No JSON to hand-edit. Reload MCP tools after making changes.

Gateway Connection. Switch between local and remote gateway. Set up per-profile remote hosts. Sign in with your remote backend’s auth provider.

Appearance. Light, dark, or system mode. Switch between “Product” view (clean, human-friendly tool summaries) and “Technical” view (raw tool args and results). Choose accent themes.

Safety. Configure YOLO mode and dangerous-command approval settings.

Management Panes

Beyond chat and settings, Desktop surfaces several management interfaces that usually require CLI commands:

• Skills: browse installed skills, search the Skills Hub, install new ones, manage your collection
• Cron: view scheduled jobs, manage their status
• Profiles: switch between Hermes profiles. Run sessions across multiple profiles simultaneously, and reference a session in another profile with cross-profile @session links
• Messaging: set up gateway channels for Telegram, Discord, Slack, WhatsApp, and others
• Agents and Command Center: orchestration surfaces for multi-agent work

Keyboard and Navigation

Desktop is designed to be navigable from the keyboard:

• Command palette: Press Cmd+K (Ctrl+K on Windows/Linux) to jump to any action or view
• Rebindable shortcuts: A shortcuts panel in Settings lets you remap every keyboard shortcut
• Custom zoom: Half-step zoom increments for fine control over text size
• Language switcher: Change the interface language in-app, including Simplified Chinese (zh-Hans)

Connecting to a Remote Backend

By default, Desktop starts and manages its own local backend. The app bundles everything. But you can also point it at a Hermes backend running on another machine.

“Remote backend” means a hermes dashboard server running on the remote machine. It needs to be up and reachable; Desktop doesn’t start it for you.

On the remote machine:

# Set credentials
cat >> ~/.hermes/.env <<'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF

# Start the dashboard bound to a reachable address
hermes dashboard --no-open --host 0.0.0.0 --port 9119

In the Desktop app:

Go to Settings → Gateway → Remote gateway. Enter the remote URL (like http://host:9119), sign in with the credential method the backend advertises (username/password form or OAuth browser flow), then save and reconnect. The session persists across restarts if you set HERMES_DASHBOARD_BASIC_AUTH_SECRET.

Each profile can point at its own remote host. Switch profiles, and Desktop connects to a different backend.

Troubleshooting remote connections

• 401 / “Invalid credentials”: username or password doesn’t match the backend. Check both.
• No “Sign in” button, only session token input: the username/password provider isn’t active on the backend. Make sure HERMES_DASHBOARD_BASIC_AUTH_USERNAME and a password (or hash) are set in .env.
• Signed out on every restart: you need HERMES_DASHBOARD_BASIC_AUTH_SECRET set to a stable value.
• Connection refused / timeout: the backend bound to 127.0.0.1 or a firewall is blocking the port. Bind to 0.0.0.0 or the tailscale IP.

Updating and Uninstalling

Updates. The app checks for updates in the background and offers a one-click install when one is ready. You can also update from the CLI with hermes update.

Uninstall. Open Settings → About → Danger zone and pick how much to remove:

1. Uninstall Chat GUI only: removes the desktop app and its data; agent, config, and chats stay. Same as hermes uninstall --gui
2. Uninstall GUI + agent, keep my data: removes the app and agent but keeps config, chats, and secrets for a future reinstall. Same as hermes uninstall
3. Uninstall everything: removes the app, agent, and all user data. Same as hermes uninstall --full

Quick Troubleshooting Reference

When something isn’t working, here’s where to start:

• App won’t boot: check HERMES_HOME/logs/desktop.log (or hermes logs gui -f). Try the repair install option in the boot failure screen
• Desktop says “405 Method Not Allowed”: restart the app. That error usually means the backend process got into a bad state
• Voice mic not working on macOS: run tccutil reset Microphone com.nousresearch.hermes
• Remote sign-in keeps failing: verify the backend is reachable: curl http://host:9119/api/status
• General weirdness: hermes doctor is the first diagnostic tool for any Hermes issue

The Bottom Line

Hermes Desktop isn’t a replacement for the CLI or the gateway. It’s another frontend on the same agent, and the value is in having the right surface for the moment.

When am I using Desktop? Standard daily chat sessions, especially when I want to drop files into the conversation or see tool output in the side panel. Configuring something I’d rather not hand-edit in YAML. Running a session while looking at files in the browser.

When am I still using the CLI? Quick questions, piping output into other commands, scripting, or when I’m already in a terminal and don’t want to switch contexts.

When am I using the gateway? Always-on bots, Telegram DMs, any interaction that needs to reach me from a phone or another machine without me starting a session.

Try it. hermes desktop if you already have Hermes, or grab the installer from hermes-agent.nousresearch.com/desktop. It costs nothing to try, and if you hate it, hermes uninstall --gui cleans it up cleanly.