Hermes Dashboard

Web-based admin dashboard for Hermes Agent gateway. Full configuration and control without CLI.

Features

Design

• Linear-inspired dark theme (#08090a canvas, Inter font, cv01 + ss03 OpenType features)
• All dialogs are dark-themed custom modals (no native prompt()/confirm())
• Single HTML file, no build step, no dependencies

Security

• Path traversal prevention on all file operations
• Atomic file writes (temp file + os.replace)
• XSS protection (HTML entity + single-quote escaping)
• Secret auto-masking (TOKEN/KEY/SECRET/PASSWORD patterns)
• Input validation on all endpoints (regex-based)
• Referrer policy (no-referrer) to prevent API key leakage
• All /api/dashboard/* routes require API_SERVER_KEY (Bearer token, constant-time compare). Without the key set, they return 503 and serve nothing.

These routes can write .env, restart the gateway, create cron jobs, and read session contents. Do not expose the gateway port through a tunnel or reverse proxy without setting API_SERVER_KEY first.

Installation

Quick Install

git clone https://github.com/chrisryugj/hermes-dashboard.git
cd hermes-dashboard
./install.sh

The installer:

1. Copies dashboard files to ~/.hermes/dashboard/
2. Patches api_server.py to register dashboard routes
3. Enables API server in .env

Then restart your gateway:

# launchd
launchctl kickstart -k gui/$(id -u)/ai.hermes.gateway

# or manual
hermes gateway restart

Access: http://localhost:8642/dashboard

Manual Install

1. Copy files:

mkdir -p ~/.hermes/dashboard
cp hermes_dashboard/api.py ~/.hermes/dashboard/
cp hermes_dashboard/index.html ~/.hermes/dashboard/

2. Add to ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_PORT=8642

3. Patch api_server.py (find # Start background sweep line and add before it):

# Dashboard plugin
try:
    import sys as _sys
    _hermes_home = os.path.expanduser("~/.hermes")
    if os.path.join(_hermes_home, "dashboard") not in _sys.path:
        _sys.path.insert(0, os.path.join(_hermes_home, "dashboard"))
    from api import register_dashboard_routes
    register_dashboard_routes(self._app)
    logger.info("[%s] Dashboard registered at /dashboard", self.name)
except Exception as _dash_err:
    logger.debug("[%s] Dashboard not loaded: %s", self.name, _dash_err)

Authentication

Set API_SERVER_KEY in .env for token-based auth:

API_SERVER_KEY=your-secret-key

Access with: http://localhost:8642/dashboard?key=your-secret-key

macOS Menu Bar Monitor (Optional)

pip install rumps
python3 ~/.hermes/dashboard/monitor.py

Shows gateway status in macOS menu bar with quick actions (dashboard, restart, logs).

Supported Models

The model selector supports these providers:

MCP Server Setup

Paste Config (Easiest)

Click Paste Config and paste your existing MCP config from Claude Desktop, Cursor, or VS Code:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server/index.js"],
      "env": { "API_KEY": "xxx" }
    }
  }
}

All formats accepted: mcpServers, mcp_servers, or direct server objects.

Manual Add

Click + Add and fill in name, command, args (JSON array), and optional env (JSON object).

Requirements

• Hermes Agent v0.7.0+
• Python 3.10+ with PyYAML and aiohttp (included with Hermes)
• macOS menu bar monitor requires rumps (pip install rumps)

License

MIT