njzy/hermes-suite repository overview

Source repository: https://github.com/njzydark/hermes-suite/tree/self-use⁠ Build repository: https://github.com/njzydark/images/tree/main⁠

⁠Hermes Suite — All-in-One Container Image

Single Docker/Podman image combining three Hermes services:

Pre-built multi-arch images available on Docker Hub⁠.

🏗️ Official container images are maintained by Ascensionoid (ascensionoid.com⁠).

⁠Why This Exists

Podman v3.4.4 cannot share the same UID/GID between multiple containers easily. The standard multi-container setup (hermes-agent + hermes-webui + hermes-dashboard) requires each container to run as the same user to share the ~/.hermes volume. Podman v3.4.4 has limitations with userns_mode: keep-id across multiple containers.

This image solves that by running all three services in one container via supervisord.

⁠Architecture

+-------------------------------------------------+
|             hermes-suite container              |
|                                                 |
|  +-- supervisord (PID 1) --------------------+  |
|  |                                           |  |
|  |  [hermes-gateway]   port 8642             |  |
|  |    hermes gateway run                     |  |
|  |                                           |  |
|  |  [hermes-dashboard] port 9119             |  |
|  |    hermes dashboard --host 0.0.0.0        |  |
|  |                                           |  |
|  |  [hermes-webui]     port 8787             |  |
|  |    python server.py                       |  |
|  |                                           |  |
|  +-------------------------------------------+  |
|                                                 |
|  /opt/data  <-- mounted from ~/.hermes          |
+-------------------------------------------------+

⁠Prerequisites

• Podman v3.4.4+ or Docker
• podman-compose (or docker-compose)
• ~10GB disk space for the image
• Network access during build (for git clone and pip install)
• Works on both amd64 (x86_64) and arm64 (ARMv8) — tested on Jetson Orin NX

⁠Version Management

To ensure stability on edge devices (Jetson, ARM boards), it is highly recommended to use pinned versions rather than building from the main branch HEAD.

⁠Using Pre-Built Images (Recommended)

If you prefer not to build manually, use our pre-verified image tags from Docker Hub⁠:

podman pull ascensionoid/hermes-suite:2026.6.19-0.51.742

⁠Manual Build with Specific Versions

If you need a specific combination, pass the versions as build arguments:

podman build \
  --build-arg AGENT_VERSION=v2026.6.19 \
  --build-arg HERMES_WEBUI_VERSION=v0.51.742 \
  -t hermes-suite:2026.6.19-0.51.742 .

Or use the build helper (reads from versions.env):

# Podman or Docker (auto-detected at container startup)
./build.sh

# Build with Docker explicitly
./build.sh --docker

# Docker without logs (optional)
./build.sh --docker-nolog

# Override defaults:
# ./build.sh --agent v2026.6.19 --webui v0.51.742

If Hermes will use an external browser CDP endpoint, you can build without local Playwright Chromium:

./build.sh --skip-chromium

⁠External Browser CDP

Hermes supports BROWSER_CDP_URL for remote browser control. Point it at an already-running browser CDP endpoint:

environment:
  - BROWSER_CDP_URL=http://browser-cdp:9222

This mode assumes the CDP endpoint is reachable without extra HTTP authentication headers. If the endpoint requires a bearer token, place an authenticating reverse proxy in front of it and set BROWSER_CDP_URL to the proxy URL.

Set the CDP URL at runtime:

export BROWSER_CDP_URL=http://browser-cdp:9222
./up.sh

If you do not set BROWSER_CDP_URL, Hermes keeps its normal local browser behavior. Build with local Playwright Chromium unless you know every browser request will use a remote CDP endpoint.

⁠Version Compatibility Table

Every release is an explicitly tested pair of Agent + WebUI on both amd64 and arm64.

⁠Version Tag Format

Suite tags follow the pattern {agent_date}-{webui_semver}:

• Agent: date-based version from nousresearch/hermes-agent (e.g. v2026.6.19)
• WebUI: semantic version from nesquena/hermes-webui (e.g. v0.51.742)

The pinned pair for each release is declared in versions.env.

⁠Quick Start

⁠1. Clone this repo

git clone https://github.com/sunnysktsang/hermes-suite.git
cd hermes-suite

⁠2. Build the image

chmod +x *.sh
./build.sh

Or manually with pinned versions:

podman build \
  --build-arg AGENT_VERSION=v2026.6.19 \
  --build-arg HERMES_WEBUI_VERSION=v0.51.742 \
  -t ascensionoid/hermes-suite:2026.6.19-0.51.742 .

⁠3. Create the network (if not already existing)

podman network create --subnet 10.99.0.0/24 agent_net

⁠4. Start the container

./up.sh

Or manually:

podman-compose up -d

⁠5. Configure

Edit ~/.hermes/.env to add your API keys, and ~/.hermes/config.yaml for model settings. These files are shared from the host via the volume mount. On first run, defaults are created automatically from the hermes-agent examples.

⁠6. Access

• Gateway: http://localhost:8642⁠
• WebUI: http://localhost:8787⁠
• Dashboard: http://localhost:9119⁠

⁠Configuration

All configuration is stored in ~/.hermes/ on the host (mounted as /opt/data inside the container). On first start, the entrypoint script copies default .env and config.yaml from the hermes-agent examples if they don't already exist.

