Table of Contents
- What "Hermes Docker" actually means
- What Hermes needs before you start
- Hermes Docker setup, step by step
- The Hermes Docker Compose file
- Connecting WhatsApp, Telegram, and iMessage from inside the container
- Updates and backups without losing your agent's memory
- Hermes Docker troubleshooting
- Docker on a VPS vs. managed Hermes hosting
- Hermes Docker FAQ
- Can Hermes run in Docker Compose?
- How much RAM does Hermes need in Docker?
- Does hermes update work in Docker?
- Is "Hermes Docker" the same as "Hermes agent Docker"?
- Does the Hermes Docker image run on a Raspberry Pi?
- Where does my agent's data live?
- What if I do not want to run Docker at all?
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
nousresearch/hermes-agent on Docker Hub, with nearly 8 million pulls, published for both x86_64 and ARM64.- 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 aghcr.iopath that does not exist publicly; use Docker Hub.
- Container vs. sandbox. Running Hermes in Docker (this guide) is different from Hermes's
terminal.backend: dockersetting, 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
Resource | Minimum | Recommended |
RAM | 1 GB | 2 to 4 GB |
CPU | 1 core | 2 cores |
Disk (data volume) | 500 MB | 2 GB+ |
Hermes Docker setup, step by step
~/.hermes/.env:mkdir -p ~/.hermes
docker run -it --rm \
-v ~/.hermes:/opt/data \
nousresearch/hermes-agent setupdocker run -d \
--name hermes \
--restart unless-stopped \
-v ~/.hermes:/opt/data \
-p 8642:8642 \
nousresearch/hermes-agent gateway rundocker logs -f hermes.-v ~/.hermes:/opt/datais the single mount that matters. Everything Hermes is lives there:.envsecrets,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
8642serves an optional OpenAI-compatible API and health endpoint. If you only want chat platforms, you can drop the-pflag entirely.
--restart unless-stoppedplus the image's internal supervisor means the gateway comes back on crashes and reboots.
The Hermes Docker Compose file
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"docker compose up -d.- Pin the version.
latestmoves near-daily (Nous ships date-tagged releases likev2026.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
~/.hermesdirectly. The repo's own compose file does this withHERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d.
ssh -L 9119:localhost:9119 you@your-server.Connecting WhatsApp, Telegram, and iMessage from inside the container
docker exec -it hermes hermes gateway setup- 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.
Updates and backups without losing your agent's memory
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~/.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.tar -czf hermes-backup-$(date +%F).tar.gz ~/.hermesHermes Docker troubleshooting
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 |
docker logs hermes and docker exec -it hermes hermes doctor cover most of it.Docker on a VPS vs. managed Hermes hosting
Hermes Docker FAQ
Can Hermes run in Docker Compose?
command: gateway run.How much RAM does Hermes need in Docker?
Does hermes update work in Docker?
Is "Hermes Docker" the same as "Hermes agent Docker"?
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?
Where does my agent's data live?
~/.hermes, container /opt/data. Config, secrets, memory, sessions, skills, cron jobs, logs. Back that folder up and you have backed up the agent.