yaoyao-webui/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 docker compose up -d
docker compose logs -f hermes-webui

Open: http://localhost:6060

Build from source

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

Services

This compose file runs a single service:

• hermes-webui — Web UI dashboard with integrated Hermes Agent runtime (pre-built image or built from source)

The Web UI container is built on the nousresearch/hermes-agent base image and uses the Hermes CLI / agent bridge runtime for chat execution. By default it performs startup gateway checks/autostart for profiles, but no Hermes gateway ports are exposed by this compose setup.

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.
CORS_ORIGINS	same host only	Comma- or space-separated cross-origin allowlist for HTTP, Socket.IO, and WebSocket requests. Set * only when you intentionally need legacy wildcard CORS.
HERMES_BIN	/opt/hermes/.venv/bin/hermes	Path to Hermes CLI binary
HERMES_AGENT_IMAGE	nousresearch/hermes-agent:latest	Hermes Agent base image (used only during build)
WEBUI_IMAGE	hermes-web-ui-local:latest	Web UI image (set to ekkoye8888/hermes-web-ui to use pre-built)
HERMES_DATA_DIR	./hermes_data	Hermes runtime data directory

Override variables directly from shell:

PORT=16060 docker compose up -d

Or create a .env file in the project root:

WEBUI_IMAGE=ekkoye8888/hermes-web-ui
PORT=6060

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 /home/agent/.hermes-web-ui in the container.
• 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	Description
${PORT} (6060)	Web UI dashboard

No Hermes gateway ports are exposed by this compose setup.

Code Runtime Behavior

• 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-specific chat runs are handled through the Hermes agent bridge. The selected/requested profile is authorized per account and passed with runtime requests; switching the frontend Hermes Profile does not restart the bridge or clear other running tasks.
• Docker is a managed gateway runtime: Web UI checks profile gateways on startup, but it does not run a periodic gateway recovery loop.

Common Operations

Recreate:

docker compose up -d --force-recreate

View auth token:

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

Stop:

docker compose down