~/.hermes/
  .env            — API keys (OPENAI_API_KEY, TELEGRAM_TOKEN, etc.)
  config.yaml     — Model, toolsets, agent settings
  SOUL.md         — Agent personality
  skills/         — Custom skills
  memories/       — Persistent memory
  webui/          — WebUI state (sessions, workspace)

⁠Stopping

./down.sh

⁠Viewing Logs

./logs.sh

All service logs stream to stdout/stderr (visible via podman logs). Supervisord also writes to /var/log/supervisor/ inside the container:

podman exec hermes-suite supervisorctl status

⁠Customization

⁠Changing component versions

Edit versions.env to change the pinned versions and runtime settings:

AGENT_VERSION=v2026.6.19
WEBUI_VERSION=v0.51.742

# Runtime selector: auto (default), podman, docker, docker-nolog
CONTAINER_RUNTIME=auto

# Use sudo for commands (rootful mode): true, false
USE_SUDO=false

# Include WhatsApp bridge: true, false (default: false)
ENABLE_WHATSAPP_BRIDGE=false

Then rebuild:

./build.sh

Or override at build time:

./build.sh --agent v2026.4.16 --webui v0.50.244

⁠WhatsApp Bridge

The WhatsApp bridge is not included in the image by default. This is intentional:

• The bridge uses Baileys⁠ to emulate a WhatsApp Web session
• Without proper configuration, anyone who messages your number gets full agent access (terminal, filesystem, browser)
• See upstream issue #15108⁠ for details

To include the WhatsApp bridge at build time:

# Option 1: CLI flag
./build.sh --whatsapp

# Option 2: Set in versions.env
ENABLE_WHATSAPP_BRIDGE=true
./build.sh

⁠Changing the workspace path

Edit the volumes section in docker-compose.yaml:

volumes:
  - ~/workspace:/workspace:z   # change ~/workspace to your project directory

⁠Migration from Multi-Container Setup

If you are currently running the multi-container setup (hermes-agent + hermes-webui):

1. Stop the existing containers.

2. Build and start hermes-suite:

   cd hermes-suite
   ./build.sh
   ./up.sh
   

   Copy

3. Your existing ~/.hermes/ data is reused automatically — no migration needed.

⁠Troubleshooting

⁠Permission errors on ~/.hermes

Rootless Podman:

The container runs as UID 10000, which maps to a host UID (e.g. 109999) per /etc/subuid. Fix ownership on the host:

sudo chown -R 109999:109999 ~/.hermes

Rootful Podman or Docker:

Ownership is auto-corrected on startup. If issues persist:

sudo chown -R 10000:10000 ~/.hermes

⁠WebUI not loading

Check that the webui venv was built correctly:

podman exec hermes-suite /opt/hermes-webui/venv/bin/python -c "import yaml; print('OK')"

⁠Services fail with "EACCES making dispatchers" (Docker only)

This should not occur with the auto-detection feature (v2026.5.16-0.51.137+). The container detects Docker at startup and adjusts the privilege model automatically. Ensure you are using a recent image.

If it still occurs, ensure tty: true is NOT set in docker-compose.yaml.

⁠Dashboard returns connection error

The dashboard needs the gateway running first. Check supervisord status:

podman exec hermes-suite supervisorctl status

⁠Build fails on git clone

Ensure the build host has network access. The hermes-webui repo is cloned at build time. If your build environment has no internet, pre-clone the webui repo and adjust the Dockerfile to COPY it instead of git clone.

⁠Build fails on uv venv or pip not found

The Dockerfile uses uv (pre-installed in the hermes-agent base image) to create virtual environments and install packages. If you change the base image, ensure uv is available at /usr/local/bin/uv.

⁠How It Works

The Dockerfile performs these steps:

1. Base image — Uses the official nousresearch/hermes-agent image which already contains Python 3.13, Node.js, npm, Playwright, the agent code, and the built-in dashboard.

2. System packages — Installs sudo, git, nano, network tools, and other utilities.

3. Browser tools — Installs Playwright Chromium for the browser toolset.

4. Supervisor — Installs supervisord via pip into a dedicated venv at /opt/supervisor (not available in Debian Trixie apt repos).

5. Hermes WebUI — Clones from GitHub and installs into a separate venv at /opt/hermes-webui/venv, along with the agent's Python dependencies so the WebUI can import agent modules.

6. Entrypoint — start.sh handles UID/GID remapping (for rootless Podman), directory setup, and config bootstrapping before launching supervisord.

⁠Files

hermes-suite/
  Dockerfile           — Build definition (parameterized AGENT_VERSION + HERMES_WEBUI_VERSION)
  versions.env         — Pinned component versions for current release
  supervisord.conf     — Process manager config (3 services)
  start.sh             — Container entrypoint (UID setup + launch)
  docker-compose.yaml  — Podman/Docker Compose configuration
  build.sh             — Build helper script (reads versions.env)
  up.sh                — Start helper script
  down.sh              — Stop helper script
  logs.sh              — Log viewer helper script
  .dockerignore        — Build context exclusions
  .env.example         — Environment variable template
  README.md            — This file

⁠Tested On

The base image nousresearch/hermes-agent provides multi-architecture manifests (amd64 + arm64). Podman and Docker automatically pull the correct variant for your platform. No changes to the Dockerfile are needed — it builds identically on both architectures.

⁠License

This project is licensed under the MIT License. The individual components are licensed separately:

• hermes-agent⁠ — by Nous Research (MIT)
• hermes-webui⁠ — by nesquena (MIT)

Thanks to nesquena⁠ for building hermes-webui and referencing this project⁠ in the official Docker docs.