Hermes Control Interface

A self-hosted web dashboard for the Hermes AI agent stack. Manage agents, chat, terminals, files, cron, token analytics, MCP servers, and swarm pipelines — behind a password gate.

Stack: Vanilla JS + Vite · Node.js · Express · WebSocket · xterm.js · Chart.js · better-sqlite3
Version: 3.6.1 · License: MIT

Quick Start

git clone https://github.com/xaspx/hermes-control-interface.git
cd hermes-control-interface
cp .env.example .env     # set HERMES_CONTROL_PASSWORD + HERMES_CONTROL_SECRET
npm install && npm run build
node server.js            # → http://localhost:10274

See docs/INSTALL.md for production setup, nginx, and systemd.

Overview

Screenshots

Core Pages · Dark Mode

Home	Chat	Office
Agents	MCP Manager	Usage

Agent Detail Pages

Dashboard	Sessions	Gateway
Config	Memory	Skills

Features

Office v3 — ZOO Swarm Monitor

Three-panel dashboard with zero-subprocess agent states (~100ms vs 3000ms):

• Agents Panel — health grid via config.yaml + kanban.db
• Kanban Panel — 8 status lanes (triage→done), dependency arrows, board switcher
• Live Feed — 50 events from gateway logs, agent filter dropdown, keyword search
• Task Popup — expandable run history, workspace file browser, event enrichment, timeline, load-more

Chat

• Real-time streaming via WebSocket gateway API
• Multi-profile support with profile switcher
• Tool call cards with collapsible JSON viewer
• Stop button, session resume, fork from message

MCP Manager

Full operational control plane — list, start, stop, restart MCP servers. Live log tail and config editor from the browser. 11 REST API routes.

Security

• CSP without unsafe-eval, CSRF on all mutating endpoints
• Rate limiting (global + chat), WebSocket RBAC
• Path traversal prevention, XSS protection
• 20 permissions across 3 roles (admin, viewer, custom)
• Profile-based access isolation — restrict users to specific agent profiles

Profile-Based Access Control

Multi-agent teams can restrict which profiles (agents) each user can see and manage:

// User creation with profile restriction
createUser('cx-team', 'password', 'custom', ['jorah']);     // only sees Jorah
createUser('influencer-team', 'password', 'custom', ['varys']); // only sees Varys  
createUser('admin', 'password', 'admin', ['*']);             // sees all agents

• allowed_profiles field on each user (["*"] = full access, ["jorah", "varys"] = specific agents)
• Filters /api/profiles, /api/office/agent-states, and all :profile endpoints
• requireProfileAccess middleware on gateway, config, and keys routes
• Profile selection UI in the Create User form (checkboxes for available agents)
• Nav tabs hidden based on user permissions (Files, Maintenance = admin only)

PWA

Installable to homescreen. Service worker with offline caching. Auto-update on new version.

Architecture

Browser (11 pages, SPA)
       │
   HTTPS :10274
       │
   Express Server (server.js — monolithic, ~6K+ lines)
       ├── Auth (bcrypt, sessions, CSRF)
       ├── RBAC (20 permissions, 3 roles)
       ├── REST API (30+ routes)
       ├── WebSocket (real-time)
       │
       ├── Hermes CLI (agent states, gateway control)
       ├── SQLite (kanban.db — task pipeline)
       ├── Filesystem (config.yaml, logs, skills)
       └── External (MCP servers, token pricing)

Full architecture: docs/ARCHITECTURE.md

API

Full API: docs/API.md

Configuration

Full config: docs/CONFIG.md

Requirements

• Node.js 20+
• Hermes Agent installed on the same machine
• hermes CLI available on PATH

Updating

git pull upstream main
npm install
npm run build
# Restart your HCI service (adjust service name):
systemctl restart hci-staging

See docs/DEPLOY.md for zero-downtime deploys.

Documentation

Built for the Hermes Agent ecosystem.
GitHub

❓ Frequently Asked Questions

General

Q: What is Hermes Control Interface (HCI)?

HCI is a self-hosted web dashboard for the Hermes AI agent stack. Manage agents, chat, terminals, files, cron, token analytics, MCP servers, and swarm pipelines — all behind a password gate.

Q: What can I manage with HCI?

| Page | Capabilities | |---|---|---| | Home | System health, agent overview, gateway status, token usage | | Chat | Real-time streaming, tool call cards, multi-profile | | Workspace | Browse, edit files and chat with Hermes scoped to a project directory | | Agents | Profile CRUD, gateway lifecycle, dashboard/sessions/cron | | Office | 3-panel swarm monitor — agent health, kanban, live feed | | Monitor | Gateway logs, CPU/RAM metrics, live process view | | Usage | Token analytics, daily trends, cost projections, alerts | | Logs | Agent/error/gateway logs with level filter | | Skills | Browse, install, remove Hermes skills | | Files | Browse and edit server files | | MCP | Start, stop, restart MCP servers, log tail, config editor | | Maintenance | Backup, restore, HCI update, system doctor |

Features

Q: What is Office v3 — ZOO Swarm Monitor?

Three-panel dashboard with zero-subprocess agent states (~100ms vs 3000ms):

• Agents Panel — health grid via config.yaml + kanban.db
• Kanban Panel — 8 status lanes (triage→done), dependency arrows
• Live Feed — 50 events from gateway logs, agent filter, keyword search
• Task Popup — run history, workspace file browser, event enrichment

Q: What chat features are available?

Q: What is MCP Manager?

Full operational control plane for MCP servers:

• List, start, stop, restart servers
• Live log tail from browser
• Config editor (JSON/YAML)
• 11 REST API routes

Installation

Q: How do I install HCI?

git clone https://github.com/xaspx/hermes-control-interface.git
cd hermes-control-interface
cp .env.example .env     # set HERMES_CONTROL_PASSWORD + HERMES_CONTROL_SECRET
npm install && npm run build
node server.js            # → http://localhost:10274

See docs/INSTALL.md for full setup.

Q: What are the requirements?

• Node.js 20+
• Hermes Agent installed on same machine
• hermes CLI available on PATH

Q: How do I update HCI?

git pull upstream main
npm install
npm run build
# Restart your HCI service (adjust service name):
systemctl restart hci-staging

Tech Stack

Q: What technologies does HCI use?

Security

Q: What security features are included?

PWA

Q: Can I install HCI as a PWA?

Yes!

• Installable to homescreen
• Service worker with offline caching
• Auto-update on new version

Configuration

Q: What environment variables are required?

See docs/CONFIG.md for full list.

API

Q: What REST API endpoints are available?

See docs/API.md for full reference.

Architecture

Q: What is the HCI architecture?

Browser (11 pages, SPA)
       │
   HTTPS :10274
       │
   Express Server (server.js — monolithic, ~6K+ lines)
       ├── Auth (bcrypt, sessions, CSRF)
       ├── RBAC (20 permissions, 3 roles)
       ├── REST API (30+ routes)
       ├── WebSocket (real-time)
       │
       ├── Hermes CLI (agent states, gateway control)
       ├── SQLite (kanban.db — task pipeline)
       ├── Filesystem (config.yaml, logs, skills)
       └── External (MCP servers, token pricing)

See docs/ARCHITECTURE.md for details.

Documentation

Q: Where can I find more documentation?

Community & Support

License

Q: Is Hermes Control Interface free and open source?

Yes! MIT License - see LICENSE. Self-host for free, manage your Hermes agent stack with a beautiful web UI.