Hermes Control Plane

A local, single-page operations console for Hermes Agent. The app is a small zero-dependency Node.js server that serves the UI and shells out to a Hermes CLI installation.

What It Does

• Lists OAuth/API-key provider pools.
• Displays account identity/email data when it can be derived from Codex, Claude, Gemini, or Hermes JWT-backed auth state.
• Edits Hermes model/fallback configuration.
• Provides panes for skills, plugins, bundles, MCP, cron, sessions, hooks, memory, kanban, webhooks, profiles, storage, config, tools, insights, security, and system status.

Run With Docker Compose

cp .env.example .env
docker compose up --build -d
docker compose logs -f

Open:

Control plane: http://127.0.0.1:7843
Pre-Hermes AI API: http://127.0.0.1:8645/v1
Post-Hermes AI API: http://127.0.0.1:8646/v1

Deploy With Portainer Git Stack

Use Portainer's Git-backed Stack flow:

1. Push this repo to Git.
2. In Portainer, create a Stack from a Git repository.
3. Set the Compose path to docker-compose.yml.
4. Add the environment variables from .env.example, adjusted for your server.
5. Enable Portainer's auto-update option, either polling or webhook.

Portainer pulls the latest Git version when it redeploys the Stack. A normal Docker container restart does not pull Git or rebuild the image by itself, so use Portainer's webhook/polling redeploy for updates.

HERMES_CONTAINER_USER defaults to 0:0 so the container can write credentials/config into Portainer-created bind directories. If you pre-create the host directories and chown them to UID/GID 1000:1000, you can set HERMES_CONTAINER_USER=1000:1000.

Recommended persistent host layout on the Portainer host:

/opt/hermes-control-plane/hermes
/opt/hermes-control-plane/codex
/opt/hermes-control-plane/claude
/opt/hermes-control-plane/gemini

The pre/post AI API services both use Hermes' native OpenAI-compatible proxy:

hermes proxy start --provider <provider> --host 0.0.0.0 --port <port>

Set these in Portainer if you want different ports or providers:

HERMES_PRE_AI_API_PORT=8645
HERMES_PRE_AI_PROVIDER=nous
HERMES_POST_AI_API_PORT=8646
HERMES_POST_AI_PROVIDER=nous

Run hermes proxy providers in the Hermes environment to see supported provider names. This Hermes build reports nous and xai.

Copy your Codex auth files into:

/opt/hermes-control-plane/codex/auth.json
/opt/hermes-control-plane/codex/authEmma.json
/opt/hermes-control-plane/codex/authMom.json

Copy Claude OAuth/auth state into:

/opt/hermes-control-plane/claude

Copy Gemini OAuth/config state into:

/opt/hermes-control-plane/gemini

Runtime Requirements

The container is Linux. It can only execute a Linux-compatible Hermes install at:

/home/hermes/.hermes/hermes-agent/venv/bin/hermes

If you are on macOS, your local ~/.hermes venv contains a macOS Python binary and cannot run inside this Linux container. Use a Linux Hermes home, or run the compose bundle on the Linux Hermes host/LXC.

The default .env.example mounts:

• Hermes state from /opt/hermes-control-plane/hermes
• Codex auth/config from /opt/hermes-control-plane/codex to /home/hermes/.codex
• Claude auth/config from /opt/hermes-control-plane/claude to /home/hermes/.claude
• Gemini auth/config from /opt/hermes-control-plane/gemini to /home/hermes/.gemini

Local Node Run

If Hermes is installed directly on the same OS as Node:

node server.cjs

The default local URL is:

http://127.0.0.1:7843

Useful Commands

npm run check
npm test
docker compose config
docker compose down