# Hermes Desktop

Electron desktop application for [Hermes Agent](https://github.com/NousResearch): 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.

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

For a production application:

```bash
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](docs/electron.md)
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

```bash
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`.