atomk-hermes-skills/skills/cross-border-ecommerce/hermes-web-ui-setup/SKILL.md

name, description, version

name	description	version
hermes-web-ui-setup	Install and run both Hermes Web UI projects — nesquena/hermes-webui (chat interface) and joeynyc/hermes-hudui (monitoring dashboard)	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

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

Key .env Settings

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)

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

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

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:

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:

# 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:

# 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:

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

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:

git config http.postBuffer 524288000

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