Hermes WebUI

Process monitoring and configuration dashboard for Hermes Agent.

Features

• Dashboard — Real-time activity feed with session list, gateway status, platform/service health, cost tracking, and model distribution
• Sessions — Browse, search (FTS5), and inspect full conversation histories with message-level detail
• Config — View config.yaml and environment variables (read-only for safety)
• Cron — View and manage scheduled agent jobs
• Skills — Browse built-in and custom skills with full source inspection
• Responsive — Mobile-friendly layout with hamburger menu
• Dark/Light theme — Toggle between themes
• Real-time updates — WebSocket-based polling bridge, no agent code modification needed

Screenshots

Dashboard	Sessions

Config	Cron Jobs

Skills

Requirements

• Python 3.11+
• Node.js 18+ (for frontend build only)
• A running Hermes Agent installation at ~/.hermes/

Installation

1. Clone the repository

git clone https://github.com/sanchomuzax/hermes-webui.git
cd hermes-webui

2. Set up Python environment

python3 -m venv venv
source venv/bin/activate
pip install -e .

3. Build the frontend

cd frontend
npm install
npx vite build
cd ..

4. Run

hermes-webui

Or directly:

python -m webui

Output:

Starting Hermes WebUI at http://0.0.0.0:8643
Auth token: <your-auth-token>

5. Log in

Open http://<your-host>:8643 in a browser and paste the auth token shown in the console output.

The token is generated once and stored in ~/.hermes/auth.json. To retrieve it later:

python3 -c "import json; print(json.load(open('$HOME/.hermes/auth.json'))['webui_token'])"

Configuration

Environment Variable	Default	Description
HERMES_HOME	~/.hermes	Hermes Agent installation directory
HERMES_WEBUI_HOST	0.0.0.0	Bind address
HERMES_WEBUI_PORT	8643	Port

CLI flags

Flag	Description
--localhost	Bind to 127.0.0.1 only (not accessible from LAN)
--port PORT	Override the default port

Running as a systemd service

Create /etc/systemd/system/hermes-webui.service:

[Unit]
Description=Hermes WebUI
After=network.target

[Service]
Type=simple
User=YOUR_USER
WorkingDirectory=/home/YOUR_USER/.hermes/hermes-webui
ExecStart=/home/YOUR_USER/.hermes/hermes-webui/venv/bin/python -m webui
Restart=on-failure
RestartSec=5
Environment=HERMES_HOME=/home/YOUR_USER/.hermes

[Install]
WantedBy=multi-user.target

Then enable and start:

sudo systemctl daemon-reload
sudo systemctl enable hermes-webui
sudo systemctl start hermes-webui

Check status:

sudo systemctl status hermes-webui
journalctl -u hermes-webui -f

Note: When running as a service, the auth token is not printed to your terminal. Retrieve it from ~/.hermes/auth.json as shown above.

Architecture

┌─────────────────────────────────────────┐
│  React Frontend (Vite + TailwindCSS)    │
│  SPA with TanStack Query + WebSocket    │
└────────────────┬────────────────────────┘
                 │ HTTP + WS
┌────────────────┴────────────────────────┐
│  FastAPI Backend (Python)               │
│  ├─ REST API (sessions, config, cron)   │
│  ├─ WebSocket hub (live events)         │
│  └─ Polling bridge (state.db + files)   │
└────────────────┬────────────────────────┘
                 │ SQLite (read-only) + YAML
┌────────────────┴────────────────────────┐
│  Hermes Agent (unmodified)              │
│  state.db, config.yaml, gateway_state   │
└─────────────────────────────────────────┘

Hermes WebUI reads from the agent's data files without modifying the agent's core code.

Tech Stack

• Backend: Python 3.11+, FastAPI, Uvicorn, Pydantic, PyYAML
• Frontend: React 19, TypeScript, Vite, TailwindCSS 4, TanStack Query
• Data: SQLite (read-only from Hermes Agent's state.db)

Pages

Page	Description
Dashboard	KPI cards (sessions, messages, cost, gateway), platform badges, activity feed with live session list, model distribution
Sessions	Paginated session list with FTS5 search, source filter tabs, click into any session to view full message history
Config	Read-only view of config.yaml sections and .env variables (sensitive values masked)
Cron	List of scheduled cron jobs with status, schedule, and prompt preview
Skills	Grid of built-in and custom skills with description, click to view full source

Troubleshooting

"Cannot connect to server" on login

• Make sure the WebUI server is running
• If accessing from another machine, ensure the server is bound to 0.0.0.0 (default), not 127.0.0.1

Dashboard shows no sessions

• Verify Hermes Agent has been used at least once (check ~/.hermes/state.db exists)
• The WebUI reads state.db in read-only mode — if the agent is actively writing, there may be a brief WAL lock delay

Activity Feed not updating

• The polling bridge checks state.db every 3 seconds
• Ensure the WebSocket connection shows "Connected" (green dot in the header)

Related

• Hermes Agent — The AI agent this UI monitors
• OpenClaw Web UI — Inspiration for the dashboard design

Built With

This project was vibe-coded with Claude Code (Claude Opus 4.6).

License

MIT