Hermes Agent Docker — Self-Host Hermes Agent in a Container

Why Docker for Hermes Agent?

Docker is the recommended way to run Hermes Agent on your own server. The official image bundles every runtime dependency — Node.js, the gateway server, all bundled plugins, and the OpenAI-compatible API layer — so there is nothing to install manually. You get a clean, reproducible environment that is easy to update, back up, and migrate.

• No dependency conflicts — the container is fully self-contained. The host only needs Docker.
• Persistent state via volumes — bind-mount ~/.hermes so config, credentials, and session memory survive container restarts and image upgrades.
• Easy upgrades — pull a new tag, restart the container, and the updated binary picks up your existing data from the volume.
• Portable — the same docker-compose.yml works on a VPS, a home server, or a cloud VM without modification.

The official image is hosted on GitHub Container Registry (GHCR) at github.com/NousResearch/hermes-agent. Always check the releases page for the current pinned tag before deploying — using :latest is fine for a quick test but pinning a specific version is recommended for production.

Quick Start: docker run

The fastest way to get Hermes Agent running is a single docker run command. This starts the gateway on port 8642 and mounts a local directory for persistent config and memory:

# Create the data directory on your host
mkdir -p ~/.hermes

# Run the container
docker run -d \
  --name hermes-agent \
  --restart unless-stopped \
  -p 8642:8642 \
  -v ~/.hermes:/home/node/.hermes \
  -e HERMES_AUTH_TOKEN=your-secret-token \
  -e OPENROUTER_API_KEY=sk-or-... \
  ghcr.io/nousresearch/hermes-agent:latest

Once the container starts, the gateway is reachable at http://localhost:8642. Open that URL in your browser to access the Hermes web UI and complete first-time setup. Replace your-secret-token with a strong random string — this becomes your gateway auth token.

docker-compose Setup

For a more maintainable setup, use docker-compose. The file below covers the most common production needs: persistent volume, env vars, restart policy, and an optional healthcheck.

# docker-compose.yml
version: "3.9"

services:
  hermes:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-agent
    restart: unless-stopped
    ports:
      - "127.0.0.1:8642:8642"   # bind to loopback; Caddy/nginx proxies HTTPS
    volumes:
      - hermes-data:/home/node/.hermes
    environment:
      HERMES_AUTH_TOKEN: "${HERMES_AUTH_TOKEN}"
      OPENROUTER_API_KEY: "${OPENROUTER_API_KEY}"
      # Optional — set if you use OpenAI directly
      # OPENAI_API_KEY: "${OPENAI_API_KEY}"
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8642/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s

volumes:
  hermes-data:

Create a .env file alongside docker-compose.yml with your secrets (never commit it to git):

# .env
HERMES_AUTH_TOKEN=change-me-to-a-strong-random-token
OPENROUTER_API_KEY=sk-or-v1-...

Then start the stack:

docker compose up -d
docker compose logs -f hermes

Configuration Options

Hermes Agent reads its runtime configuration from the mounted data directory (/home/node/.hermes) and from environment variables. The table below lists the most commonly used env vars at container start:

For a complete list of configuration options supported by your installed version, see the upstream Hermes Agent README.

Persistent Memory and Volumes

All of Hermes Agent's stateful data lives under /home/node/.hermes inside the container. This includes:

• config.yaml — gateway settings, model provider config, channel integrations (Telegram, Discord, Slack, etc.)
• credentials/ — pairing credentials for Telegram, Discord, and other platform integrations
• memory/ — session memory embeddings (Qwen3 embeddings or your configured embedding model)
• logs/ — internal logs for debugging and audit

Always mount this directory to a named volume or a host path. Without a volume, every container restart wipes all credentials and memory, requiring you to re-pair every channel integration from scratch.

# Named volume (recommended — Docker manages the path)
volumes:
  - hermes-data:/home/node/.hermes

# Host bind mount (alternative — easier to inspect and back up)
volumes:
  - ~/.hermes:/home/node/.hermes

To back up your data, copy the volume contents to a safe location before any image upgrade:

