Bug Description

The hermes dashboard command fails to start inside the official nousresearch/hermes-agent Docker container because it attempts to run npm install and npm run build in /opt/hermes/web, which resides in the image's read-only overlayfs lowerdir. Even running as root cannot write to this path, making Dashboard completely unusable in containerized deployments.

Environment

• Image: nousresearch/hermes-agent:latest (pulled 2026-04-18)
• Docker version: 26.x
• Host OS: Rocky Linux 9
• Container user: 1000:2000 (also tested with root)

Steps to Reproduce

1. Start the official container:

   docker run -d --name hermes-agent \
     -p 8000:8000 -p 8645:8645 -p 9119:9119 \
     -v /data/internal/hermes:/opt/data \
     -e API_SERVER_ENABLED=true \
     nousresearch/hermes-agent:latest \
     gateway run
   

2.Inside the container, attempt to start Dashboard:
docker exec hermes-agent bash -c "cd /opt/hermes && .venv/bin/hermes dashboard --host 0.0.0.0 --port 9119 --insecure --no-open"

3.Observe the failure:
→ Building web UI...
✗ Web UI npm install failed
Run manually: cd web && npm install && npm run build

In the official Docker image, /opt/hermes/web is part of the committed image layers (overlayfs lowerdir). When the dashboard startup script executes npm install, it tries to create node_modules inside /opt/hermes/web. However, overlayfs lowerdir is read-only by design — even root inside the container cannot mkdir, chmod, or chown files in this path:

Inside container

$ mkdir /opt/hermes/web/node_modules
mkdir: cannot create directory '/opt/hermes/web/node_modules': Permission denied

$ rm -rf /opt/hermes/web
rm: cannot remove '/opt/hermes/web/...': Permission denied

This makes the "build on first launch" approach fundamentally incompatible with the official Docker image.
Expected Behavior
Dashboard should start successfully in the official Docker image without requiring manual frontend builds inside the container.
Possible Solutions
Pre-build web_dist in the image: Include the built frontend artifacts (web_dist or dist) in the official Docker image, so npm install is only needed for development, not production containers.
Skip build if dist exists: Modify the dashboard startup script to check for pre-existing build artifacts before attempting npm install.
Support DASHBOARD_SKIP_BUILD env var: Allow users to bypass the build step and serve static files from a mounted volume.
Build to a writable path: Change the build output directory to /tmp or another writable location inside the container.
Additional Context
The WebUI project (ghcr.io/nesquena/hermes-webui) works around this by shipping its own Docker image with a proper init script that handles virtualenv setup separately from the application code.
Users currently cannot use Dashboard at all in containerized deployments without rebuilding the entire image or mounting a fully prepared web directory, which is fragile and breaks on image updates.

Logs
/opt/hermes/.venv/bin/python: No module named hermes
→ Building web UI...
✗ Web UI npm install failed
Run manually: cd web && npm install && npm run build

Thank you for the great work on Hermes Agent! The gateway and CLI work perfectly in containers — it would be great if Dashboard could work equally well in Docker deployments.