Hermes WebUI — Docker Compose Examples

Working Docker Compose configurations for deploying Hermes WebUI — single, dual, and three-container setups. Each variant is tested and matches the architecture described in the HermesDocker setup guide.

Quick Start

git clone https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent
cp .env.example .env   # edit API keys + set WANTED_UID/WANTED_GID
docker compose up -d    # single-container (simplest)

Open http://localhost:8787.

Variants

File	Containers	Use When
docker-compose.single.yml	1 (all-in-one)	First try — quickest setup
docker-compose.dual.yml	2 (agent + WebUI)	Want gateway/WebUI isolation
docker-compose.three.yml	3 (agent + WebUI + dashboard)	Full production stack with monitoring

Prerequisites

• Docker Engine ≥ 24.0 + Docker Compose ≥ 2.20
• git clone https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent (required for multi-container setups)
• At least one LLM API key (Anthropic, OpenAI, or OpenRouter)

Common Pitfalls

1. UID/GID mismatch — macOS UIDs start at 501, not 1000. Always set WANTED_UID and WANTED_GID in .env.
2. Missing hermes-agent source — Multi-container setups need the agent source cloned to the host and volume-mounted.
3. Permission denied on volumes — Run chown -R $WANTED_UID:$WANTED_GID ~/.hermes before first start.

Full troubleshooting at hermesdocker.com.