Fixing "AIAgent not available" in Hermes Web UI

The Web UI cannot find the Hermes Agent source code and starts in reduced-functionality mode. Symptoms in docker logs hermes-webui:

!! WARNING: hermes-agent source not found.
!!   Looked in: /home/hermeswebui/.hermes/hermes-agent
ImportError: AIAgent not available -- check that hermes-agent is on sys.path
  agent dir   : NOT FOUND  [XX]

Root Cause

The container needs the Hermes Agent Python source at /home/hermeswebui/.hermes/hermes-agent (or /opt/hermes as fallback). This is used by the init script to:

Install dependencies from the agent's pyproject.toml
Make AIAgent importable from run_agent.py

When the source is missing, the server starts without any agent features.

Fix (agent source is on host but not in the container)

If your Hermes home is bind-mounted and the agent source exists on the host but wasn't mounted:

Option A: Copy source into the mounted data directory (no restart needed)

# Copy host's hermes-agent source into the directory already mounted to the container
cp -r /path/to/host/.hermes/hermes-agent /path/to/mounted-data/hermes-agent

# Install deps inside the container
docker exec hermes-webui bash -c "source /app/venv/bin/activate && pip install -e /home/hermeswebui/.hermes/hermes-agent"

# Remove the fast-restart marker and restart to force full setup
docker exec hermes-webui rm -f /app/venv/.deps_installed
docker restart hermes-webui

# If permission errors occur (root-owned pycache from prior pip install):
docker exec hermes-webui bash -c "find /app/venv -user root -delete"
docker restart hermes-webui

Option B: Add a proper bind mount (cleaner, Docker Compose)

Add to the webui service in your docker-compose.yml:

services:
  hermes-webui:
    image: ghcr.io/nesquena/hermes-webui:latest
    volumes:
      - ~/.hermes:/home/hermeswebui/.hermes:ro
      - ~/.hermes/hermes-agent:/home/hermeswebui/.hermes/hermes-agent:ro   # <-- add this
      - /path/to/workspace:/workspace
    environment:
      - HERMES_WEBUI_PASSWORD=***
    ports:
      - "8787:8787"

Then recreate:

docker compose up -d

Verifying the fix

# Check startup logs for success
docker logs hermes-webui | grep "agent dir"

# Expected:
#   agent dir   : /home/hermeswebui/.hermes/hermes-agent  [ok]

# Also confirm no AIAgent import errors:
docker logs hermes-webui | grep -i "AIAgent"

# Should return nothing (no errors)

Known edge cases

Fast restart skipping agent install

The init script checks for /app/venv/.deps_installed. If the agent source was added after the container's first startup (when the marker was created), the init script skips reinstalling and the import still fails even though the source is present.

Fix: Remove the marker and restart:

docker exec hermes-webui rm -f /app/venv/.deps_installed
docker restart hermes-webui

Permission denied during reinstall ("os error 13")

A prior pip install -e or manual install running as root leaves root-owned .pyc files in /app/venv/lib/python3.12/site-packages/__pycache__/. When the init script later runs as a non-root user, it can't remove them.

Fix: Clean root files from the venv:

docker exec hermes-webui bash -c "find /app/venv -user root -delete"
docker restart hermes-webui

3.3 KiB Raw Blame History