From 5468b045508624b7c1c500d4175f315edbda1180 Mon Sep 17 00:00:00 2001
From: Nathan Esquenazi <nesquena@gmail.com>
Date: Sun, 12 Apr 2026 00:37:35 -0700
Subject: [PATCH] docs: two-container Docker setup for Agent + WebUI (#288)

Adds docker-compose.two-container.yml and README section for running
hermes-agent and hermes-webui in separate Docker containers connected
via shared volumes.

The key insight: the WebUI imports hermes-agent's Python modules
directly (not via HTTP), so the agent source must be mounted into
the WebUI container. The existing docker_init.bash handles installing
the agent's dependencies at startup via uv pip install.

Shared volumes:
- hermes-home: config, sessions, skills, memory (~/.hermes)
- hermes-agent-src: agent source code for Python import

Fixes #288

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md                        | 26 +++++++++++++++
 docker-compose.two-container.yml | 55 ++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 docker-compose.two-container.yml

diff --git a/README.md b/README.md
index a4d57eb..d3ea26e 100644
--- a/README.md
+++ b/README.md
@@ -171,6 +171,32 @@ docker run -d \
 > To expose on a network, change the port to `"8787:8787"` in `docker-compose.yml`
 > and set `HERMES_WEBUI_PASSWORD` to enable authentication.
 
+### Two-container setup (Agent + WebUI)
+
+If you run the Hermes Agent in its own Docker container and want the WebUI
+in a separate container:
+
+```bash
+docker compose -f docker-compose.two-container.yml up -d
+```
+
+This starts both containers with shared volumes:
+
+- **`hermes-home`** — shared `~/.hermes` for config, sessions, skills, memory
+- **`hermes-agent-src`** — the agent's source code, mounted into the WebUI
+  container so it can install the agent's Python dependencies at startup
+
+The WebUI's init script automatically installs hermes-agent and all its
+dependencies (openai, anthropic, etc.) into its own Python environment on
+first boot. Subsequent restarts reuse the installed packages.
+
+> **How it works:** The WebUI imports hermes-agent's Python modules directly
+> (not via HTTP). The shared volume makes the agent source available, and
+> the init script runs `uv pip install` to set up the dependencies. Both
+> containers share the same `~/.hermes` directory for config and state.
+
+See `docker-compose.two-container.yml` for the full configuration.
+
 ---
 
 ## What start.sh discovers automatically
diff --git a/docker-compose.two-container.yml b/docker-compose.two-container.yml
new file mode 100644
index 0000000..e4f7800
--- /dev/null
+++ b/docker-compose.two-container.yml
@@ -0,0 +1,55 @@
+# Two-container Docker Compose: Hermes Agent + Hermes WebUI
+#
+# This runs the agent and web UI in separate containers connected via
+# shared volumes. The WebUI installs the agent's Python dependencies
+# at startup from the shared agent source volume.
+#
+# Usage:
+#   docker compose -f docker-compose.two-container.yml up -d
+#
+# The agent container runs the gateway (CLI, Telegram, cron, etc.).
+# The WebUI container serves the browser interface on port 8787.
+# Both share ~/.hermes for config, sessions, and state.
+
+services:
+  hermes-agent:
+    image: nousresearch/hermes-agent:latest
+    container_name: hermes-agent
+    volumes:
+      # Persist config, state, sessions, skills, memory across restarts
+      - hermes-home:/root/.hermes
+      # Expose agent source so the WebUI can install dependencies from it
+      - hermes-agent-src:/opt/hermes
+    environment:
+      - HERMES_HOME=/root/.hermes
+    restart: unless-stopped
+
+  hermes-webui:
+    image: ghcr.io/nesquena/hermes-webui:latest
+    container_name: hermes-webui
+    depends_on:
+      - hermes-agent
+    ports:
+      - "127.0.0.1:8787:8787"
+    volumes:
+      # Same hermes home as the agent — shares config, sessions, state
+      - hermes-home:/home/hermeswebui/.hermes
+      # Agent source mounted where docker_init.bash expects it.
+      # At startup the init script runs:
+      #   uv pip install /home/hermeswebui/.hermes/hermes-agent
+      # which installs the agent and all its Python dependencies.
+      - hermes-agent-src:/home/hermeswebui/.hermes/hermes-agent
+    environment:
+      - HERMES_WEBUI_HOST=0.0.0.0
+      - HERMES_WEBUI_PORT=8787
+      - HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui-mvp
+      # Match your host user's UID/GID for correct file permissions
+      - WANTED_UID=${UID:-1000}
+      - WANTED_GID=${GID:-1000}
+      # Optional: set a password for remote access
+      # - HERMES_WEBUI_PASSWORD=your-secret-password
+    restart: unless-stopped
+
+volumes:
+  hermes-home:
+  hermes-agent-src: