Hermes WebUI Installation and Configuration Issues

Pitfall 1: "Connection lost" Error When Web UI Can't Reach Hermes Gateway

**What happens**: You open Hermes WebUI in the browser, but it shows Error: Connection lost and keeps retrying every few seconds without connecting.

**Root cause**: Hermes WebUI needs the Hermes Gateway running first. Gateway binds to port 8787 by default. If Gateway isn't running, or if Docker port mapping is wrong, Web UI simply can't reach it.

Fix:

# Start Hermes Gateway first (background)
python -m hermes_cli.main gateway &
# Or with systemd
systemctl --user start hermes-gateway

# Verify Gateway is healthy
curl http://localhost:8787/health
# Should return JSON status

# Then start Hermes WebUI
cd hermes-webui
python3 bootstrap.py --host 0.0.0.0

If using Docker Compose, make sure Gateway and WebUI share the same network and ports are correctly mapped:

services:
  hermes-gateway:
    image: nousresearch/hermes-agent
    ports:
      - "8787:8787"  # Gateway API
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

  hermes-webui:
    image: ghcr.io/nesquena/hermes-webui
    ports:
      - "3000:3000"  # Web UI
    environment:
      - HERMES_GATEWAY_URL=http://hermes-gateway:8787
    depends_on:
      - hermes-gateway

**Prevention**: Always confirm Gateway is Running before starting Web UI. Use a startup script:

#!/bin/bash
python -m hermes_cli.main gateway &
sleep 3
python3 bootstrap.py --host 0.0.0.0

Pitfall 2: Password Verification Loop on Web UI

**What happens**: Browser prompts for password. You enter the password set via HERMES_WEBUI_PASSWORD, page refreshes, and asks for password again — infinite loop.

**Root cause**: Hermes WebUI v0.50.x uses PBKDF2 key storage. The first time you set a password it generates two files: ~/.hermes/webui/.pbkdf2_key and ~/.hermes/webui/.signing_key. If you later update the password in .env but don't delete these files, Web UI still validates against the old key.

Fix:

# Stop Web UI first
# Remove old key files
rm -rf ~/.hermes/webui/.pbkdf2_key ~/.hermes/webui/.signing_key

# Confirm .env password is correct
cat ~/.hermes/config.yaml | grep -A5 'webui:'
# Should show:
# password: your_password

# Restart Web UI
python3 bootstrap.py --host 0.0.0.0

Another common cause: running Gateway via systemd with password set via systemctl set-environment — the env var never reaches the Docker container process. Pass it in the systemd unit Environment= field instead:

[Service]
Environment="HERMES_WEBUI_PASSWORD=letmein"
Environment="HERMES_GATEWAY_URL=http://localhost:8787"
ExecStart=/usr/bin/python3 /usr/local/bin/bootstrap.py --host 0.0.0.0

Pitfall 3: Port Conflict Prevents Web UI Startup

**What happens**: Error: Port 3000 is already in use, Web UI fails to start.

**Root cause**: Hermes WebUI defaults to port 3000, but your server may already have Node.js apps, Nginx, or other services on that port.

Fix:

# Check what's using port 3000
lsof -i :3000
# or
ss -tlnp | grep 3000

# Override with --port flag
python3 bootstrap.py --host 0.0.0.0 --port 8080

# Persist: add to .env
echo "PORT=8080" >> ~/.hermes/webui/.env

For Nginx reverse proxy setups:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Pitfall 4: Profile Switch Makes Conversations "Disappear"

**What happens**: You switch Profile in Web UI (e.g., from default to work), and all previous conversations vanish. You think data is lost — but it's a display issue.

Root cause: Hermes Agent's Profile model (configuration namespace) and Web UI's session management don't align intuitively. Profile contains independent config (provider, API key, memory container), but Web UI uses Profile as a session namespace isolator. When you switch Profile, you're genuinely in a new session context with no shared history.

How it actually works:

• Each Profile has its own session list — they don't cross-pollinate
• There's no "shared" conversation across Profiles
• To move a conversation between Profiles, export the Session ID and import into target Profile

Practical workflow:

• Plan your Profile structure before you start using Web UI
• Avoid frequent Profile switches mid-workflow
• If you need to preserve a conversation, use `Export Session` before switching

Pitfall 5: API Key Format Error Causes "Invalid API key"

**What happens**: Connecting Hermes Agent to Open WebUI or another client fails with Invalid API key, even though the key copied from Anthropic Console is correct.

Root cause: Two common mistakes:

1. **Bearer token format mismatch**: Some clients expect Authorization: Bearer sk-ant-..., but Hermes Gateway actually expects Authorization: Bearer anthropic-api-key: sk-ant-... (with prefix)

2. **Env var not passed into Docker**: If Gateway runs in Docker but ANTHROPIC_API_KEY wasn't passed via -e or env_file, Gateway sees an empty key

Fix:

Check env var is correctly passed:

# Host verification
echo $ANTHROPIC_API_KEY
# Should return key starting with sk-ant-

# Inside Docker
docker exec  env | grep ANTHROPIC

Create a .env file for Docker Compose:

ANTHROPIC_API_KEY=sk-ant-your-key-here

Then reference it in docker-compose.yml:

services:
  hermes-gateway:
    image: nousresearch/hermes-agent:v0.14.0
    env_file:
      - .env
    ports:
      - "8787:8787"

For Open WebUI connection, use this exact config:

URL: http://YOUR_SERVER_IP:8787
API Key: sk-ant-your-key-here  # No Bearer prefix, just the key itself
Model: claude-sonnet-4-20250514  # or your configured model

Pre-Launch Checklist

Run these commands to confirm a healthy setup:

# 1. Gateway health
curl http://localhost:8787/health
# Expect: {"status": "ok", "version": "0.14.x"}

# 2. Web UI accessible
curl http://localhost:3000/
# Expect: HTML page returned

# 3. API models list
curl http://localhost:8787/v1/models \
  -H "Authorization: Bearer sk-ant-your-key-here"
# Expect: list of configured models

# 4. Firewall open
sudo ufw status | grep -E '3000|8787'
# Expect: ALLOW entries

Summary

Hermes WebUI completes the Hermes Agent experience, bringing it closer to ChatGPT-level usability. The 5 traps that cost me 3 days:

1. Gateway not running before Web UI → Connection lost

2. Password changed but old key files not deleted → Password loop

3. Port 3000 occupied → Startup failure

4. Profile/session isolation not understood → "Disappearing" conversations

5. Env vars not reaching Docker → Invalid API key

Work through them in order and you'll be up and running in under 10 minutes.

👉 Quick AI Agent setup? Try MiniMax — accessible from China, good value Token plans:

https://platform.minimaxi.com/subscribe/token-plan?code=E5yur9NOub&source=link

Related articles:

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews