Hermes Agent Docker: Complete Deployment Guide for 2026

Two Docker Modes Explained — Choose Before You Start

Most guides skip this decision entirely and jump to docker run. Don't. The two modes have meaningfully different security and operational profiles.

Mode 1 — Hermes Running Inside a Container

Hermes and all its dependencies live inside the image. You manage state via named volumes. The container restart policy keeps it alive across reboots. This is the most common production pattern.

• Clean separation from host — no accidental writes to your machine
• Full portability; redeploy anywhere with the same compose file
• Slightly higher overhead than running natively

Mode 2 — Docker as a Terminal Backend Sandbox

Here, Hermes runs directly on the host (or in a container) and calls out to the Docker daemon to spin up ephemeral containers for shell execution. You configure it by setting DOCKER_HOST so Hermes can reach the daemon:

export DOCKER_HOST=unix:///var/run/docker.sock   # Linux
export DOCKER_HOST=tcp://host.docker.internal:2375  # Windows/Mac (Docker Desktop)

Prerequisites and Environment Setup

Before pulling any image, confirm:

• Docker Engine 24+ or Docker Desktop 4.26+
• An LLM API key ready: OpenAI (OPENAI_API_KEY), Anthropic (ANTHROPIC_API_KEY), or a local Ollama endpoint
• Outbound internet access on port 443 (for LLM API calls)
• At least 2 GB RAM allocated to the container (4 GB recommended for Ollama-backed setups)

Windows-Specific Setup (Docker Desktop + WSL2)

Windows is where most Docker deployments quietly break. Watch for these:

# Correct — Docker Desktop translates this automatically
volumes:
  - hermes_data:/root/.hermes

DOCKER_HOST=npipe:////./pipe/docker_engine

[wsl2]
memory=4GB
processors=2

Quick Start — Run Hermes Agent with Docker in 5 Minutes

Pull the official image and run the setup wizard:

# Pull the latest image
docker pull nousresearch/hermes-agent:latest

# Run with a persistent volume for state
docker run -it \
  -v hermes_home:/root/.hermes \
  -e OPENAI_API_KEY=your_key_here \
  nousresearch/hermes-agent:latest

The setup wizard launches on first run. It will prompt you to:

1. Select your LLM provider (OpenAI, Anthropic, Ollama, or custom endpoint)
2. Enter your API key or endpoint URL
3. Configure the terminal backend (native or Docker sandbox)

Once complete, verify the session is working:

> hello

Production Deployment with Docker Compose

The bare docker run command works for testing. For anything persistent, use Compose.

version: "3.9"

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-agent
    restart: unless-stopped
    stdin_open: true
    tty: true

    environment:
      # Use environment secrets — never hardcode keys in compose files
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      HERMES_LOG_LEVEL: info

    volumes:
      - hermes_home:/root/.hermes         # Config + conversation history
      - hermes_skills:/root/.hermes/skills # Skill store — see next section

    deploy:
      resources:
        limits:
          memory: 2G
          cpus: "1.5"

    healthcheck:
      test: ["CMD", "hermes", "--health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  hermes_home:
  hermes_skills:

Store your API keys in a .env file (never committed to version control):

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Preserving Hermes Skills Across Container Rebuilds

This is the most overlooked production concern. Hermes stores learned skills separately from general config. Mount these paths explicitly:

When updating the image:

docker compose pull
docker compose up -d   # Named volumes persist automatically

Advanced Topology — Host-Docker (Sibling Container) Setup

This architecture is used when you want Hermes to orchestrate sibling containers for isolated code execution — for example, running user-submitted code safely.

┌─────────────────────────────────┐
│         Docker Host             │
│                                 │
│  ┌──────────────┐               │
│  │ hermes-agent │◄──socket──────┤── /var/run/docker.sock
│  │  container   │               │
│  └──────┬───────┘               │
│         │ docker run (sibling)  │
│  ┌──────▼───────┐               │
│  │  sandbox-1   │  (ephemeral)  │
│  └──────────────┘               │
└─────────────────────────────────┘

Compose configuration for this topology:

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    restart: unless-stopped
    environment:
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      DOCKER_HOST: unix:///var/run/docker.sock
      HERMES_TERMINAL_BACKEND: docker
    volumes:
      - hermes_home:/root/.hermes
      - /var/run/docker.sock:/var/run/docker.sock  # Socket mount
    group_add:
      - "999"   # docker group GID — adjust to match your host

Connecting Hermes to Claude via Telegram Bot

No written guide currently covers this — it's only shown in video form. Here's the full setup.

/newbot
→ Name: Hermes Agent
→ Username: your_hermes_bot
→ Save the token: 123456:ABC-DEF...

environment:
  ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
  HERMES_LLM_PROVIDER: anthropic
  HERMES_TELEGRAM_TOKEN: ${TELEGRAM_BOT_TOKEN}
  HERMES_TELEGRAM_ALLOWED_USERS: "your_telegram_user_id"

docker compose up -d

Multi-Architecture Deployment (ARM64 / Oracle Free Tier / Raspberry Pi)

The nousresearch/hermes-agent image ships as a multi-arch manifest. ARM64 is supported — pull it explicitly on ARM hosts:

# Oracle Free Tier (Ampere A1) or Raspberry Pi 4/5
docker pull --platform linux/arm64 nousresearch/hermes-agent:latest

# Verify the architecture
docker inspect nousresearch/hermes-agent:latest | grep Architecture

Known ARM-specific issues:

• Some Ollama model quantizations (Q8) run slower on ARM; prefer Q4_K_M for local inference
• If you hit exec format error, confirm you're using the --platform linux/arm64 flag
• Docker Desktop on Apple Silicon handles ARM natively — no platform flag needed

Troubleshooting Common Hermes Agent Docker Failures

A reference table for the failures you're most likely to encounter:

Frequently Asked Questions

Final Thoughts: Checklist and Next Steps

The learning loop is what separates Hermes from every other agent you've run in Docker. The setup above ensures that loop actually accumulates — not resets — every time you ship an update.

Before calling a deployment production-ready, confirm:

• ☐ Named volumes created for both hermes_home and hermes_skills
• ☐ API keys stored in .env, not hardcoded in compose
• ☐ restart: unless-stopped policy active
• ☐ Health check passing: docker inspect hermes-agent --format='{{.State.Health.Status}}'
• ☐ Log rotation configured (max-size, max-file)
• ☐ Resource limits set to prevent memory exhaustion
• ☐ Setup wizard completed and first chat session verified
• ☐ (If Mode 2) Docker socket mount confirmed and socket proxy considered

Next steps to get value immediately:

1. Run a few real tasks — file summarization, code review, web research — to seed the skill library
2. After 10–15 tasks, run hermes skills list to see what's been learned
3. Review the Nous Research GitHub for agent configuration docs covering custom skill templates and memory tuning
4. If you're on Oracle Free Tier, set up a cron-based docker compose pull && docker compose up -d for zero-downtime image updates while preserving learned state