# 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:

1. Install dependencies from the agent's `pyproject.toml`
2. 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)

```bash
# 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:

```yaml
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:

```bash
docker compose up -d
```

## Verifying the fix

```bash
# 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:

```bash
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:

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