Hermes Docker: Run the Hermes Agent in Docker (2026)

Do not index

To run Hermes in Docker, pull the official nousresearch/hermes-agent image from Docker Hub, run the one-time setup wizard, then start the gateway with your ~/.hermes folder mounted to /opt/data. Any Linux server with 2 GB of RAM can do it, and your agent's memory survives every restart and update. This Hermes Docker guide walks through the exact commands, the official Docker Compose file, channel setup, updates, and the honest math on when a managed host like Agent37 beats running the container yourself.

What "Hermes Docker" actually means

Hermes is the open-source personal agent from Nous Research: one gateway process that answers you on Telegram, WhatsApp, Discord, Slack, and 20+ other platforms, with persistent memory, skills, and scheduled jobs. The GitHub repo is MIT-licensed and sits at 232,000+ stars as of August 2026.

Docker is a Tier 1 supported platform for it. The official image is nousresearch/hermes-agent on Docker Hub, with nearly 8 million pulls, published for both x86_64 and ARM64.

Two things trip people up before they even start:

Wrong image. Docker Hub has several unrelated projects named "hermes" (a Cosmos blockchain relayer, an old Tomcat messaging server). If the image name is not nousresearch/hermes-agent, it is not this agent. Some third-party guides also print a ghcr.io path that does not exist publicly; use Docker Hub.

Container vs. sandbox. Running Hermes in Docker (this guide) is different from Hermes's terminal.backend: docker setting, which keeps the agent on your host but sandboxes its shell commands inside a container. You can use either, or both.

What Hermes needs before you start

The requirements are modest. From the official docs:

Resource	Minimum	Recommended
RAM	1 GB	2 to 4 GB
CPU	1 core	2 cores
Disk (data volume)	500 MB	2 GB+

Browser automation is the hungry part: without it 1 GB of RAM holds up, with Playwright and Chromium in play give the container at least 2 GB.

You also need an LLM API key (OpenRouter, Anthropic, OpenAI, Google, and a dozen others are supported), and the model you pick must have at least a 64,000-token context window or Hermes refuses to start. The agent itself is free software: what you pay for is model usage and somewhere always-on to run it.

On VPS sizing: a 2 GB box is the realistic floor. Hetzner's entry cloud server (CX23, 2 vCPU / 4 GB) is €5.49/mo after the 2026 price rises, but only in its EU regions; its US locations start around $20/mo. DigitalOcean's famous $4/mo droplet has 512 MB of RAM, which is below Hermes's minimum, so you are really looking at $6 to $12/mo there. Our VPS guide for Hermes compares the options in detail.

Hermes Docker setup, step by step

Two commands. First, the one-time setup wizard, which asks for your API keys and writes them into ~/.hermes/.env:

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

Then start the gateway as a persistent background container:

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

That is a running Hermes. Check it with docker logs -f hermes.

What the pieces do:

-v ~/.hermes:/opt/data is the single mount that matters. Everything Hermes is lives there: .env secrets, config.yaml, its SOUL.md personality file, memories, sessions, skills, cron jobs, logs. The image itself is stateless, which is exactly what makes updates safe.

Port 8642 serves an optional OpenAI-compatible API and health endpoint. If you only want chat platforms, you can drop the -p flag entirely.

--restart unless-stopped plus the image's internal supervisor means the gateway comes back on crashes and reboots.

One warning from the docs worth repeating: never run two gateway containers against the same data directory. Session files and memory stores are not safe for concurrent writes.

The Hermes Docker Compose file

For anything long-lived, use Compose. This is the official example, lightly annotated:

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"   # gateway API (optional)
      - "9119:9119"   # dashboard (only active with HERMES_DASHBOARD=1)
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_DASHBOARD=1
      # Forward specific env vars instead of using the .env file:
      # - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

Bring it up with docker compose up -d.

Two adjustments worth making:

Pin the version. latest moves near-daily (Nous ships date-tagged releases like v2026.8.18). Pinning a date tag means you choose when to upgrade and can roll back by changing one line.

Match the container user to your host user if you plan to edit files in ~/.hermes directly. The repo's own compose file does this with HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d.

The dashboard on port 9119 is genuinely useful (chat, sessions, config in the browser), but treat it as localhost-only. Since the June 2026 hardening it fails closed rather than serving unauthenticated on a public interface; the sane pattern on a VPS is to keep it bound to loopback and reach it over an SSH tunnel: ssh -L 9119:localhost:9119 you@your-server.

Connecting WhatsApp, Telegram, and iMessage from inside the container

The channel wizard runs fine inside the container:

docker exec -it hermes hermes gateway setup

Channel notes that save real debugging time:

Telegram is the five-minute path: create a bot with BotFather, paste the token, then set your numeric user ID as an allowed user so strangers cannot talk to your agent.

WhatsApp pairs by QR code, and the QR renders right in the terminal where the wizard runs. If it comes out garbled, widen your terminal (60+ columns) and re-pair. The session credentials land inside ~/.hermes, so they survive container recreation; you scan once, not every restart.

