GitHub - PyModel/hermes-ui: Self-hosted control plane for Hermes Agent — chat, profiles, providers, models, skills, automation, and logs in one local dashboard. Ships as a desktop app, an npm CLI, and a Docker image.

A desktop app, local runtime, and web console for Hermes Agent — chat with agents, manage models and profiles, connect platform channels, automate jobs, and run coding agents, all on your own machine.

Quick Start · Features · Configuration · Docker · Development

Overview

Hermes UI is a self-hosted control plane for Hermes Agent. It runs agent conversations with streaming responses and tool traces, and gives you one dashboard for profiles, providers, models, credentials, memory, skills, plugins, automation, and logs. It ships three ways — a native desktop app, an npm CLI, and a Docker image — and keeps all data local.

Note

Everything stays on your machine. Hermes Agent data lives in ~/.hermes, and UI state (sessions, auth, uploads) lives in ~/.hermes-ui unless HERMES_UI_HOME is set.

Area	What Hermes UI does
Agent chat	Streaming Hermes Agent conversations with tool traces, file upload/download, and persistent local sessions.
Local control plane	Manage profiles, providers, models, credentials, memory, skills, plugins, logs, and runtime settings from one dashboard.
Automation	Configure platform channels, cron jobs, Kanban tasks, group-chat rooms, and MCP servers around the same profiles.
Workspace tools	File browser, web terminal, voice input/output, coding-agent runners, device discovery, and performance views.
Distribution	Desktop app for Windows/macOS/Linux, an npm CLI package, and a Docker image.

Quick Start

Desktop app (recommended)

Download the latest installer from GitHub Releases. Builds are published for macOS, Windows, and Linux. The desktop app bundles the UI runtime and starts the local server automatically.

After first launch it installs managed command shims:

Command	Description
`hermes-ui`	Open the Hermes UI desktop app
`hermes-ui cli ...`	Run the bundled Hermes Agent CLI
`hermes-ui web ...`	Run the bundled `hermes-ui` command
`hermes-ui-mcp`	Run the managed UI MCP bridge

npm

npm install -g @pythoughts/hermes-ui
hermes-ui start

Then open http://localhost:8648.

Important

Requires Node.js >= 23.

Docker Compose

Single-container deployment with an integrated Hermes Agent:

# Use the pre-built image (recommended)
UI_IMAGE=pythoughtslabs/hermes-ui docker compose up -d
# Or build from source
docker compose up -d --build
docker compose logs -f hermes-ui

Then open http://localhost:6060. Persistent data is stored in ./hermes_data; the auth token is written to ./hermes_data/hermes-ui/.token and printed to the container logs on first run. See docs/docker.md for details.

Features

Agent chat

Real-time streaming over Socket.IO, multi-session management, and a local SQLite session store separate from Hermes' read-only history. Markdown rendering with syntax highlighting, expandable tool-call details, profile-scoped uploads, and path-based downloads across local, Docker, SSH, and Singularity backends. Sessions group by source (Telegram, Discord, Slack, …), pin live runs to the top, and are searchable with Ctrl+K.

Platform channels

Configure 8 platforms from one page — Telegram, Discord, Slack, WhatsApp, Matrix, Feishu (Lark), WeChat (QR login), and WeCom. Credentials write to ~/.hermes/.env and behavior settings to ~/.hermes/config.yaml, with per-platform configured/unconfigured detection.

Models & profiles

Auto-discover models from the credential pool, fetch provider model lists, and manage preset or custom OpenAI-compatible providers (including OpenAI Codex and Nous Portal OAuth). Create, clone, import, export, and switch Hermes profiles, with account-bound access — super admins manage every profile; regular admins only see profiles assigned to them.

Automation & workspace

Scheduled jobs — create, edit, pause, resume, and trigger cron jobs with quick presets.
Kanban — a profile-aware board for planning and tracking agent work.
Group chat — multi-agent rooms with @mention routing, context compression, and SQLite persistence.
Coding agents — launch and monitor local Codex and Claude Code sessions from the dashboard.
File browser — browse, edit, and transfer files across local, Docker, SSH, and Singularity backends.
Web terminal — node-pty + xterm with multi-session support and resize.

Voice (TTS / STT)

