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

Hermes Web UI Demo

Hermes Web UI Demo

npm version license stars

--- ## Features ### AI Chat - Real-time chat streaming over Socket.IO `/chat-run`; chat runs execute through the Hermes agent bridge - 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) - Profile-scoped file uploads - File download support — download uploaded files and agent-generated files by resolved path 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 - Profile-aware model selector — discovers models available to the signed-in account through authorized Hermes profiles - 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` - 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 - Create, rename, delete, and switch between Hermes profiles - Clone existing profile or import from archive (`.tar.gz`) - Export profile for backup or sharing - Profile-scoped configuration, cache, uploads, sessions, jobs, usage, memory, skills, plugins, providers, and model visibility - Account-bound profile access: super administrators can manage every profile; regular administrators only see and use profiles assigned to their account ### File Browser - Browse files on remote backends (local, Docker, SSH, Singularity) - Upload, download, rename, copy, move, and delete files - Store uploaded files under the selected/requested Hermes profile while keeping downloads path-based for agent-generated artifacts outside the upload directory - 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 / server / 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) - Username/password login with account management in Settings - Default bootstrap credentials are `admin` / `123456`; users are prompted after login to change the default username and password - Super administrators can manage users and profile bindings; regular administrators can manage their own account details CLI maintenance commands: ```bash # Delete persisted login IP lock records hermes-web-ui clear-login-locks # Delete login locks and restart the running Web UI process hermes-web-ui clear-login-locks --restart # Create or reset the default super administrator login to admin / 123456 hermes-web-ui reset-default-login ``` `clear-login-locks` removes `${HERMES_WEB_UI_HOME:-~/.hermes-web-ui}/.login-lock.json`. If the server is running, restart it to clear in-memory lock state. `reset-default-login` updates the Web UI account database; if an `admin` user already exists, its password is reset to `123456` and the account is enabled as a super administrator. ### 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) - Profile and provider 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) ```bash npm install -g hermes-web-ui hermes-web-ui start ``` Open **http://localhost:8648** ### Docker Compose Single-container deployment with integrated Hermes Agent: ```bash # 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`](./docs/docker.md). ### Hermes Agent Runtime Discovery When Web UI starts backend chat features, it prefers a source checkout that contains `run_agent.py` such as `~/.hermes/hermes-agent`. If no source checkout is found, it falls back to the Python environment used by the installed `hermes` command, then the system Python. This supports both source installs and package installs such as `pip install hermes-agent`. ## Web UI Environment Variables These variables configure Hermes Web UI, its local Hermes runtime integration, and development/preview helpers. Provider API keys and Hermes Agent settings are normally managed through Hermes profiles; environment variables here are process-level overrides. | 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. | | `HERMES_WEBUI_STATE_DIR` | unset | Compatibility alias for `HERMES_WEB_UI_HOME`. | | `UPLOAD_DIR` | `$HERMES_WEB_UI_HOME/upload` | Upload root override. Files are stored below profile-scoped subdirectories. | | `CORS_ORIGINS` | `*` | Koa CORS origin setting. | | `AUTH_TOKEN` | auto-generated | Explicit bearer token. If unset, Web UI creates one under `HERMES_WEB_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` | `/opt/data/workspace` | 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_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://ekkolearnai.com` | OpenRouter attribution referer sent by bridge runs. | | `HERMES_OPENROUTER_APP_TITLE` | `Hermes Web UI` | OpenRouter attribution title sent by bridge runs. | | `HERMES_OPENROUTER_APP_CATEGORIES` | `cli-agent,personal-agent` | OpenRouter attribution categories sent by bridge runs. | | `HERMES_WEB_UI_MANAGED_GATEWAY` | platform/runtime dependent | Force managed legacy gateway process handling. Set `1`, `true`, `yes`, or `on` to enable. | | `HERMES_WEB_UI_STOP_GATEWAYS_ON_SHUTDOWN` | enabled in production | Controls whether Web UI shutdown also stops managed gateway processes. Set `0` or `false` to detach them. | | `GATEWAY_HOST` | `127.0.0.1` | Default gateway host written into profile config for legacy gateway compatibility. | | `HERMES_WEB_UI_PREVIEW_REPO` | package repository | GitHub repository used by Version Preview. | | `HERMES_WEB_UI_PREVIEW_AGENT_BRIDGE_TRANSPORT` | platform default | Version Preview broker transport. Set `tcp` to use loopback TCP for Preview on macOS/Linux; when unset, Preview follows `HERMES_AGENT_BRIDGE_WORKER_TRANSPORT=tcp`. | | `HERMES_WEB_UI_PREVIEW_AGENT_BRIDGE_ENDPOINT` | isolated preview endpoint | Directly overrides the Version Preview broker endpoint. | | `HERMES_WEB_UI_BACKEND_PORT` | `8648` | Backend port used by the Vite dev proxy. | | `HERMES_WEB_UI_FRONTEND_PORT` | `8649` | Frontend Vite dev server port. | ### 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: - Initializes Web UI data directories, local databases, and bundled skills - Starts the Hermes agent bridge used by `/chat-run` - Opens browser on successful startup --- ## Development ```bash git clone https://github.com/EKKOLearnAI/hermes-web-ui.git cd hermes-web-ui npm install npm run dev ``` - Frontend: http://localhost:8649 - BFF Server: http://localhost:8647 ```bash npm run build # outputs to dist/ ``` See [DEVELOPMENT.md](./DEVELOPMENT.md) for project development guidelines. ## 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 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 Socket.IO chat streaming, the Hermes agent bridge, profile-aware file upload and path-based download (multi-backend: local/Docker/SSH/Singularity), session CRUD, account- and profile-scoped management, 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 [![Star History Chart](https://api.star-history.com/svg?repos=EKKOLearnAI/hermes-web-ui&type=Date)](https://star-history.com/#EKKOLearnAI/hermes-web-ui&Date) ## License [BSL-1.1](./LICENSE)