hermes-web-ui

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 custom OpenAI-compatible providers
• Provider-level model grouping

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)
• 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:

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
• The web UI service is built from this repository's Dockerfile
• All runtime settings are environment-variable driven in docker-compose.yml

Override compose variables directly from command line (no .env file required):

PORT=16060 \
UPSTREAM=http://127.0.0.1:8642 \
HERMES_BIN=/opt/hermes/.venv/bin/hermes \
docker compose up -d --build hermes-agent hermes-webui

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, 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)

License

MIT