# hermes-ui

Self-hosted web dashboard for [Hermes Agent](https://github.com/NousResearch) — chat, session
history, skills, MCP servers, model management, IM channels, file management, and usage analytics
in one browser UI.

> This project is under active rebuild. Feature work is being staged phase by phase; see
> `docs/phases/README.md` for the current plan.

## Prerequisites

hermes-ui runs as a plain Node.js server. It does **not** bundle a runtime.

- Node.js `>=23`
- Python with `hermes-agent` installed

Install `hermes-agent`, then either put `hermes` on your `PATH` or point `HERMES_BIN` at the
executable:

```bash
export HERMES_BIN=/path/to/hermes
```

If the CLI cannot be found, the UI shows an install hint instead of failing silently.

## Getting Started

```bash
npm ci --ignore-scripts
npm run build
npm start
```

Then open http://localhost:8648 and log in with the default credentials printed on first start.

For development with hot reload:

```bash
npm run dev
```

The client runs on http://localhost:8649 and the Koa server on port 8647.

## Layout

```
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` | Web UI state directory. Defaults to `~/.hermes-web-ui`. |
| `HERMES_WEBUI_STATE_DIR` | Alternate override for the Web UI state directory. |
| `PORT` | Server 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` | Run client and server with hot reload. |
| `npm run build` | Type-check and build client and server bundles. |
| `npm start` | Serve the production build. |
| `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`.