hermes-agent/apps/desktop

Hermes Desktop ☤

The native desktop app for Hermes Agent — the self-improving AI agent from Nous Research. Same agent, same skills, same memory as the CLI and gateway, in a polished native window — chat with streaming tool output, side-by-side previews, a file browser, voice, and settings, no terminal required. Available for macOS, Windows, and Linux.

Chat with the full agent	Streaming responses, live tool activity, structured tool summaries, and the same conversation history as every other Hermes surface.
Side-by-side previews	Render web pages, files, and tool outputs in a right-hand pane while you keep chatting.
File browser	Explore and preview the working directory without leaving the app.
Voice	Talk to Hermes and hear it back.
Settings & onboarding	Manage providers, models, tools, and credentials from a real UI. First-run setup gets you to your first message in seconds.
Stays current	Built-in updates pull the latest agent and rebuild the app in place.

---

Install

Install with Hermes (recommended)

Already have the Hermes CLI? Just run:

hermes desktop

It builds and launches the GUI against your existing install — same config, keys, sessions, and skills. On first launch Hermes walks you through picking a provider and model; nothing else to configure.

Prebuilt installers

Prebuilt installers are built and distributed via the Hermes Desktop website..

---

Updating

The app checks for updates in the background and offers a one-click update when one is ready. You can also update any time from the CLI:

hermes update

---

Requirements

The installer handles everything for you (Python 3.11+, a portable Git, ripgrep).

---

Development

Want to hack on the app itself? Install workspace deps from the repo root once, then run the dev server from this directory:

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 source checkout, or sandbox it away 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

Building 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)

Installers are built and uploaded to GitHub Releases manually. macOS/Windows signing & notarization happen automatically when the relevant credentials are present in the environment (CSC_LINK / CSC_KEY_PASSWORD / APPLE_* for macOS, WIN_CSC_* for Windows).

How it works

The packaged app ships the Electron shell and a native React chat surface. On first launch it can install the Hermes Agent runtime into HERMES_HOME (~/.hermes, or %LOCALAPPDATA%\hermes on Windows) — the same layout a CLI install uses, so the two are interchangeable. Backend resolution first honours HERMES_DESKTOP_HERMES_ROOT, then a completed managed install, then a probed hermes on PATH (unless HERMES_DESKTOP_IGNORE_EXISTING=1 is set), and finally an explicit HERMES_DESKTOP_HERMES command override for packagers/troubleshooting. The renderer (React, in src/) talks to a headless backend the app launches for you — a hermes serve process that serves the tui_gateway JSON-RPC/WebSocket API — through the framework-agnostic client in apps/shared (the same client the web dashboard consumes), and reuses the agent runtime rather than embedding hermes --tui. The app is self-contained: it runs its own hermes serve backend and never opens or requires the web dashboard UI. (For backward compatibility, a runtime that predates the serve command automatically falls back to a headless dashboard --no-open — see electron/backend-command.cjs — so mid-upgrade installs never break.) The install, backend-resolution, and self-update logic all live in electron/main.cjs.

Verification

Run before opening a PR (lint may surface pre-existing warnings but must exit cleanly):

npm run fix
npm run typecheck
npm run lint
npm run test:desktop:all

Troubleshooting

Boot logs land in HERMES_HOME/logs/desktop.log (includes backend output and recent Python tracebacks) — check it first if the app reports a boot failure.

macOS / Linux:

# Force a clean first-launch setup
rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"
# Rebuild a broken Python venv
rm -rf "$HOME/.hermes/hermes-agent/venv"
# Reset a stuck macOS microphone prompt (macOS only)
tccutil reset Microphone com.nousresearch.hermes

Windows (PowerShell):

# Force a clean first-launch setup
Remove-Item "$env:LOCALAPPDATA\hermes\hermes-agent\.hermes-bootstrap-complete"
# Rebuild a broken Python venv
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes\hermes-agent\venv"

The default Hermes home on Windows is %LOCALAPPDATA%\hermes. Set the HERMES_HOME env var if you've relocated it.

---

Community

• 💬 Discord
• 📖 Documentation
• 🐛 Issues

---

License

MIT — see LICENSE.

Built by Nous Research.