website/docs/user-guide/desktop.md
The Hermes desktop app is a native app built around the same agent you get from the CLI and the gateway — same config, same API keys, same sessions, same skills, same memory. It is not a separate product or a lightweight clone; it uses the same Hermes Agent core and settings, and drives it through a modern & thoughtfully designed UI. If you have used hermes in a terminal, everything you set up there is already here, and anything you do here shows up there.
It runs on macOS, Windows, and Linux.
:::tip Which interface is which? Hermes has several front ends that all talk to the same agent:
hermes) and TUI (hermes --tui) — terminal interfaces.hermes dashboard) — a browser admin panel; its optional Chat tab embeds the TUI through a pseudo-terminal.Pick whichever fits the moment. They share state, so you can start a session in one and resume it in another. :::
Follow the installation instructions for Hermes Desktop.
If you already have Hermes installed, simply run
hermes desktop
That uses your current config, keys, sessions, and skills.
The desktop app is organized as a chat-first window with a left sidebar for navigation. It's built to allow managing multiple simultaneous agent conversations, configuring messaging providers, creating artifacts, browsing projects' folder structures, and working on multiple projects at once.
The center of the app. You get:
The bar along the bottom of the chat shows live session state and exposes quick controls without opening Settings:
Chatting against a Hermes instance on another machine instead of the bundled local backend? See Connecting to a remote backend below — and for the full picture of how the remote-hosted dashboard connection works (the auth gate, the /api/ws chat socket, and WebSocket close-code triage), see Web Dashboard → Connecting Hermes Desktop to a remote backend.
Explore and preview the working directory without leaving the app — useful for following along as the agent reads, writes, and edits files. Set the initial project directory with hermes desktop --cwd <path> (or the HERMES_DESKTOP_CWD environment variable).
Talk to Hermes and hear it back, the same voice mode available elsewhere. On macOS the OS will prompt once for microphone access.
Manage providers, models, tools, and credentials from a real UI instead of editing YAML. First-run onboarding gets you to your first message in seconds. The settings panes cover providers/keys, model selection, toolset configuration, MCP servers, the gateway, and session management.
hermes model knows about, so you pick from the same catalog the CLI sees rather than a curated subset.First-run onboarding has been redesigned on a unified overlay design system, and you can pick Choose provider later to skip provider setup and get into the app first.
The app also surfaces the broader Hermes management surface so you don't have to drop to a terminal:
@session links.The app checks for updates in the background and offers a one-click update when one is ready.
The manual update process also works with the GUI.
Open Settings → About → Danger zone and pick how much to remove:
hermes uninstall --gui.)hermes uninstall.)hermes uninstall --full.)The app closes to finish the job (the cleanup runs after it exits so it can remove the running app bundle and its own venv). The agent-removing options are hidden automatically when no local agent is installed (for example, a GUI-only "lite" client connected to a remote backend).
You can do the same from the terminal — hermes uninstall --gui for the GUI alone, or hermes uninstall / hermes uninstall --full for the agent too.
:::note
Running hermes uninstall --gui from a source checkout (a hermes desktop dev build) also removes the workspace node_modules and apps/desktop/{dist,release} build output, since those are GUI build artifacts. They're recoverable with hermes desktop (or npm install + a rebuild) — but if you're actively hacking on the desktop app, expect to reinstall dependencies afterward.
:::
hermes desktopTo launch via the CLI, simply run hermes desktop. By default it installs workspace Node dependencies, builds the current OS's unpacked Electron app, then launches that packaged artifact.
| Flag | Description |
|---|---|
--skip-build | Skip npm install/package and launch the existing unpacked app from apps/desktop/release |
--force-build | Force a full rebuild even if the content stamp matches |
--build-only | Build the desktop app but do not launch it (used by hermes update) |
--source | Launch via electron . against apps/desktop/dist instead of the packaged app |
--cwd PATH | Initial project directory for desktop chat sessions (sets HERMES_DESKTOP_CWD) |
--hermes-root PATH | Override the Hermes source root the app uses (sets HERMES_DESKTOP_HERMES_ROOT) |
--ignore-existing | Force the app to ignore any hermes CLI already on PATH during backend resolution |
--fake-boot | Enable deterministic boot delays for validating the startup UI |
The packaged app ships only the Electron shell. On first launch it installs the Hermes Agent runtime into HERMES_HOME (~/.hermes, or %LOCALAPPDATA%\hermes on Windows) — the same layout a CLI install uses, which is why the two are interchangeable. The React renderer talks to a hermes dashboard backend over the standard gateway APIs and reuses the agent rather than reimplementing it. Install, backend-resolution, and self-update logic live in the Electron main process.
By default the app starts and manages its own local backend. You can instead point it at a Hermes backend running on another machine — a VPS, a home server, or a Mini behind Tailscale.
:::info The remote backend is a running hermes dashboard process
"Remote backend" means a hermes dashboard server running on the remote machine — that is the process the desktop app connects to. Nothing in this section works unless that dashboard is actually up and reachable. The desktop app does not start it for you; you (or a systemd service) keep hermes dashboard running on the remote host, and the app attaches to it. If you also use messaging channels (Telegram, Discord, etc.), the gateway is a separate long-running process you start independently — see the note after the setup steps.
:::
The connection has two halves: on the backend you protect the dashboard with an auth provider, and in the app you enter the backend's URL and sign in. Binding the dashboard to a non-loopback address automatically engages its auth gate, and the provider you configure is what lets the desktop app through.
Pick a provider based on where the backend lives:
hermes dashboard register (or the Portal /local-dashboards page) to provision its OAuth client, then sign in from the app with Sign in with Nous Research. A self-hosted OIDC provider works the same way if you run your own identity provider.The rest of this section shows the username/password path because it's the quickest to stand up on a trusted network; for the OAuth path see Web Dashboard → Default provider: Nous Research.
Set a username and password, then start the dashboard bound to a reachable address. The credentials live in ~/.hermes/.env (the secrets file, mode 0600):
# 1. Set the dashboard login credentials.
cat >> ~/.hermes/.env <<'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
# Recommended: a stable signing secret so sessions survive restarts.
# Without it a random key is generated per boot and you'll be logged out
# on every restart.
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env
# 2. Run the dashboard bound to a reachable address. The non-loopback bind
# engages the auth gate; the username/password provider handles login.
hermes dashboard --no-open --host 0.0.0.0 --port 9119
Keep that hermes dashboard process running for as long as you want the desktop app to be able to connect — if it stops, the app can no longer reach the backend. Run it under systemd, tmux, or your process manager of choice so it survives logout and reboots.
Separately, make sure the gateway is running on the remote host if you rely on messaging channels — the dashboard backend is what the desktop app talks to, but your Telegram/Discord/Slack gateway sessions are a different process that you start and keep running on their own. See Messaging for gateway setup.
Prefer not to keep a plaintext password at rest? Set HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH to a scrypt hash instead — compute it with python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('PW'))". Full configuration surface (config.yaml keys, every env var, the rate limiter): Web Dashboard → Username/password provider.
Running the dashboard as a systemd service? Give the unit EnvironmentFile=%h/.hermes/.env so the credentials are in the environment at boot.
:::warning
The dashboard reads and writes your .env (API keys, secrets) and can run agent commands. The username/password setup shown above is for a trusted network — never expose a password-protected dashboard directly to the open internet; put it behind a VPN. Tailscale is the clean option: bind to the machine's tailscale IP (--host <tailscale-ip>) and use http://<tailscale-ip>:9119 as the Remote URL so only your tailnet can reach it. To reach a backend over the public internet, use the OAuth (Nous Portal) provider instead.
:::
Settings → Gateway → Remote gateway:
http://<backend-host>:9119 (path prefixes like /hermes work if you front it with a reverse proxy)<provider> (e.g. Sign in with Nous Research), which runs the provider's browser sign-in. Either way the app ends up with an authenticated session against the backend.HERMES_DASHBOARD_BASIC_AUTH_SECRET is set.You can also set the backend URL without the UI via the HERMES_DESKTOP_REMOTE_URL environment variable before launching the app (it overrides the in-app setting); you still sign in from the Gateway settings panel.
:::note Per-profile remote hosts The remote gateway host is configured per profile, so each profile can point at its own remote backend (or stay on its local one). Switching profiles switches which remote host the app connects to. :::
HERMES_DASHBOARD_BASIC_AUTH_USERNAME / HERMES_DASHBOARD_BASIC_AUTH_PASSWORD. The backend returns the same generic error for an unknown user and a wrong password (no enumeration oracle), so double-check both. Confirm the gate is on with curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers' — it should report true and include "basic"./api/status won't list "basic" in auth_providers. Make sure both the username and a password (or password hash) are set in ~/.hermes/.env and that the dashboard process actually loaded them.HERMES_DASHBOARD_BASIC_AUTH_SECRET to a stable value. Without it the token-signing key is regenerated per boot, invalidating all sessions.127.0.0.1 (the default) or a firewall/VPN is blocking the port. Bind to 0.0.0.0 or the tailscale IP and open the port to your trusted network.For the same setup from the web-dashboard angle, see Web Dashboard → Connecting Hermes Desktop to a remote backend; the env vars are catalogued under Environment Variables → Web Dashboard & Hermes Desktop.
Boot logs land in HERMES_HOME/logs/desktop.log (it includes backend output and recent Python tracebacks) — check it first if the app reports a boot failure. You can also tail it from the CLI:
hermes logs gui -f
Common resets:
# Force a clean first-launch setup (macOS/Linux)
rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"
# Rebuild a broken Python venv (macOS/Linux)
rm -rf "$HOME/.hermes/hermes-agent/venv"
# Reset a stuck macOS microphone prompt
tccutil reset Microphone com.nousresearch.hermes
The build downloads the Electron runtime (~114 MB) from github.com/electron/electron/releases. If the installer hangs on the Build desktop app step with the live output repeating retrying attempt=…, GitHub is being blocked or throttled on your network (firewall, proxy, or region).
The installer self-heals this automatically: on a failed build it (1) clears a corrupt cached Electron zip and retries, then (2) if it still fails and you haven't set ELECTRON_MIRROR, retries once more through npmmirror.com, the de-facto Electron community mirror. @electron/get SHASUM-checks the download, but the checksums come from the same mirror — that catches a corrupt or partial download, not a compromised mirror. If you'd rather not trust a third-party host, pin your own ELECTRON_MIRROR (below); the build never overrides one you've set.
To choose your own mirror (e.g. a corporate/trusted one), set ELECTRON_MIRROR before installing or rebuild manually — the build honors it and won't override it:
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ \
bash -c 'cd "$HOME/.hermes/hermes-agent/apps/desktop" && CSC_IDENTITY_AUTO_DISCOVERY=false npm run pack'
To clear a corrupt cached zip by hand:
rm -f "$HOME/Library/Caches/electron"/electron-*.zip # macOS
rm -f "$HOME/.cache/electron"/electron-*.zip # Linux
If you want to hack on the app itself, install workspace deps from the repo root once, then run the dev server from apps/desktop:
npm install # from repo root — links apps/desktop, web, apps/shared
cd apps/desktop
npm run dev # Vite renderer + Electron, which boots the Python backend
Point the app at a specific checkout, or sandbox it from your real config:
HERMES_DESKTOP_HERMES_ROOT=/path/to/clone npm run dev
HERMES_HOME=/tmp/throwaway npm run dev
npm run dev:fake-boot # exercise the startup overlay with deterministic delays
Build installers:
npm run dist:mac # DMG + zip
npm run dist:win # NSIS + MSI
npm run dist:linux # AppImage + deb + rpm
npm run pack # unpacked app under release/ (no installer)
macOS/Windows signing and notarization run automatically when the relevant credentials are present in the environment (CSC_LINK / CSC_KEY_PASSWORD / APPLE_* for macOS, WIN_CSC_* for Windows).