Hermes Agent Docker Compose: Self-Host Setup Guide

To self-host Hermes Agent with Docker Compose, pull the nousresearch/hermes-agent image, run the gateway run command, and mount your host ~/.hermes directory to /opt/data inside the container so config, memory, sessions, and skills persist across restarts. Hermes Agent is Nous Research's open-source (MIT-licensed) self-improving AI agent, and the official repository ships a working docker-compose.yml with both a gateway service and an optional dashboard service that you can adapt in a few minutes.

Prerequisites

Running Hermes Agent in Docker Compose requires Docker Engine, the Compose plugin, and at least one large language model API key. The official image, nousresearch/hermes-agent, bundles its Python 3.11 runtime, the gateway server, and bundled plugins, so you do not install Python or Node.js on the host yourself.

Before you write a compose file, confirm the basics on your machine or VPS:

• Docker Engine 24+ and the Compose v2 plugin. Run docker compose version to confirm Compose is installed as a subcommand, not the legacy docker-compose binary.
• An LLM provider key. Hermes supports Nous Portal, OpenRouter, OpenAI, Anthropic, and custom OpenAI-compatible endpoints per the official Nous Research repository.
• Roughly 2 GB of RAM free. A small gateway runs comfortably in a low-cost VPS tier; browser automation (Playwright/Chromium) needs --shm-size=1g and more headroom.
• A persistent host directory such as ~/.hermes that you control and back up.

As of the v0.17.0 release (June 2026), the project documents Docker, docker-compose.yml, and a Windows-specific compose file in the repo, confirmed in the GitHub releases page. If you have never touched the agent before, our Hermes Agent setup guide walks through first-run configuration before you containerize it.

The docker-compose.yml file

The Hermes Agent docker-compose file defines a long-running gateway service plus an optional dashboard service, both backed by the same data volume. The snippet below mirrors the structure of the official docker-compose.yml — treat it as a representative template and check the repo for the current canonical version before deploying.

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: ["gateway", "run"]
    network_mode: host
    env_file:
      - ~/.hermes/.env
    environment:
      HERMES_UID: "10000"
      HERMES_GID: "10000"
    volumes:
      - ~/.hermes:/opt/data

  dashboard:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-dashboard
    restart: unless-stopped
    depends_on:
      - hermes
    command: ["dashboard", "--host", "127.0.0.1", "--no-open"]
    network_mode: host
    environment:
      HERMES_UID: "10000"
      HERMES_GID: "10000"
    volumes:
      - ~/.hermes:/opt/data

A few details matter. The gateway runs as a non-root user (UID/GID 10000) and keeps its immutable install tree at /opt/hermes while all writable state lives under /opt/data. The repo's compose file uses network_mode: host; if you prefer explicit port mapping instead, drop host networking and publish the gateway port (commonly 8642) and dashboard port under a ports: block. For a side-by-side with the OpenClaw lineage equivalent, see our OpenClaw Docker Compose guide.

Environment and configuration

Hermes Agent reads secrets and provider settings from an .env file and a config.yaml, both stored in the mounted data directory rather than inside the image. This keeps API keys out of your compose file and out of version control.

The table below lists the environment variables you are most likely to set when containerizing the gateway.

Put the keys in ~/.hermes/.env and reference that file from compose with env_file, as shown above. Never commit provider keys or messaging bot tokens to git, and rotate any key that has ever been pasted into a chat or shared screen. For the underlying choice of provider and what it costs to run, our Hermes Agent cost breakdown covers token economics in detail.

Volumes for persistence

Persistence in a Hermes Agent container depends on one bind mount: the host ~/.hermes directory mapped to /opt/data inside the container. Everything the agent learns and stores lives there, so if you skip this mount, the container loses its memory and configuration on every recreate.

The data directory holds these contents, per the official Docker documentation:

• .env — API keys and secrets
• config.yaml — model selection, enabled tools, and gateway settings
• sessions/ — conversation history
• memories/ — the agent's persistent, self-curated memory
• skills/ — installed and self-generated skills
• logs/ — runtime logs

You can use a host bind mount (~/.hermes:/opt/data) or a named Docker volume; the bind mount is easier to back up because the files sit in a normal directory. Because the container runs as UID 10000, ensure that user can write to the host directory — set HERMES_UID/HERMES_GID to match your host ownership if you hit permission errors. Back up the whole directory the same way you would any stateful service.

Running and updating Hermes Agent

You start the stack with docker compose up -d and update it with a pull-and-recreate cycle that preserves your data volume. Because all state lives in /opt/data, swapping the image does not touch your memory, sessions, or skills.

The core lifecycle commands:

# First run: bring the gateway (and dashboard) up
docker compose up -d

# Confirm it is healthy
docker compose logs -f hermes
docker compose exec hermes hermes doctor

# Update to the latest image
docker compose pull
docker compose up -d

# Stop / remove
docker compose down

Run hermes doctor inside the container before sending production traffic — it diagnoses missing keys, model misconfiguration, and connectivity problems. For remote access, do not bind the dashboard or API server to 0.0.0.0 on a public VPS. Keep the dashboard on 127.0.0.1 and reach it over an SSH tunnel, Tailscale, or WireGuard, or place an authenticated reverse proxy (Caddy, Nginx, Traefik) with HTTPS in front. The community documentation covers reverse-proxy patterns in more depth.

Limitations and Tradeoffs

Docker Compose is the right tool for a single-host Hermes Agent deployment, but it is not a fit for every situation. Compose orchestrates containers on one machine; it does not give you multi-node scheduling, rolling deploys, or built-in failover the way Kubernetes does.

Other tradeoffs worth weighing before you commit:

• Browser tools need extra config. Playwright/Chromium-based skills require --shm-size=1g (or an equivalent shm_size in compose), which adds memory pressure on small VPS tiers.
• You own the security surface. Self-hosting means you are responsible for TLS, auth, key rotation, and network exposure — there is no managed layer doing it for you.
• Host networking is convenient but blunt. The repo's default network_mode: host simplifies messaging callbacks but bypasses Docker's port isolation; use explicit port mapping if you need tighter control.
• When not to use it: if you only want to try Hermes for a few minutes, the one-line native installer or hermes CLI is faster than writing a compose file. Reach for Compose when you want a durable, restart-safe, long-running gateway.

If you are still deciding between Hermes Agent and an OpenClaw-style stack for your use case, our OpenClaw vs Hermes Agent comparison lays out the differences, and the Hermes Agent self-hosted guide covers the non-Docker installation path.

Related Guides

• Hermes Agent Self-Hosted Guide
• Hermes Agent Setup Guide
• Hermes Agent Cost Breakdown
• OpenClaw Docker Compose Guide