---
name: hermes-web-ui-setup
description: Install and run both Hermes Web UI projects — nesquena/hermes-webui (chat interface) and joeynyc/hermes-hudui (monitoring dashboard)
version: 1.0
---

# Hermes Web UI — Installation & Setup

Two complementary Web UIs for the Hermes AI Agent, running on separate ports.

## Environment

- Server: Ubuntu Linux, Python 3.11+, Node.js 18+
- Hermes data: `~/.hermes/`
- Both projects cloned to Gitea: `https://gitea9webs.sh3.ikuai7.com/admin9webs/`

## Project 1: hermes-webui (Chat Interface) — Port 8787

**Repo:** `https://github.com/nesquena/hermes-webui` (★6250)  
**Gitea:** `https://gitea9webs.sh3.ikuai7.com/admin9webs/hermes-webui`  
**Tech:** Python backend + vanilla JS frontend, no build step

### Install & Run

```bash
cd /home/ubuntu/hermes-webui
cp .env.example .env
# Edit .env with host/port/password
python3 bootstrap.py --no-browser
```

### Key .env Settings

```bash
HERMES_WEBUI_HOST=0.0.0.0    # Bind to all interfaces for remote access
HERMES_WEBUI_PORT=8787
HERMES_HOME=/home/ubuntu/.hermes
HERMES_WEBUI_PASSWORD=xxx     # REQUIRED if binding 0.0.0.0 — otherwise 401 warning
```

### ⚠️ Pitfalls

- **No password on 0.0.0.0** = anyone can access your agent and filesystem. Always set `HERMES_WEBUI_PASSWORD`.
- **No build step** — bootstrap.py handles everything, just needs pyyaml.
- **Background launch**: Use `terminal(background=true)` + env vars inline, NOT `nohup &` (Hermes blocks shell backgrounding).
- Password auth returns 401 on `/api/sessions` without credentials — this confirms it's working.

## Project 2: hermes-hudui (Monitoring Dashboard) — Port 3001

**Repo:** `https://github.com/joeynyc/hermes-hudui` (★1394)  
**Gitea:** `https://gitea9webs.sh3.ikuai7.com/admin9webs/hermes-hudui`  
**Tech:** FastAPI backend + React/Vite/Tailwind frontend, requires build step

### Install (manual steps)

```bash
cd /home/ubuntu/hermes-hudui

# 1. Create venv & install backend
python3 -m venv venv
source venv/bin/activate
pip install -e .

# 2. Build frontend
cd frontend
npm install
npm run build
cd ..

# 3. Copy frontend build to static serving dir
mkdir -p backend/static/assets
cp frontend/dist/index.html backend/static/
cp frontend/dist/assets/* backend/static/assets/
```

### Run

```bash
cd /home/ubuntu/hermes-hudui
source venv/bin/activate
HERMES_HOME=/home/ubuntu/.hermes hermes-hudui --port 3001
```

### ⚠️ Pitfalls

- **Must build frontend first** — without `npm run build` + copy to `backend/static/`, the dashboard serves nothing.
- **Vite build output filenames have hashes** (e.g., `index-CULqjDQ_.js`) — copy ALL files from `dist/assets/`, not just specific ones.
- **Old build files may linger** — `backend/static/assets/` may have stale JS from previous builds; clean before copying.
- **Health endpoint**: `/api/health` (not `/health`) returns full diagnostics JSON.
- **Minor DB issue**: `tool_calls` table may be missing — harmless, dashboard still works.
- **v0.9.0+ requires `cryptography`**: New Replay feature uses `backend.services.replay_signer` which imports `cryptography.exceptions.InvalidSignature`. If missing, startup crashes with `ModuleNotFoundError: No module named 'cryptography'`. Fix: `pip install cryptography` in the venv. Always check for new deps after `git pull`.
- **stash pop conflicts on `backend/static/index.html`**: This file has hash-based asset references that differ between builds. On merge conflict, always take the upstream version: `git checkout upstream/main -- backend/static/index.html`.

## Running Both Simultaneously

| Project | Port | Purpose |
|---------|------|---------|
| hermes-webui | 8787 | Chat with Hermes (browser-based CLI) |
| hermes-hudui | 3001 | Monitor Hermes (18-tab dashboard) |

Use `terminal(background=true)` for each, with inline env vars. Kill existing processes on a port with `fuser -k PORT/tcp`.

## Updating from GitHub Upstream

When local code falls behind GitHub upstream:

### hermes-webui
```bash
cd /home/ubuntu/hermes-webui
git pull origin master
# Then restart service (see below)
```

### hermes-hudui
Origin points to Gitea, so add GitHub as upstream:
```bash
cd /home/ubuntu/hermes-hudui
git remote add upstream https://github.com/joeynyc/hermes-hudui.git 2>/dev/null
git fetch upstream main
# Stash local changes first if any
git stash
git merge upstream/main
git stash pop  # May conflict on backend/static/index.html — use upstream version
git checkout upstream/main -- backend/static/index.html  # If conflict
git add backend/static/index.html
```

### ⚠️ After updating, always reinstall dependencies
New versions may add Python dependencies. Check if the service starts cleanly:
```bash
# hudui example: v0.9.0 added 'cryptography' — install in venv
cd /home/ubuntu/hermes-hudui && source venv/bin/activate && pip install cryptography
```

## Restarting Services

Both run as background processes. Kill old ones first, then relaunch:

```bash
# Find and kill old processes
ps aux | grep -E "hermes.*(webui|hudui)" | grep -v grep
kill <PIDs>

# Restart webui
# terminal(background=true):
cd /home/ubuntu/hermes-webui && source .env 2>/dev/null; export HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PORT=8787 HERMES_HOME=/home/ubuntu/.hermes HERMES_WEBUI_PASSWORD='xxx'; python3 bootstrap.py --no-browser

# Restart hudui
# terminal(background=true):
cd /home/ubuntu/hermes-hudui && source venv/bin/activate && HERMES_HOME=/home/ubuntu/.hermes hermes-hudui --port 3001
```

Verify after restart:
```bash
curl -sk -o /dev/null -w "%{http_code}" http://127.0.0.1:8787/  # Expect 302 (redirect to login)
curl -sk -o /dev/null -w "%{http_code}" http://127.0.0.1:3001/  # Expect 200
```

## Gitea Mirror Push

Push to Gitea with auth in URL (credential-less push fails):
```bash
git push https://admin9webs:Tt123456!@gitea9webs.sh3.ikuai7.com/admin9webs/hermes-webui.git master
git push https://admin9webs:Tt123456!@gitea9webs.sh3.ikuai7.com/admin9webs/hermes-hudui.git main
```

For large repos, increase http buffer:
```bash
git config http.postBuffer 524288000
```

The `hermes-web-ui` repo (empty, labeled "EKKOLearnAI") was deleted via `DELETE /api/v1/repos/admin9webs/hermes-web-ui`.