A full-featured web dashboard for Hermes Agent.
Manage AI chat sessions, monitor usage & costs, configure platform channels,
schedule cron jobs, browse skills — all from a clean, responsive web interface.

npm install -g hermes-web-ui && hermes-web-ui start

Hermes Web UI Demo

Features

AI Chat

Real-time chat streaming over Socket.IO /chat-run; API Server runs consume Hermes Gateway streaming responses
Multi-session management — create, rename, delete, switch between sessions
Self-built session database — local SQLite storage for Web UI sessions; Hermes state.db remains a read-only source for Hermes history APIs
Session grouping by source (Telegram, Discord, Slack, etc.) with collapsible accordion
Active session indicator — live sessions pin to top with spinner icon
Sessions sorted by latest message time
Markdown rendering with syntax highlighting and code copy
Tool call detail expansion (arguments / result)
File upload support
File download support — download user-uploaded files and agent-generated files across local, Docker, SSH, and Singularity backends
Session search — Ctrl+K search across the Web UI local session database; read-only Hermes history sessions are not included
Global model selector — discovers models from ~/.hermes/auth.json credential pool
Per-session model display badge and context token usage

Platform Channels

Unified configuration for 8 platforms in one page:

Platform	Features
Telegram	Bot token, mention control, reactions, free-response chats
Discord	Bot token, mention, auto-thread, reactions, channel allow/ignore lists
Slack	Bot token, mention control, bot message handling
WhatsApp	Enable/disable, mention control, mention patterns
Matrix	Access token, homeserver, auto-thread, DM mention threads
Feishu (Lark)	App ID / Secret, mention control
WeChat	QR code login (scan in browser, auto-save credentials)
WeCom	Bot ID / Secret

Credential management writes to ~/.hermes/.env
Channel behavior settings write to ~/.hermes/config.yaml
Auto gateway restart on config change
Per-platform configured/unconfigured status detection

Usage Analytics

Total token usage breakdown (input / output)
Session count with daily average
Estimated cost tracking & cache hit rate
Model usage distribution chart
30-day daily trend (bar chart + data table)

Scheduled Jobs

Create, edit, pause, resume, delete cron jobs
Trigger immediate execution
Cron expression quick presets

Model Management

Auto-discover models from credential pool (~/.hermes/auth.json)
Fetch available models from each provider endpoint (/v1/models)
Add, update, and delete providers (preset & custom OpenAI-compatible)
OpenAI Codex & Nous Portal OAuth login
Provider URL auto-detection for non-v1 API versions (e.g. /v4)
Provider-level model grouping with default model switching

Multi-Profile & Gateway

Create, rename, delete, and switch between Hermes profiles
Clone existing profile or import from archive (.tar.gz)
Export profile for backup or sharing
Multi-gateway management — start, stop, and monitor gateway per profile
Auto port conflict resolution
Profile-scoped configuration and cache isolation

File Browser

Browse files on remote backends (local, Docker, SSH, Singularity)
Upload, download, rename, copy, move, and delete files
Create directories
View file content with syntax highlighting

Group Chat

Multi-agent chat rooms with real-time messaging via Socket.IO
@mention routing — mention an agent to trigger a contextual reply
Context compression — automatic conversation summarization when history exceeds token threshold
Typing status and reply progress indicators
Room creation, deletion, and invite code management
Agent management — add/remove agents from rooms with per-agent profiles
SQLite message persistence
Mobile responsive with collapsible sidebar

Skills & Memory

Browse and search installed skills
View skill details and attached files
User notes and profile management

Logs

View agent / gateway / error logs
Filter by log level, log file, and keyword
Structured log parsing with HTTP access log highlighting

Authentication

Token-based auth (auto-generated on first run or set via AUTH_TOKEN env var)
Optional username/password login — set via settings page after initial token auth
Auth can be disabled with AUTH_DISABLED=1

Settings

Display (streaming, compact mode, reasoning, cost display)
Agent (max turns, timeout, tool enforcement)
Memory (enable/disable, char limits)
Session reset (idle timeout, scheduled reset)
Privacy (PII redaction)
Model settings (default model & provider)
API server configuration

Web Terminal

Integrated terminal powered by node-pty and @xterm/xterm
Multi-session support — create, switch between, and close terminal sessions
Real-time keyboard input and PTY output streaming via WebSocket
Window resize support

Quick Start

npm (Recommended)

npm install -g hermes-web-ui
hermes-web-ui start

Open http://localhost:8648

One-line Setup (Auto-detect OS)

Automatically installs Node.js (if missing) and hermes-web-ui on Debian/Ubuntu/macOS:

