Skip to content

docker.md

Latest commit

 

History

History
105 lines (72 loc) · 3.35 KB

docker.md

File metadata and controls

105 lines (72 loc) · 3.35 KB
Raw

Docker Compose Guide

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

Quick Start

Pull pre-built image (Recommended)

UI_IMAGE=pythoughtslabs/hermes-ui docker compose up -d
docker compose logs -f hermes-ui

Open: http://localhost:6060

Build from source

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

Services

This compose file runs a single service:

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

The 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 UI listen port
BIND_HOST 0.0.0.0 Optional 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)
UI_IMAGE hermes-ui-local:latest UI image (set to pythoughtslabs/hermes-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:

UI_IMAGE=pythoughtslabs/hermes-ui
PORT=6060

Data Persistence

Path Description
${HERMES_DATA_DIR} (./hermes_data) Hermes runtime data (sessions, config, profiles)
${HERMES_DATA_DIR}/hermes-ui UI data (auth token, etc.)
  • Hermes data persists in ./hermes_data, mapped to /home/agent/.hermes in the container.
  • UI data persists in ./hermes_data/hermes-ui/, mapped to /home/agent/.hermes-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) 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: 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-ui | grep token
# or
cat ./hermes_data/hermes-ui/.token

Stop:

docker compose down