iMessage works from a Linux container via BlueBubbles, but BlueBubbles itself needs a Mac that stays on with Messages signed in. The alternative is Photon, a managed iMessage bridge that needs no Mac at all.

All channel credentials live in the mounted volume, which means recreating the container never logs you out.

Updates and backups without losing your agent's memory

The one Docker-specific gotcha: hermes update does not work inside a container. The docs are explicit about this. Updating is done by replacing the image:

docker compose pull
docker compose up -d

Your agent's memory, sessions, and config all live in ~/.hermes on the host, so this is safe by design. On first start after an upgrade, Hermes runs its config migrations automatically and writes timestamped backups of config.yaml and .env before touching them.

Backups are equally boring, which is the point:

tar -czf hermes-backup-$(date +%F).tar.gz ~/.hermes

Stop the container first if you want a perfectly consistent snapshot. Restoring on a new server is untarring that archive and running the same compose file. This is also the migration path from a native install to Docker: same folder, same contract.

Hermes Docker troubleshooting

The failure modes are consistent enough that most map to one of four fixes:

Symptom	Likely cause	Fix
`Permission denied: /opt/data/config.yaml`	Container user does not own the host folder (very common on NAS boxes)	Set `HERMES_UID`/`HERMES_GID` to your host user's IDs and recreate, or `chown -R` the `~/.hermes` folder
Agent dies mid-task with browser tools on	Out of memory	Raise the container memory limit to 4 GB, or disable browser automation
Model rejected at startup	Context window under 64k tokens	Pick a larger-context model
WhatsApp QR unreadable	Terminal too narrow for Unicode rendering	Widen to 60+ columns and re-run pairing

For anything else, docker logs hermes and docker exec -it hermes hermes doctor cover most of it.

Raspberry Pi and ARM: the official image ships for ARM64, so a Pi 4 or Pi 5 on a 64-bit OS works, with 2 GB of RAM as the practical floor and browser automation best left off. 32-bit OS images will not run it.

Docker on a VPS vs. managed Hermes hosting

Here is the honest version, since we sell one side of it.

DIY Hermes Docker is genuinely good. The official image is well-maintained, the single-volume contract makes it hard to lose data, and if you already run a home server or VPS with other containers, adding Hermes is an evening project. Total cost: roughly $6 to $12/mo for a suitable VPS plus your model API usage, and you own every part of the stack.

What you are signing up for is the ops loop: watching releases, pulling images, keeping an eye on RAM, tunneling into the dashboard, and being the person who notices when the agent went quiet at 2 a.m. None of it is hard. All of it is recurring.

Agent37 exists for people who want the always-on agent without that loop: a managed Hermes instance from $3.99/mo (1 vCPU, 4 GB RAM), deployed in one click, with a task board, web terminal, file browser, live desktop, and runtime updates handled for you. No SSH, no compose file, no server to patch. BYOK, so your model keys go straight to the provider, and it runs OpenClaw on the same dashboard if you use both agents. We are YC-backed and SOC 2 Type I audited, and the honest downside at this price: support is community plus an AI bot, not a human on call.

If you are building Hermes for other people, the Cloud API provisions isolated always-on Hermes instances behind one API call, from $1.99/mo shared or $4.94/mo dedicated per instance (2 vCPU / 4 GB), white-label by default. New workspaces get a $1 starter credit with no card.

Other managed lanes exist: Hivra (formerly HermesOS) hosts Hermes alongside other agents from $9.99/mo after a card-required trial. If Hermes-in-the-browser is all you want, compare both.

Hermes Docker FAQ

Can Hermes run in Docker Compose?

Yes, it is the recommended way to run it long-term. The official docs ship a Compose example (above): one service, one volume mount, command: gateway run.

How much RAM does Hermes need in Docker?

1 GB minimum, 2 to 4 GB recommended. Browser automation is what pushes you to the high end. The docs' own line is that it runs on a $5 VPS, which was true before Hetzner's June 2026 price rise; the EU floor is now about €5.49 (~$6.50)/mo, and US pricing for the same specs runs higher.

Does `hermes update` work in Docker?

No. Update by pulling the new image and recreating the container. Your data directory carries everything across.

Is "Hermes Docker" the same as "Hermes agent Docker"?

Same thing: the Hermes agent runtime containerized. The only genuinely different thing is terminal.backend: docker, which sandboxes the agent's shell commands while Hermes runs on the host.

Does the Hermes Docker image run on a Raspberry Pi?

Yes, on ARM64 with a 64-bit OS and at least 2 GB of RAM. Leave browser automation off on a Pi.

Where does my agent's data live?

Entirely in the mounted volume: host ~/.hermes, container /opt/data. Config, secrets, memory, sessions, skills, cron jobs, logs. Back that folder up and you have backed up the agent.

What if I do not want to run Docker at all?

That is what managed hosting is for. Agent37 runs Hermes always-on from $3.99/mo: one click to deploy, chat channels connect from the browser, updates roll out automatically. Try it alongside a DIY container for a week and keep whichever fits.

Hermes Docker: How to Run the Hermes Agent in Docker (2026 Guide)