# Back up using the named volume
docker run --rm \
  -v hermes-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/hermes-backup-$(date +%Y%m%d).tar.gz -C /data .

Exposing the Gateway

The gateway runs on port 8642 inside the container. For production, do not expose it directly — put a reverse proxy with TLS in front of it. Below are minimal configs for Caddy and nginx.

Caddy (auto-HTTPS, simplest option):

# Caddyfile
hermes.yourdomain.com {
    reverse_proxy localhost:8642
}

Caddy automatically provisions and renews a Let's Encrypt certificate for the domain. No further TLS configuration needed.

nginx:

# /etc/nginx/sites-available/hermes
server {
    listen 443 ssl;
    server_name hermes.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/hermes.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/hermes.yourdomain.com/privkey.pem;

    location / {
        proxy_pass         http://127.0.0.1:8642;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_read_timeout 3600s;
    }
}

server {
    listen 80;
    server_name hermes.yourdomain.com;
    return 301 https://$host$request_uri;
}

The proxy_read_timeout 3600s line is important — Hermes uses long-lived WebSocket connections for real-time streaming, and the default nginx timeout of 60 seconds will disconnect active sessions.

Using a GPU for Local Models

If you run Hermes Agent with a local model backend (for example, an Ollama instance or a vLLM server on the same host), you may want to pass your GPU through to those inference containers. Hermes Agent itself does not do GPU inference — it is a gateway and orchestration layer — but it can sit alongside a GPU-accelerated inference container in the same compose stack.

For the inference container (e.g. Ollama), add the GPU deploy block:

# In docker-compose.yml — for your inference container, not Hermes itself
  ollama:
    image: ollama/ollama:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    volumes:
      - ollama-models:/root/.ollama
    ports:
      - "127.0.0.1:11434:11434"

Then point Hermes at the local Ollama endpoint (see the Hermes + Ollama guide for full details). The --gpus all flag is the docker run equivalent of the compose snippet above.

Why Use OpenClaw Launch Instead?

Self-hosting Hermes via Docker gives you full control, but it also means managing updates, TLS, backups, restarts, and infrastructure uptime yourself. OpenClaw Launch runs the exact same Hermes Agent Docker container for you — fully managed.

OpenClaw Launch provisions the same Hermes Docker container behind the scenes. The difference is that you get a one-click deploy, a managed subdomain with HTTPS, and zero server administration — you never touch a terminal unless you want to.

Frequently Asked Questions

What port does Hermes Agent use?

The Hermes Agent gateway listens on port 8642 by default. You can override this with the PORT environment variable. For production, bind the port to 127.0.0.1:8642 and proxy it through Caddy or nginx so the port is never exposed directly to the internet.

Where does Hermes Agent store its config and memory?

All persistent data lives under /home/node/.hermes inside the container. Mount this path to a named volume or a host directory to preserve config, credentials, and session memory across container restarts and image upgrades. Without a volume, the data is lost every time the container is replaced.

Can I run multiple Hermes Agent instances on the same host?

Yes. Give each container a unique name, a separate data volume, and a different host port (for example, 8642 and 8643). Each instance has its own config, credentials, and memory — they do not share state. Use separate reverse proxy entries (or separate subdomains) to expose each one over HTTPS.

How do I update to a newer Hermes Agent version?

Pull the new image tag, then recreate the container. With docker-compose, this is a single command:

docker compose pull hermes && docker compose up -d hermes

Because the data volume is separate from the container image, your config and memory are preserved across the upgrade. Always back up the volume before a major version bump just in case.

Do I need to rebuild the image when I change config?

No. The official Hermes Agent image is pre-built. You never rebuild it — only pull a newer tag when an upstream release is available. Config changes go into the mounted data directory or as env var overrides, then take effect after a container restart.

What's Next?

• Hermes Agent Desktop App — Run Hermes locally without Docker using the native desktop installer
• Hermes Agent on Windows — Windows-specific setup: WSL2, Docker Desktop, and the native installer
• Hermes Agent + Ollama — Point Hermes at a local Ollama server for private, offline agents
• Hermes Hosting on OpenClaw Launch — Managed Hermes containers with zero server administration