ray
105 lines
3.3 KiB
Markdown
105 lines
3.3 KiB
Markdown
# 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
|
|
```
|