hermes-ui

Self-hosted web dashboard for Hermes Agent — 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:

export HERMES_BIN=/path/to/hermes

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

Getting Started

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:

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

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.