hermes-web-ui/docs/docker.md

Docker Compose Guide

This repository ships an environment-variable driven Docker Compose setup.

Quick Start

Pull pre-built image (Recommended)

WEBUI_IMAGE=ekkoye8888/hermes-web-ui:latest docker compose up -d hermes-agent hermes-webui
docker compose logs -f hermes-webui

Open: http://localhost:6060

Build from source

docker compose up -d --build hermes-agent hermes-webui
docker compose logs -f hermes-webui

Services

This compose file runs two services:

• hermes-agent — Hermes Agent runtime (image: nousresearch/hermes-agent)
• hermes-webui — Web UI dashboard (pre-built image or built from source)

Environment Variables

All key runtime settings are configured from compose variables.

Variable	Default	Description
PORT	6060	Web UI listen port
BIND_HOST	0.0.0.0	Optional Web UI bind host. Defaults to IPv4 for stable WSL/Windows access. Set :: explicitly if you want IPv6 listening.
UPSTREAM	http://hermes-agent:8642	Hermes gateway URL (container internal)
HERMES_BIN	/opt/hermes/.venv/bin/hermes	Path to Hermes CLI binary
HERMES_AGENT_IMAGE	nousresearch/hermes-agent:latest	Hermes Agent base image
WEBUI_IMAGE	hermes-web-ui-local:latest	Web UI image (set to ekkoye8888/hermes-web-ui:latest to use pre-built)
HERMES_DATA_DIR	./hermes_data	Hermes runtime data directory
AUTH_DISABLED	false	Set to true to disable login authentication

Override variables directly from shell:

PORT=16060 \
AUTH_DISABLED=true \
docker compose up -d hermes-agent hermes-webui

Or create a .env file in the project root:

WEBUI_IMAGE=ekkoye8888/hermes-web-ui:latest
PORT=6060
AUTH_DISABLED=false

Data Persistence

Path	Description
${HERMES_DATA_DIR} (./hermes_data)	Hermes runtime data (sessions, config, profiles)
${HERMES_DATA_DIR}/hermes-web-ui	Web UI data (auth token, etc.)

• Hermes data persists in ./hermes_data, mapped to /home/agent/.hermes in the container.
• Web UI data persists in ./hermes_data/hermes-web-ui/, mapped to /root/.hermes-web-ui in the container.
• When AUTH_DISABLED=false, the auth token is auto-generated on first run and printed to container logs.
• Deleting the token file and restarting will generate a new one.

Port Mapping

Port	Service	Description
${PORT} (6060)	hermes-webui	Web UI dashboard
8642-8670	hermes-agent	Hermes Agent gateway ports (for multi-profile)

Code Runtime Behavior

• Server upstream comes from UPSTREAM env (packages/server/src/config.ts).
• Hermes CLI binary comes from HERMES_BIN env (packages/server/src/services/hermes-cli.ts).
• If HERMES_BIN is not provided, code falls back to hermes in PATH.
• Profile switching dynamically resolves upstream URLs via GatewayManager — the UPSTREAM env only sets the default profile gateway.

Common Operations

Recreate webui:

docker compose up -d --no-deps --force-recreate hermes-webui

View auth token:

docker compose logs hermes-webui | grep token
# or
cat ./hermes_data/hermes-web-ui/.token

Stop:

docker compose down