Hermes Agent Docker Setup (2026)

Do not index

A Hermes agent Docker setup starts with the official nousresearch/hermes-agent image and a one-time setup wizard. You mount host ~/.hermes to /opt/data, run setup once for keys and channels, then either stop there (interactive) or switch to gateway run with Docker Compose for an always-on bot. This page covers both paths. For Compose-only steps, see Hermes agent Docker Compose setup. To skip Docker entirely, Agent 37 runs Hermes on managed isolation from $3.99/mo (1 vCPU, 4 GB RAM, 8 GB storage).

What is a Hermes agent Docker setup?

Hermes agent Docker setup means running Nous Research's Hermes agent inside a Linux container instead of a bare-metal install. The container is disposable. Your agent state (keys, sessions, memory, skills) lives on a host volume at ~/.hermes, mounted to /opt/data inside the image.

This image provides a comparative overview of two methods to run Hermes agents using Docker: the one-time setup wizard and the always-on gateway. The one-time setup involves running an interactive Docker command once to connect keys and channels, saving the configuration for later use, ideal for quick starts. The always-on gateway method runs a persistent Docker container for continuous 24/7 agent operations, supporting ongoing channel traffic and ensuring reliability and resilience. Each approach includes example Docker commands, accompanied by key benefits and operational scenarios, enabling users to choose the best option based on their deployment needs.

Path	Command shape	Best for
One-time wizard	`docker run ... setup`	First keys, channels, config
Always-on gateway	`gateway run` via Compose	24/7 Telegram, Slack, Discord, WhatsApp
Managed Hermes	Agent 37 template	Skip Docker ops, same dashboard as OpenClaw, Claude Code, Codex, OpenCode, Grok CLI

Official reference: Hermes Docker Setup.

Do not confuse this with "Docker as a terminal backend," where Hermes runs on the host and only tool commands land in a sandbox container. This page is Hermes in Docker.

What do you need before a Hermes agent Docker setup?

Before you run a hermes agent docker setup, gather:

Docker Engine with the Compose plugin (docker compose version)

Linux VPS or Docker Desktop with SSH (browser VPS consoles often break : and @ on paste)

Model API keys (Anthropic, OpenAI, OpenRouter, or Nous Portal) for BYOK

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

Comfortable floor: 2 vCPU, 4 GB RAM, 40 GB SSD for a solo always-on gateway

Empty or existing ~/.hermes is fine. The wizard writes into it on first run.

How do you run the Hermes agent Docker setup wizard?

The setup wizard is a one-time interactive pass. It writes keys and channel tokens to ~/.hermes/.env.

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

Run this over SSH, not a broken browser terminal. When the wizard finishes, your data directory holds config, keys, and channel hooks.

This step alone does not keep Hermes online after you close the session. For 24/7 channels, move to gateway run (next section) or use Compose.

How do you keep Hermes running after Docker setup?

This image provides a clear, step-by-step visual guide for setting up the Hermes Agent using Docker. It outlines four major steps: 1) Installing Docker with verification commands and ensuring Docker Desktop is running; 2) Running the Hermes Setup Wizard via a Docker command to choose model and settings and generate configuration; 3) Starting the Hermes agent either through 'gateway run' or Docker Compose with corresponding commands and checks for agent activity and health; 4) Securing access to the dashboard on port 9119 by setting the DASHBOARD_PASS environment variable and accessing the dashboard URL. The image is designed as an official Nous Research instructional graphic and is suited for user onboarding and technical documentation.

After the wizard, pick one of two always-on shapes.

Option A: Docker Compose (recommended for VPS)

Write a docker-compose.yml and start detached:

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"

docker compose up -d
docker compose logs -f

Full step-by-step: Hermes agent Docker Compose setup.

Option B: Single `docker run` for gateway

For a quick test without Compose:

docker run -d --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Compose is still the better production default. It gives you one file, docker compose pull upgrades, and clearer rollback.

Volume rules (non-negotiable)

Mount is always ~/.hermes:/opt/data

Never mount over /opt/hermes (that is the application tree inside the image)

Never run two gateway containers against the same ~/.hermes directory

How do you secure the Hermes dashboard on port 9119?

When HERMES_DASHBOARD=1, the dashboard listens on 9119. Non-loopback binds require an auth provider. HERMES_DASHBOARD_INSECURE is a deprecated no-op after 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.

8642 is the OpenAI-compatible API / health port. Chat-only channel setups often skip publishing it.

Hermes agent Docker setup vs managed hosting

Use Docker setup when you already staff containers. Use managed when channels equal revenue or you need per-client isolation without building a control plane.

Path	Price	Who owns ops	Best for
Hermes agent Docker setup (DIY)	About $6 to $12/mo VPS + your time	You	Platform engineers
Hermes Desktop + Docker 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 Hermes workloads

On Agent 37, Hermes agent shares the same dashboard and isolation model as OpenClaw, Claude Code, Codex, OpenCode, and Grok CLI. Desktop wiring: Hermes Desktop Docker. Fast managed path: deploy Hermes.

How do you upgrade after Hermes agent Docker setup?

With Compose:

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 Hermes agent Docker setup cost?

This image presents a detailed pricing table for the Hermes Agent Docker setup across various service tiers. It highlights five pricing options: DIY VPS ($6-12/month), Basic ($3.99/month), Plus ($9.99/month), Pro ($29.99/month), and Max ($99.99/month). Each tier lists its key specifications such as the number of virtual CPUs (vCPU), RAM allocation, and management type. The Basic tier, currently emphasized, offers 2+ vCPUs, 4+ GB RAM, and managed isolation. Higher tiers offer increased vCPUs and RAM for enhanced performance. Additionally, the image notes an optional white-label API available from $1.99 per agent per month. This table serves as a professional reference for users evaluating Docker setup costs and specifications for Hermes Agent deployment.

Hermes agent software is free. You pay for compute, tokens (BYOK), and operator time.

Tier	Price	Specs	Typical use
DIY Docker 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 Docker setup
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 Hermes agent Docker setup failures

Wrong volume path, so memory disappears after recreate

Publishing 9119 without an auth provider

Two containers sharing one ~/.hermes

Running setup but never switching to gateway run for always-on channels

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 Hermes agent Docker setup?

nousresearch/hermes-agent (often :latest). Mount ~/.hermes to /opt/data. Run setup once, then gateway run for always-on.

Is Hermes agent Docker setup the same as Docker Compose setup?

Not exactly. Docker setup covers the wizard plus either Compose or a single docker run gateway. Compose setup is the always-on YAML path only. See Hermes agent Docker Compose setup.

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 Docker setup?

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

When should I skip Hermes agent Docker setup?

When you need per-client isolation, predictable upgrades, or you will not staff Docker patches. Use Agent 37 from $3.99/mo instead. Same dashboard covers Hermes agent, OpenClaw, Claude Code, Codex, OpenCode, and Grok CLI.

Hermes Agent Docker Setup: Official Image, Wizard, and Always-On Gateway (2026)