# NousResearch/hermes-agent · Docker container support for Hermes Agent ## Open now - Nothing open on GitHub. These issues and pull requests concern adding Docker container and image support for running the Hermes Agent. The work includes creating Dockerfiles and enabling full Docker-based deployment. ## TL;DR - 4 member(s): 0 open issue(s), 1 closed issue(s), 0 open PR(s), 1 merged PR(s), 2 PR(s) closed without merging. - A fix was merged to main in PR #3668. Verify it addresses your case. - **Recommended:** read PR #3668 (and any competing PRs below) before filing. Confirm the merged change covers your symptom. ## Maintainer resolution verdict - Internal-tracker verdict over this cluster's issue members: `resolved` · deciding PR(s): `pr-3668`. This is distinct from the fix status above. Weigh it yourself. ## How this cluster was grouped - Link evidence (`STRUCTURAL_SPANNING`): every member is connected by structural evidence: shared changed files, or a closing/superseded reference. - Pairwise link density `0.50`: the share of member pairs that carry a link, counting a structural link in full and a relevance-only link at 0.36. `1.00` means every pair is linked. ## Closed / duplicate issues - #850: \[Feature\]: Full docker deployment ## Prior & competing PRs - **#3668: feat(docker): add Docker container for the agent (salvage #1841)**. merged to main · fix tier `verified` - maintainer direction: category `merged` - files: `.dockerignore`, `.github/workflows/docker-publish.yml`, `Dockerfile`, `docker/SOUL.md`, `docker/entrypoint.sh`, `website/docs/user-guide/docker.md`, `website/sidebars.ts` - fix hunks: - `.dockerignore` ```diff @@ -0,0 +1,13 @@ +# Git +.git +.gitignore +.gitmodules + +# Dependencies +node_modules + +# CI/CD +.github + +# Environment files +.env \ No newline at end of file ``` - `.github/workflows/docker-publish.yml` ```diff @@ -0,0 +1,61 @@ +name: Docker Build and Publish + +on: + push: + branches: [main] + pull_request: + branches: [main] + +concurrency: + group: docker-${{ github.ref }} + cancel-in-progress: true + +jobs: + build-and-push: + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Build image + uses: docker/build-push-action@v6 + with: + context: . + file: Dockerfile + load: true + tags: nousresearch/hermes-agent:test + cache-from: type=gha + cache-to: type=gha,mode=max + + - name: Test image starts + run: | + docker run --rm \ + -v /tmp/hermes-test:/opt/data \ + --entrypoint /opt/hermes/docker/entrypoint.sh \ + nousresearch/hermes-agent:test --help + + - name: Log in to Docker Hub + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Push image + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: docker/build-push-action@v6 + with: + context: . + file: Dockerfile + push: true + tags: | + nousresearch/hermes-agent:latest + nousresearch/hermes-agent:${{ github.sha }} + cache-from: type=gha + cache-to: type=gha,mode=max ``` - `Dockerfile` ```diff @@ -0,0 +1,20 @@ +FROM debian:13.4 + +RUN apt-get update +RUN apt-get install -y nodejs npm python3 python3-pip ripgrep ffmpeg gcc python3-dev libffi-dev + +COPY . /opt/hermes +WORKDIR /opt/hermes + +RUN pip install -e ".[all]" --break-system-packages +RUN npm install +RUN npx playwright install --with-deps chromium +WORKDIR /opt/hermes/scripts/whatsapp-bridge +RUN npm install + +WORKDIR /opt/hermes +RUN chmod +x /opt/hermes/docker/entrypoint.sh + +ENV HERMES_HOME=/opt/data +VOLUME [ "/opt/data" ] +ENTRYPOINT [ "/opt/hermes/docker/entrypoint.sh" ] \ No newline at end of file ``` - `docker/SOUL.md` ```diff @@ -0,0 +1,15 @@ +# Hermes Agent Persona + + \ No newline at end of file ``` - `docker/entrypoint.sh` ```diff @@ -0,0 +1,34 @@ +#!/bin/bash +# Docker entrypoint: bootstrap config files into the mounted volume, then run hermes. +set -e + +HERMES_HOME="/opt/data" +INSTALL_DIR="/opt/hermes" + +# Create essential directory structure. Cache and platform directories +# (cache/images, cache/audio, platforms/whatsapp, etc.) are created on +# demand by the application — don't pre-create them here so new installs +# get the consolidated layout from get_hermes_dir(). +mkdir -p "$HERMES_HOME"/{cron,sessions,logs,hooks,memories,skills} + +# .env +if [ ! -f "$HERMES_HOME/.env" ]; then + cp "$INSTALL_DIR/.env.example" "$HERMES_HOME/.env" +fi + +# config.yaml +if [ ! -f "$HERMES_HOME/config.yaml" ]; then + cp "$INSTALL_DIR/cli-config.yaml.example" "$HERMES_HOME/config.yaml" +fi + +# SOUL.md +if [ ! -f "$HERMES_HOME/SOUL.md" ]; then + cp "$INSTALL_DIR/docker/SOUL.md" "$HERMES_HOME/SOUL.md" +fi + +# Sync bundled skills (manifest-based so user edits are preserved) +if [ -d "$INSTALL_DIR/skills" ]; then + python3 "$INSTALL_DIR/tools/skills_sync.py" +fi + +exec hermes "$@" ``` - `website/docs/user-guide/docker.md` ```diff @@ -0,0 +1,56 @@ +# Hermes Agent — Docker + +Want to run Hermes Agent, but without installing packages on your host? This'll sort you out. + +This will let you run the agent in a container, with the most relevant modes outlined below. + +The container stores all user data (config, API keys, sessions, skills, memories) in a single directory mounted from the host at `/opt/data`. The image itself is stateless and can be upgraded by pulling a new version without losing any configuration. + +## Quick start + +If this is your first time running Hermes Agent, create a data directory on the host and start the container interactively to run the setup wizard: + +```sh +mkdir -p ~/.hermes +docker run -it --rm \ + -v ~/.hermes:/opt/data \ + nousresearch/hermes-agent +``` + +This drops you into the setup wizard, which will prompt you for your API keys and write them to `~/.hermes/.env`. You only need to do this once. It is highly recommended to set up a chat system for the gateway to work with at this point. + +## Running in gateway mode + +Once configured, run the container in the background as a persistent gateway (Telegram, Discord, Slack, WhatsApp, etc.): + +```sh +docker run -d \ + --name hermes \ + --restart unless-stopped \ + -v ~/.hermes:/opt/data \ + nousresearch/hermes-agent gateway run +``` + +## Running interactively (CLI chat) + +To open an interactive chat session against a running data directory: + +```sh +docker run -it --rm \ + -v ~/.hermes:/opt/data \ + nousresearch/hermes-agent +``` + +## Upgrading + +Pull the latest image and recreate the container. Your data directory is untouched. + +```sh +docker pull nousresearch/hermes-agent:latest +docker rm -f hermes +docker run -d \ + --name hermes \ + --restart unless-stopped \ + -v ~/.hermes:/opt/data \ + nousresearch/hermes-agent +``` ``` - `website/sidebars.ts` ```diff @@ -37,6 +37,7 @@ const sidebars: SidebarsConfig = { 'user-guide/configuration', 'user-guide/sessions', 'user-guide/security', + 'user-guide/docker', { type: 'category', label: 'Messaging Gateway', ``` - **#1841: Add a docker container for the agent**. closed without merge - maintainer direction: category `merged_via`; implication `superseded`; refs `#3668`, `#3610` - **#3637: feat: add Docker image for running Hermes Agent in containers**. closed without merge - maintainer direction: category `superseded_by_pr`; implication `superseded` ## Fix status - Merged to main in PR #3668 (cited above). No release data is tracked. Verify downstream. - Fix last verified (merged) `2026-03-29`. This confirmation is old and may be out of date (a revert/reopen would not have invalidated it here); re-verify. - Subsystem: `agent`