hermes-web-ui/README.md

Hermes Web UI 中文

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

Mobile

---

Features

AI Chat

• Real-time streaming via SSE with async run support
• Multi-session management — create, rename, delete, switch between sessions
• 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
• 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 OAuth login for Codex models
• 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

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

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

Run Web UI together with Hermes Agent:

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

# Or build from source
docker compose up -d --build hermes-agent hermes-webui

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.

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 -v	Show version number
hermes-web-ui -h	Show help message

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/

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

MIT