duansq/hermes-webui repository overview

⁠Hermes WebUI Docker Image

A maintained Docker Hub image for Hermes WebUI⁠, a lightweight browser interface for Hermes Agent.

This image is published from the maintained fork at zerostwo/hermes-webui and is intended for simple self-hosted deployment with Docker Compose.

⁠Image

duansq/hermes-webui

Recommended production tag:

duansq/hermes-webui:stable

Available tag families:

• stable — recommended production tag from the default branch.
• latest — same default-branch image for users who prefer the conventional tag.
• sha-<short-sha> — immutable image for a specific commit.
• X.Y.Z, X.Y — release tags when the repository publishes v* git tags.

⁠Quick start

Create a deployment directory:

sudo mkdir -p /srv/hermes-webui
sudo chown "$USER:$USER" /srv/hermes-webui
cd /srv/hermes-webui

Create compose.yaml:

services:
  hermes-webui:
    image: duansq/hermes-webui:stable
    container_name: hermes-webui
    ports:
      - "0.0.0.0:${HERMES_WEBUI_HOST_PORT:-18787}:8787"
    volumes:
      - ${HERMES_HOME:-${HOME}/.hermes}:/home/hermeswebui/.hermes
      - ${HERMES_WORKSPACE:-${HOME}/workspace}:/workspace
    environment:
      - WANTED_UID=${UID:-1000}
      - WANTED_GID=${GID:-1000}
      - HERMES_WEBUI_HOST=0.0.0.0
      - HERMES_WEBUI_PORT=8787
      - HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui
      - HERMES_WEBUI_DEFAULT_WORKSPACE=/workspace
      - HERMES_WEBUI_PASSWORD=${HERMES_WEBUI_PASSWORD:?Set HERMES_WEBUI_PASSWORD in .env}
      - HERMES_SKIP_CHMOD=${HERMES_SKIP_CHMOD:-1}
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped

Create .env next to compose.yaml:

cat > .env <<'EOF'
HERMES_WEBUI_HOST_PORT=18787
HERMES_WEBUI_PASSWORD=change-this-password
HERMES_HOME=/home/your-user/.hermes
HERMES_WORKSPACE=/home/your-user/workspace
UID=1000
GID=1000
EOF

Start the service:

docker compose pull
docker compose up -d
docker compose ps
curl -fsS http://127.0.0.1:18787/health

Open:

http://<server-ip>:18787/

⁠Updating

cd /srv/hermes-webui
docker compose pull
docker compose up -d
curl -fsS http://127.0.0.1:${HERMES_WEBUI_HOST_PORT:-18787}/health

For a fully pinned deployment, replace stable with a sha-<short-sha> tag from Docker Hub.

⁠Volumes and state

The container expects your Hermes Agent state to be mounted at:

/home/hermeswebui/.hermes

The compose example maps this from the host's HERMES_HOME, defaulting to:

/home/your-user/.hermes

Your workspace is mounted at /workspace. If Hermes tools need direct access to additional host paths, add explicit read/write mounts for those directories in compose.yaml.

⁠Security notes

• Set HERMES_WEBUI_PASSWORD for any non-local deployment.
• Keep .env private and out of git.
• Prefer a reverse proxy with TLS if exposing the WebUI beyond a trusted LAN/VPN.
• The container runs the WebUI as an unprivileged runtime user after startup initialization.

⁠GPU notes

The default image is CPU-oriented. If your Hermes tools need GPU access, install the NVIDIA Container Toolkit on the host and add GPU passthrough to your compose file:

services:
  hermes-webui:
    gpus: all

GPU availability still depends on host drivers, container runtime support, and the tools invoked by Hermes.

⁠Troubleshooting

Check container status and logs:

docker compose ps
docker compose logs --tail=200 hermes-webui

Check health:

curl -i http://127.0.0.1:${HERMES_WEBUI_HOST_PORT:-18787}/health

If the container cannot read files under ~/.hermes, confirm UID, GID, and HERMES_SKIP_CHMOD in .env match your host deployment needs.