Hermes Agent Docker Compose Setup (2026)

Do not index

This image illustrates the setup process for the Hermes Agent using Docker Compose. It includes a step-by-step official image path and management service from $3.99 per month. Key features highlighted are a prerequisites checklist, the official compose.yml configuration, a secure dashboard accessible via port 9119, and channel verification. The visual shows a laptop screen with the docker-compose YAML file specifying the Hermes service details and environment configuration. Adjacent elements visualize the Hermes service container, Redis Alpine container, and active channels with status indicators, as well as the Hermes dashboard URL (https://localhost:9119) showing a healthy status. This setup enables users to deploy and monitor the Hermes Agent efficiently with Docker Compose.

A Hermes agent Docker Compose setup is the official DIY path to an always-on Hermes gateway. You run nousresearch/hermes-agent, mount ~/.hermes to /opt/data, start with docker compose up -d, and optionally enable the dashboard on port 9119. This page is the step-by-step setup. For a shorter Compose overview, see Hermes Docker Compose. If you want Hermes online without YAML, Agent 37 starts at $3.99/mo (1 vCPU, 4 GB RAM, 8 GB storage).

What do you need before a Hermes agent Docker Compose setup?

Before you start a hermes agent docker compose setup, gather a Linux VPS or Docker Desktop host, SSH access (not a broken browser console), and model API keys. Comfortable DIY floor: 2 vCPU, 4 GB RAM, 40 GB SSD.

This image outlines the essential prerequisites required before starting the Hermes Agent Compose setup using Docker. It lists five key items: Docker Engine plus Compose plugin, the /.hermes data directory, BYOK model API keys, channel plans for Telegram, Discord, and Slack, and the dashboard authorization decision for port 9119. The visual includes a stylized portrait of a person with headphones on the left and is branded with 'Agent 37' in the bottom right corner. This information is useful for developers and system administrators preparing to deploy Hermes Agent services.

Checklist:

Docker Engine + Compose plugin installed (docker compose version)

Empty or existing ~/.hermes directory for state

BYOK keys ready (Anthropic, OpenAI, OpenRouter, or Nous Portal)

One channel plan (Telegram, Discord, Slack, or WhatsApp)

Decision on dashboard: local tunnel only, or auth on 9119

Official Docker reference: Hermes Docker Setup.

How do you run a Hermes agent Docker Compose setup?

This image outlines the five-step setup process for deploying the Hermes Agent using Docker Compose. The steps include: 1) Starting the Hermes Setup Wizard; 2) Writing a compose.yml file specifying the Hermes agent image, port mapping (9119:9119), volume mounts, and restart policy; 3) Running 'docker compose up -d' to create the network and start the containers for hermes-agent and hermes-db; 4) Authenticating on port 9119 via a login interface; and 5) Verifying the communication with a channel reply indicating the Hermes Agent is online and ready. This visual guide aids in quickly setting up and verifying the Hermes Agent environment using containerization.

Run the setup in this order: wizard once, write Compose, start detached, secure the dashboard, then verify channels.

Step 1: One-time Hermes setup wizard

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Use SSH. Browser VPS consoles often corrupt : and @ on paste. Keys land in ~/.hermes/.env.

Step 2: Create `docker-compose.yml`

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"
      - "9119:9119"
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_DASHBOARD=1
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

Mount is always ~/.hermes:/opt/data. Never mount over /opt/hermes. Never run two gateway containers against the same data directory.

Step 3: Start and follow logs

docker compose up -d
docker compose logs -f

Inside the published image, gateway run is s6-supervised. With HERMES_DASHBOARD=1, the dashboard restarts beside the gateway.

Step 4: Secure dashboard port 9119

Non-loopback binds require an auth provider. HERMES_DASHBOARD_INSECURE is a deprecated no-op after the June 2026 hardening.

For a homelab or Tailscale box, set:

HERMES_DASHBOARD_BASIC_AUTH_USERNAME

HERMES_DASHBOARD_BASIC_AUTH_PASSWORD

