hermes-desktop/README.md

Hermes Desktop

Electron desktop application for Hermes Agent: chat, session history, skills, MCP, models, channels, files and usage analytics.

Getting started

For source development, use Node.js >=23 plus a user-installed Python/Hermes Agent. Installed desktop packages include Electron and Node.js; Hermes remains external. Set HERMES_BIN if the hermes executable is not on PATH.

npm ci --ignore-scripts
npm run electron:setup
npm run dev

For a production application:

npm run build
npm start
npm run dist

Installers are written to release/. Build on the target OS: macOS DMG/ZIP, Windows NSIS EXE, Linux AppImage/DEB. See Electron runtime for packaging, native modules, data locations and isolated verification.

Layout

electron          Electron main process, metadata preload and local-service entry
packages/client   Vue 3 client: views, components, Pinia stores, i18n, API helpers
packages/server   Koa API, Socket.IO chat runtime, SQLite stores, Hermes integration
packages/skills   Built-in skills injected into the Hermes skills directory
tests             Vitest unit/integration tests and Playwright browser tests
scripts           Build and repository harness scripts
docs              Architecture, harness docs, and the phased build plan

Docker

docker compose up -d

The image is based on nousresearch/hermes-agent, so Python and the Hermes CLI are already present in the container.

Configuration

Variable	Purpose
HERMES_BIN	Path to the hermes executable. Falls back to hermes on PATH.
HERMES_HOME	Hermes profile directory. Used to isolate profiles.
HERMES_WEB_UI_HOME	Service state override. Desktop default: Electron userData/state; standalone web: ~/.hermes-web-ui.
HERMES_WEBUI_STATE_DIR	Alternate override for the Web UI state directory.
PORT	Standalone web server port. Desktop selects and persists a local port.

The HERMES_WEB_UI_* prefixes and the ~/.hermes-web-ui data directory are kept from the 0.6.x line on purpose, so existing deployments and data directories keep working.

Commands

Command	Description
npm run dev	Launch Electron with Vite hot reload.
npm run dev:web	Optional standalone web development.
npm run electron:setup	Download Electron and rebuild native modules.
npm run pack / npm run dist	Build unpacked app / native installers.
npm run test:electron	Real Electron lifecycle smoke test.
npm run build	Type-check and build client, server, main and preload.
npm start	Launch the built desktop app.
npm run test	Run Vitest tests.
npm run test:coverage	Run Vitest with coverage.
npm run test:e2e	Run Playwright browser tests.
npm run harness:check	Validate repository docs, workflows, and package scripts.
npm run openapi:generate	Regenerate docs/openapi.json.

License

BSL-1.1. See LICENSE.