Read assistant replies aloud and dictate turns from the chat input. Providers include browser Web Speech, built-in Edge TTS, OpenAI-compatible /audio/speech, custom endpoints, and MiMo (preset voices, voice design, and voice cloning). Provider keys are stored server-side and only masked status is returned to the browser.

Warning

Custom/OpenAI-compatible and MiMo base URLs must be public http/https endpoints — they cannot target localhost or private networks. External providers may keep processing a request after the browser or server aborts.

Analytics, logs & admin

Token usage breakdowns, session counts, estimated cost and cache-hit tracking, model-usage distribution, and a 30-day trend. Filterable agent/server/error logs with structured parsing. LAN peer discovery, an MCP manager for the managed hermes-ui server, version-preview tooling, and performance views for super admins.

Authentication

Token-based auth (auto-generated or set via AUTH_TOKEN) plus username/password login with account management.

Caution

Default bootstrap credentials are admin / admin. You are prompted to change them after first login — do so before exposing the server.

CLI maintenance:

hermes-ui clear-login-locks # clear persisted login IP locks
hermes-ui clear-login-locks --restart # clear locks and restart the server
hermes-ui reset-default-login # reset the super-admin login to admin / admin

Configuration

Provider keys and agent settings are normally managed through Hermes profiles; the variables below are process-level overrides. The most common ones:

Variable	Default	Description
`PORT`	`8648`	UI listen port.
`BIND_HOST`	`0.0.0.0`	Bind host. Set `::` for IPv6.
`HERMES_UI_HOME`	`~/.hermes-ui`	Data home for auth token, credentials, logs, DB, and uploads.
`AUTH_TOKEN`	auto-generated	Explicit bearer token.
`AUTH_JWT_SECRET`	`AUTH_TOKEN`	JWT signing secret for username/password sessions.
`PROFILE`	`default`	Startup/default Hermes profile.
`CORS_ORIGINS`	same host only	Cross-origin allowlist for HTTP, Socket.IO, and WebSocket.
`LOG_LEVEL`	`info`	Server log level.
`WORKSPACE_BASE`	user home	Base directory for workspace browsing.
`HERMES_HOME`	platform default	Hermes data home (`%LOCALAPPDATA%\hermes` on Windows, `~/.hermes` elsewhere).

All environment variables

Variable	Default	Description
`PORT`	`8648`	UI listen port.
`BIND_HOST`	`0.0.0.0`	UI bind host. Set `::` explicitly for IPv6.
`HERMES_UI_HOME`	`~/.hermes-ui`	UI data home for auth token, credentials, logs, DB, and default uploads. `HERMES_UI_STATE_DIR` is also supported as a compatibility alias.
`HERMES_UI_STATE_DIR`	unset	Compatibility alias for `HERMES_UI_HOME`.
`HERMES_UI_DISABLE_MCP_AUTOINJECT`	unset	Disable startup injection of the managed `hermes-ui` MCP server into Hermes profile configs.
`HERMES_UI_ALLOW_TRANSIENT_MCP_AUTOINJECT`	unset	Allow managed MCP injection when `HERMES_UI_HOME` is under a temporary directory, such as Version Preview runtimes.
`UPLOAD_DIR`	`$HERMES_UI_HOME/upload`	Upload root override. Files are stored below profile-scoped subdirectories.
`CORS_ORIGINS`	same host only	Comma- or space-separated cross-origin allowlist for HTTP, Socket.IO, and WebSocket requests. Set `*` only when you intentionally need legacy wildcard CORS.
`AUTH_TOKEN`	auto-generated	Explicit bearer token. If unset, UI creates one under `HERMES_UI_HOME`.
`AUTH_JWT_SECRET`	`AUTH_TOKEN`	JWT signing secret override for username/password sessions.
`PROFILE`	`default`	Startup/default Hermes profile. Runtime requests use the profile selected by the frontend and authorized for the current account.
`LOG_LEVEL`	`info`	Server log level.
`BRIDGE_LOG_LEVEL`	`$LOG_LEVEL` or `info`	Bridge log level.
`MAX_DOWNLOAD_SIZE`	`200MB`	Maximum file download size.
`MAX_EDIT_SIZE`	`10MB`	Maximum editable file size.
`WORKSPACE_BASE`	current user's home directory	Base directory for workspace browsing.
`HERMES_HOME`	platform default	Hermes data home. Windows uses `%LOCALAPPDATA%\hermes`; macOS/Linux uses `~/.hermes`.
`HERMES_BIN`	`hermes`	Custom Hermes CLI binary path.
`HERMES_AGENT_ROOT`	auto-discovered	Hermes Agent source checkout containing `run_agent.py`.
`HERMES_AGENT_BRIDGE_PYTHON`	auto-discovered	Python interpreter used to launch the agent bridge.
`HERMES_AGENT_BRIDGE_UV`	auto-discovered	`uv` executable used to launch the agent bridge when available.
`UV`	auto-discovered	Fallback `uv` executable path.
`PYTHON`	auto-discovered	Fallback Python executable for the agent bridge.
`HERMES_AGENT_BRIDGE_ENDPOINT`	platform default	Agent bridge broker endpoint. Windows defaults to `tcp://127.0.0.1:18765`; macOS/Linux defaults to `ipc:///tmp/hermes-agent-bridge.sock`.
`HERMES_AGENT_BRIDGE_TIMEOUT_MS`	`120000`	Timeout for Node requests to the bridge broker.
`HERMES_AGENT_BRIDGE_CONNECT_RETRY_MS`	`5000`	Short retry window for connecting to the bridge socket.
`HERMES_AGENT_BRIDGE_STARTUP_TIMEOUT_MS`	`120000`	Timeout while waiting for the Python bridge to become ready.
`HERMES_AGENT_BRIDGE_STOP_ON_SHUTDOWN`	enabled	Stop the bridge broker during UI shutdown and restart. Set `0`, `false`, `no`, or `off` to keep the bridge across restarts.
`HERMES_AGENT_BRIDGE_AUTO_RESTART`	enabled	Auto-restart the bridge broker after unexpected exit. Set `0`, `false`, `no`, or `off` to disable.
`HERMES_AGENT_BRIDGE_RESTART_DELAY_MS`	`1000`	Base delay for bridge auto-restart backoff.
`HERMES_AGENT_BRIDGE_PLATFORM`	`cli`	Platform identity passed to Hermes Agent.
`HERMES_AGENT_BRIDGE_WORKER_TRANSPORT`	platform default	Profile worker transport. Set `tcp` for loopback TCP or `ipc`/`unix` for Unix domain sockets; defaults to Windows TCP and macOS/Linux IPC.
`HERMES_AGENT_BRIDGE_WORKER_PORT_BASE`	`18780`	Base port for TCP worker endpoints.
`HERMES_BRIDGE_PROVIDER`	profile/default	Provider override for bridge runs.
`HERMES_BRIDGE_TOOLSETS`	profile/default	Toolset override for bridge runs.
`HERMES_BRIDGE_MAX_TURNS`	profile/default	Maximum turn override for bridge runs.
`HERMES_BRIDGE_SUPPRESS_PLATFORM_HINT`	`cli`	Controls bridge platform hint suppression passed to Hermes Agent.
`HERMES_OPENROUTER_APP_REFERER`	`https://github.com/Pythoughts-labs/hermes-ui`	OpenRouter attribution referer sent by bridge runs.
`HERMES_OPENROUTER_APP_TITLE`	`Hermes UI`	OpenRouter attribution title sent by bridge runs.
`HERMES_OPENROUTER_APP_CATEGORIES`	`cli-agent,personal-agent`	OpenRouter attribution categories sent by bridge runs.
`HERMES_UI_MANAGED_GATEWAY`	enabled	Controls UI-managed Hermes gateway process handling. Set `0`, `false`, `no`, or `off` to use `hermes gateway start` instead.
`HERMES_UI_DISABLE_GATEWAY_AUTOSTART`	unset	Skip startup gateway checks/autostart. Set `1`, `true`, `yes`, or `on` for dashboard-only deployments where another service owns Hermes gateway lifecycle.
`HERMES_UI_DISABLE_SKILL_INJECTION`	unset	Skip startup bundled skill injection. Set `1`, `true`, `yes`, or `on` when bundled skills are managed outside Hermes UI.
`HERMES_UI_STOP_GATEWAYS_ON_SHUTDOWN`	enabled in production	Controls whether UI shutdown also stops managed gateway processes. Set `0` or `false` to detach them.
`HERMES_GATEWAY_URL` / `GATEWAY_URL`	unset	Explicit Hermes gateway upstream URL for proxy routes.
`GATEWAY_HOST`	`127.0.0.1`	Default Hermes gateway upstream host for proxy routes.
`GATEWAY_PORT`	`8642`	Default Hermes gateway upstream port for proxy routes.
`HERMES_UI_PREVIEW_REPO`	package repository	GitHub repository used by Version Preview.
`HERMES_UI_PREVIEW_AGENT_BRIDGE_TRANSPORT`	platform default	Version Preview broker transport.
`HERMES_UI_PREVIEW_AGENT_BRIDGE_ENDPOINT`	isolated preview endpoint	Directly overrides the Version Preview broker endpoint.
`HERMES_UI_BACKEND_PORT`	`8648`	Backend port used by the Vite dev proxy.
`HERMES_UI_FRONTEND_PORT`	`8649`	Frontend Vite dev server port.