HERMES_DASHBOARD_BASIC_AUTH_SECRET (stable sessions)

Prefer an SSH tunnel or Tailscale over a naked public bind. OAuth / OIDC options are documented for public deploys. UI context: Hermes agent dashboard.

Step 5: Verify the setup worked

docker compose ps shows the container healthy / running

A test message on your channel gets a reply with the laptop closed (or after docker stop is not the case; leave it running)

Dashboard loads only after auth (or via tunnel)

~/.hermes still holds sessions after docker compose down then up -d

Hermes agent Docker Compose setup vs managed hosting

This image provides a side-by-side comparison of two setups for managing container composition: a DIY Compose Setup and the Agent 37 managed service. It highlights the key differences, indicating that the DIY Compose Setup requires users to manage compose files and pins, bear costs of $6 to $12 per month for VPS, handle authentication and TLS themselves, and manage upgrade procedures. In contrast, Agent 37 offers a fully managed service with no compose babysitting, a starting price of $3.99 per month, a browser-based terminal, and deployment capability in under 5 minutes. The image aims to help users decide between self-managed YAML-based setups or an easier-to-use managed alternative.

Use Compose when you already staff Docker. Use managed when channels equal revenue.

Path	Price	Who owns ops	Best for
Hermes agent Docker Compose setup	About $6 to $12/mo VPS	You	Platform engineers
Hermes Desktop + Compose backend	Same VPS + laptop	You	Desktop UI fans
Agent 37 Basic	$3.99/mo	Platform	Production default
Agent 37 Pro	$29.99/mo	Platform	Browser-heavy work

Desktop wiring: Hermes Desktop Docker. Fast managed path: deploy Hermes.

How do you upgrade after the first Hermes agent Docker Compose setup?

docker compose pull
docker compose up -d

State survives because /opt/data is on the host. Pin a release tag or digest in production instead of floating on :latest forever.

For unattended gateways, enable tool-loop hard stops in config.yaml so a stuck loop cannot burn tokens forever. Official docs cover tool_loop_guardrails.hard_stop_enabled.

How much does this setup cost?

Hermes agent software is free. You pay for the VPS, tokens (BYOK), and your time.

Tier	Price	Specs	Typical use
DIY Compose VPS	About $6 to $12/mo	2 vCPU / 4 GB class	Engineers who own Docker
Agent 37 Basic	$3.99/mo	1 vCPU, 4 GB, 8 GB	Skip Compose
Plus	$9.99/mo	1 vCPU, 4 GB, 12 GB	Bundled free models
Pro	$29.99/mo	2 vCPU, 8 GB, 20 GB, Chromium	Browser workloads
Max	$99.99/mo	4 vCPU, 16 GB, 40 GB	Teams

White-label API from $1.99 per agent per month, billed per minute. Start at Agent 37 pricing.

Common setup failures

Wrong volume path, so memory disappears after recreate

Publishing 9119 without an auth provider

Two containers sharing one ~/.hermes

Treating :latest as a rollback strategy

Expecting Docker Desktop on a sleeping laptop to stay online

Broader Compose framing: Hermes Docker Compose. Hosting ranking: Hermes agent hosting.

Frequently Asked Questions

What is the official image for a Hermes agent Docker Compose setup?

nousresearch/hermes-agent (often :latest). Mount ~/.hermes to /opt/data and run gateway run.

Is hermes setup the same as Docker Compose setup?

No. hermes setup (or the container wizard) writes keys and config once. Compose is how you keep the gateway running.

Do I need both ports 8642 and 9119?

8642 is API / health. Chat-only channels often skip publishing it. 9119 is the dashboard when HERMES_DASHBOARD=1.

Can I point Hermes Desktop at this setup?

Yes. Enable the dashboard, then add a Remote Gateway on 9119. Guide: Hermes Desktop Docker.

When should I skip this setup?

When you need per-client isolation or you will not staff Docker upgrades. Use Agent 37 from $3.99/mo instead.

Hermes Agent Docker Compose Setup: Step-by-Step Guide (2026)