mirror of
https://github.com/EKKOLearnAI/hermes-web-ui.git
synced 2026-05-27 22:40:18 +00:00
ekko
b9b99042a0
* refactor(docker): merge two-container setup into single container The Web UI already manages the Hermes Agent gateway lifecycle internally via GatewayManager (spawn hermes gateway run --replace), making the separate hermes-agent container redundant. The Dockerfile is built on the hermes-agent base image, so all CLI tooling is already included. - Remove hermes-agent service and shared volume from docker-compose.yml - Remove gateway port mapping (8642-8670) — internal-only now - Update docs/docker.md, README.md, README_zh.md for single-container setup Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs: remove version tag from image references Use ekkoye8888/hermes-web-ui instead of ekkoye8888/hermes-web-ui:latest to avoid pinning a specific version in documentation. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
280 lines
10 KiB
Markdown
280 lines
10 KiB
Markdown
<p align="center">
|
|
<strong>Hermes Web UI</strong>
|
|
<a href="./README_zh.md">中文</a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
A full-featured web dashboard for <a href="https://github.com/NousResearch/hermes-agent">Hermes Agent</a>.<br/>
|
|
Manage AI chat sessions, monitor usage & costs, configure platform channels,<br/>
|
|
schedule cron jobs, browse skills — all from a clean, responsive web interface.
|
|
</p>
|
|
|
|
<p align="center">
|
|
<code>npm install -g hermes-web-ui && hermes-web-ui start</code>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<img src="https://github.com/EKKOLearnAI/hermes-web-ui/blob/main/packages/client/src/assets/image1.png" alt="Hermes Web UI Demo" width="680"/>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<img src="https://github.com/EKKOLearnAI/hermes-web-ui/blob/main/packages/client/src/assets/image2.png" alt="Hermes Web UI Demo" width="680"/>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://www.npmjs.com/package/hermes-web-ui"><img src="https://img.shields.io/npm/v/hermes-web-ui?style=flat-square&color=blue" alt="npm version"/></a>
|
|
<a href="https://github.com/EKKOLearnAI/hermes-web-ui/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/hermes-web-ui?style=flat-square" alt="license"/></a>
|
|
<a href="https://github.com/EKKOLearnAI/hermes-web-ui/stargazers"><img src="https://img.shields.io/github/stars/EKKOLearnAI/hermes-web-ui?style=flat-square" alt="stars"/></a>
|
|
</p>
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
### AI Chat
|
|
|
|
- Real-time streaming via SSE with async run support
|
|
- Multi-session management — create, rename, delete, switch between sessions
|
|
- **Self-built session database** — local SQLite storage with automatic sync from Hermes state.db on first startup
|
|
- 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 global search across all conversations
|
|
- 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)
|
|
|
|
```bash
|
|
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
|
|
bash <(curl -fsSL https://raw.githubusercontent.com/EKKOLearnAI/hermes-web-ui/main/scripts/setup.sh)
|
|
```
|
|
|
|
### WSL
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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).
|
|
|
|
### 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
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
[](https://star-history.com/#EKKOLearnAI/hermes-web-ui&Date)
|
|
|
|
<!-- If the chart above doesn't load, visit https://star-history.com/#EKKOLearnAI/hermes-web-ui -->
|
|
|
|
## License
|
|
|
|
[BSL-1.1](./LICENSE)
|