From a72208eaf600309f378e41692b5c30722b1e43e1 Mon Sep 17 00:00:00 2001
From: bergeouss <48155732+bergeouss@users.noreply.github.com>
Date: Thu, 23 Apr 2026 01:35:09 +0200
Subject: [PATCH] =?UTF-8?q?fix(docker):=20improve=20two-container=20agent?=
 =?UTF-8?q?=20path=20discovery=20and=20docs=20=E2=80=94=20v0.50.158=20(PR?=
 =?UTF-8?q?=20#873=20by=20@bergeouss,=20closes=20#858)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docker_init.bash now checks /opt/hermes as a fallback alongside the primary path. Warning updated with concrete mount guidance. Volume type notes added to compose files and README.
---
 README.md                          |  7 +++++++
 docker-compose.three-container.yml |  6 ++++++
 docker-compose.two-container.yml   | 17 +++++++++++++++++
 docker_init.bash                   | 23 +++++++++++++++++++----
 4 files changed, 49 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 4c60d75..9531bb1 100644
--- a/README.md
+++ b/README.md
@@ -189,6 +189,13 @@ This starts both containers with shared volumes:
 - **`hermes-agent-src`** — the agent's source code, mounted into the WebUI
   container so it can install the agent's Python dependencies at startup
 
+> **Volume type:** The compose files use named Docker volumes by default.
+> If you prefer bind mounts to an existing directory (e.g. for sharing state
+> with an agent container you already run), both containers must mount the
+> same host path — the agent writes to `/root/.hermes`, the WebUI reads from
+> `/home/hermeswebui/.hermes`. See `docker-compose.two-container.yml` for
+> a bind-mount example.
+
 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.
diff --git a/docker-compose.three-container.yml b/docker-compose.three-container.yml
index 8afa3a3..0e5c1ec 100644
--- a/docker-compose.three-container.yml
+++ b/docker-compose.three-container.yml
@@ -13,6 +13,12 @@
 #
 # All three share the same hermes-home volume so config, sessions,
 # skills, and memory are consistent across all surfaces.
+#
+# NOTE ON VOLUMES:
+#   This file uses named Docker volumes (hermes-home, hermes-agent-src) which
+#   work out of the box. If you prefer bind mounts (e.g. to an existing directory),
+#   see the two-container compose file for a bind-mount example.
+#   When using bind mounts, ALL containers must mount the same host path.
 
 services:
   hermes-agent:
diff --git a/docker-compose.two-container.yml b/docker-compose.two-container.yml
index af4eb63..0b61d02 100644
--- a/docker-compose.two-container.yml
+++ b/docker-compose.two-container.yml
@@ -10,6 +10,23 @@
 # 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.
+#
+# NOTE ON VOLUMES:
+#   This file uses named Docker volumes (hermes-home, hermes-agent-src) which
+#   work out of the box. If you prefer bind mounts (e.g. to an existing directory),
+#   replace the named volumes at the bottom. Example for hermes-agent-src:
+#
+#     hermes-agent-src:
+#       driver: local
+#       driver_opts:
+#         type: none
+#         o: bind
+#         device: /opt/hermes-agent
+#
+#   When using bind mounts, BOTH containers must mount the same host path.
+#   The agent exposes source at /opt/hermes, the WebUI reads it from
+#   /home/hermeswebui/.hermes/hermes-agent — as long as both point to the
+#   same host directory, the paths align correctly.
 
 services:
   hermes-agent:
diff --git a/docker_init.bash b/docker_init.bash
index 4849374..187e825 100644
--- a/docker_init.bash
+++ b/docker_init.bash
@@ -294,14 +294,29 @@ else
   test -x /app/venv/bin/pip
 
   echo ""; echo "== Adding hermes-agent's pyproject.toml base dependencies to the virtual environment"
-  if [ -d "/home/hermeswebui/.hermes/hermes-agent" ] && [ -f "/home/hermeswebui/.hermes/hermes-agent/pyproject.toml" ]; then
-    uv pip install "/home/hermeswebui/.hermes/hermes-agent[honcho]" --trusted-host pypi.org --trusted-host files.pythonhosted.org || error_exit "Failed to install hermes-agent's requirements"
+  _agent_paths=(
+    "/home/hermeswebui/.hermes/hermes-agent"
+    "/opt/hermes"
+  )
+  _agent_src=""
+  for _p in "${_agent_paths[@]}"; do
+    if [ -d "$_p" ] && [ -f "$_p/pyproject.toml" ]; then
+      _agent_src="$_p"
+      break
+    fi
+  done
+  if [ -n "$_agent_src" ]; then
+    uv pip install "$_agent_src[honcho]" --trusted-host pypi.org --trusted-host files.pythonhosted.org || error_exit "Failed to install hermes-agent's requirements"
   else
     echo ""
-    echo "!! WARNING: hermes-agent source not found at /home/hermeswebui/.hermes/hermes-agent"
+    echo "!! WARNING: hermes-agent source not found."
+    echo "!!   Looked in: ${_agent_paths[0]}"
+    echo "!!              ${_agent_paths[1]}"
     echo "!! The WebUI will start with reduced functionality (no model auto-detection,"
     echo "!! no personality routing, no CLI session imports)."
-    echo "!! To fix: mount the agent source volume into the container. See:"
+    echo "!! To fix: mount the agent source volume into the container:"
+    echo "!!   -v /path/to/hermes-agent:/home/hermeswebui/.hermes/hermes-agent"
+    echo "!! Or see the two-container compose example:"
     echo "!!   https://github.com/nesquena/hermes-webui/blob/master/docker-compose.two-container.yml"
     echo ""
   fi