bash <(curl -fsSL https://raw.githubusercontent.com/EKKOLearnAI/hermes-web-ui/main/scripts/setup.sh)

WSL

bash <(curl -fsSL https://raw.githubusercontent.com/EKKOLearnAI/hermes-web-ui/main/scripts/setup.sh)
hermes-web-ui start

WSL auto-detects and uses hermes gateway run for background startup (no launchd/systemd).

Docker Compose

Single-container deployment with integrated Hermes Agent:

# Use pre-built image (Recommended)
WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose up -d

# Or build from source
docker compose up -d --build

docker compose logs -f hermes-webui

Open http://localhost:6060

Persistent Hermes data is stored in ./hermes_data
Web UI auth token is stored in ./hermes_data/hermes-web-ui/.token
On first run with auth enabled, the token is printed to container logs
All runtime settings are environment-variable driven in docker-compose.yml

For detailed notes and troubleshooting, see docs/docker.md.

Web UI Environment Variables

These variables configure Hermes Web UI itself. Provider API keys and Hermes Agent settings are managed separately through Hermes profiles.

Variable	Default	Description
`PORT`	`8648`	Web UI listen port.
`BIND_HOST`	`0.0.0.0`	Web UI bind host. Set `::` explicitly for IPv6.
`HERMES_WEB_UI_HOME`	`~/.hermes-web-ui`	Web UI data home for auth token, credentials, logs, DB, and default uploads. `HERMES_WEBUI_STATE_DIR` is also supported as a compatibility alias.
`UPLOAD_DIR`	`$HERMES_WEB_UI_HOME/upload`	Upload directory override.
`CORS_ORIGINS`	`*`	Koa CORS origin setting.
`AUTH_DISABLED`	unset	Set to `1` or `true` to disable Web UI auth.
`AUTH_TOKEN`	auto-generated	Explicit bearer token. If unset, Web UI creates one under `HERMES_WEB_UI_HOME`.
`PROFILE`	`default`	Initial Hermes profile name.
`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`	`/opt/data/workspace`	Base directory for workspace browsing.
`GATEWAY_HOST`	`127.0.0.1`	Default gateway host written into profile config.
`HERMES_WEB_UI_STOP_GATEWAYS_ON_SHUTDOWN`	environment-dependent	Whether Web UI shutdown also stops managed gateways.

CLI Commands

Command	Description
`hermes-web-ui start`	Start in background (daemon mode)
`hermes-web-ui start --port 9000`	Start on custom port
`hermes-web-ui stop`	Stop background process
`hermes-web-ui restart`	Restart background process
`hermes-web-ui status`	Check if running
`hermes-web-ui update`	Update to latest version & restart
`hermes-web-ui upgrade`	Alias for `update`
`hermes-web-ui -v`	Show version number
`hermes-web-ui -h`	Show help message

update / upgrade first attempt npm cache clean --force, then run npm install -g hermes-web-ui@latest and restart. Cache cleanup is best-effort; if it fails, the updater continues with the install.

Auto Configuration

On startup the BFF server automatically:

Validates ~/.hermes/config.yaml and fills missing api_server fields
Backs up original config to config.yaml.bak if modified
Detects and starts the gateway if needed
Resolves port conflicts (kills stale processes)
Opens browser on successful startup

Development

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

Frontend: http://localhost:5173
BFF Server: http://localhost:8648 (proxies to Hermes on 8642)

npm run build   # outputs to dist/

See DEVELOPMENT.md for project development guidelines.

Architecture

Browser → BFF (Koa, :8648) → Hermes Gateway (:8642)
                ↓
           Hermes CLI (sessions, logs, version)
                ↓
           ~/.hermes/config.yaml  (channel behavior)
           ~/.hermes/auth.json    (credential pool)
           Tencent iLink API      (WeChat QR login)

The frontend is designed with multi-agent extensibility — all Hermes-specific code is namespaced under hermes/ directories (API, components, views, stores), making it straightforward to add new agent integrations alongside.

The BFF layer handles API proxy (with path rewriting), SSE streaming, file upload and download (multi-backend: local/Docker/SSH/Singularity), session CRUD via CLI, config/credential management, WeChat QR login, model discovery, skills/memory management, log reading, and static file serving.

Tech Stack

Frontend: Vue 3 + TypeScript + Vite + Naive UI + Pinia + Vue Router + vue-i18n + SCSS + markdown-it + highlight.js

Backend: Koa 2 (BFF server) + node-pty (web terminal)

Star History

License

BSL-1.1

Keywords

FAQs

What is hermes-web-ui?

Is hermes-web-ui popular?

Is hermes-web-ui well maintained?

Package last updated on 16 May 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

hermes-web-ui