CLI commands

Command	Description
`hermes-ui start`	Start in background (daemon mode)
`hermes-ui start --port 9000`	Start on a custom port
`hermes-ui stop`	Stop the background process
`hermes-ui restart`	Restart the background process (stops the bridge by default)
`hermes-ui status`	Check if running
`hermes-ui update`	Update to the latest version and restart
`hermes-ui -v`	Show the version number
`hermes-ui -h`	Show help

Tip

restart, update, and upgrade stop the Agent Bridge broker by default so restarted servers don't reuse stale Python bridge processes. Set HERMES_AGENT_BRIDGE_STOP_ON_SHUTDOWN=0 to keep the bridge alive across restarts.

Architecture

Browser → BFF (Koa, :8648) → Socket.IO /chat-run
↓
Hermes agent bridge → Hermes Agent runtime
↓
Hermes CLI / profiles
profile config.yaml (channel/provider behavior)
profile auth.json (credential pool)
Tencent iLink API (WeChat QR login)

The frontend is built for multi-agent extensibility — all Hermes-specific code is namespaced under hermes/ directories (API, components, views, stores), so new agent integrations can sit alongside it. The BFF layer handles Socket.IO chat streaming, the agent bridge, profile-aware uploads and multi-backend downloads, session CRUD, account- and profile-scoped management, config and credential management, WeChat QR login, model discovery, skills/memory/plugins, TTS/STT, coding-agent proxies, MCP/runtime management, log reading, and static serving.

Tech stack: Vue 3 · TypeScript · Vite · Naive UI · Pinia · Vue Router · vue-i18n · SCSS · markdown-it · highlight.js · Koa 2 · node-pty.

Development

git clone https://github.com/Pythoughts-labs/hermes-ui.git
cd hermes-ui
npm install
npm run dev

Frontend: http://localhost:8649
BFF server: http://localhost:8647

npm run build # outputs to dist/
npm test# run the test suite

See DEVELOPMENT.md for the full development guide.

Name		Name	Last commit message	Last commit date
.github		.github
bin		bin
docs		docs
packages		packages
scripts		scripts
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CLAUDE.md		CLAUDE.md
DEVELOPMENT.md		DEVELOPMENT.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
nodemon.json		nodemon.json
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
tsconfig.website.json		tsconfig.website.json
vite.config.ts		vite.config.ts
vite.config.website.ts		vite.config.website.ts
vitest.config.ts		vitest.config.ts

Navigation Menu

Uh oh!

Repository files navigation

Overview

Quick Start

Desktop app (recommended)

npm

Docker Compose

Features

Agent chat

Platform channels

Models & profiles

Automation & workspace

Voice (TTS / STT)

Analytics, logs & admin

Authentication

Configuration

CLI commands

Architecture

Development

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Overview

Quick Start

Desktop app (recommended)

npm

Docker Compose

Features

Agent chat

Platform channels

Models & profiles

Automation & workspace

Voice (TTS / STT)

Analytics, logs & admin

Authentication

Configuration

CLI commands

Architecture

Development

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages