.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Native install gets you running in 90 seconds. Docker Compose gets you running in five minutes but gives you something worth the extra time: clean upgrades, isolation from the host, identical setup across machines and the ability to tear the whole thing down and rebuild it with one command. If you're hosting Hermes for any reason other than personal experimentation, Compose is the boring-and-correct deployment shape.
This guide is for people who already know Docker. If you're new to containers, the native Ubuntu install is friendlier as a starting point. The LumaDock VPS setup guide covers the gentler 1-click route. Come back here once you want the operational benefits Compose brings.
What you'll end up with
One Compose file orchestrating two services: hermes (the gateway) and optionally watchtower (an automatic image updater, for the people who want auto-upgrades). State persists in a named volume so destroying and recreating the container doesn't lose your memories or skills. The container exposes ports for the dashboard and any messaging gateways that need inbound webhooks (Slack, custom HTTP).
The Compose file
Save as docker-compose.yml in a directory you control (I use /opt/hermes on production boxes):
services:
hermes:
image: ghcr.io/nousresearch/hermes-agent:latest
container_name: hermes
restart: unless-stopped
volumes:
- hermes-data:/root/.hermes
- ./env:/root/.hermes/.env:ro
environment:
HERMES_HOME: /root/.hermes
HERMES_LOG_LEVEL: info
TZ: Europe/London
ports:
- "127.0.0.1:9119:9119" # dashboard, bound to localhost only
- "8765:8765" # gateway HTTP for inbound webhooks
mem_limit: 2g
cpus: 2.0
healthcheck:
test: ["CMD", "hermes", "doctor", "--quiet"]
interval: 60s
timeout: 30s
retries: 3
start_period: 90s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"
volumes:
hermes-data:A few choices worth explaining.
The image tag :latest is convenient for development. For production, pin to a specific version (:v0.12.0) so an upstream change doesn't surprise you between restarts. Bump it manually when you've tested the new version.
The dashboard port (9119) is bound to 127.0.0.1 so it's not exposed to the public internet. If you want remote access, do it through SSH tunnel or a reverse proxy with auth, not by exposing the port directly. The Nginx + HTTPS guide covers the proxy pattern.
The gateway HTTP port (8765) is exposed publicly because some channels (Slack, custom webhooks) need inbound HTTP from the internet. If you only use polling-based platforms (Telegram, Discord), drop this port mapping; you don't need it.
The ./env mount overlays a single read-only file at the path Hermes expects its .env to be. Why mount a file rather than baking the env into the Compose file directly? Because .env contains your API keys and you don't want those committed to the same git repo as your Compose file. Keep ./env in .gitignore.
The healthcheck runs hermes doctor --quiet every 60 seconds. The flag suppresses normal output, so the check succeeds silently if all checks pass and exits non-zero if anything is broken. The 90-second start_period gives Hermes time to load skills and connect to providers on first start without the healthcheck flapping.
The log rotation cap (10 MB per file, 5 files) keeps Docker's JSON log driver from filling your disk. For most installs this gives you about a week of logs at warning level or above.
Bring it up
cd /opt/hermes
echo "TELEGRAM_BOT_TOKEN=your-token-here" > env
echo "OPENROUTER_API_KEY=your-key-here" >> env
chmod 600 env
docker compose up -d
docker compose logs -f hermesThe logs should show Hermes loading providers, connecting to your messaging platforms and the healthcheck flipping to healthy after about 90 seconds. If the container restarts in a loop, the logs tell you why; the most common cause on first start is a missing or malformed env file.
To shell into the container:
docker compose exec hermes bashFrom inside, hermes is on the PATH and behaves exactly as it would on a native install. Useful when you want to tweak config or run an ad-hoc command without bouncing the gateway.
Persistent state in detail
The named volume hermes-data mounts at /root/.hermes inside the container. That's where everything lives: the SQLite session database, the skills directory, the memory files. Destroying the container with docker compose down leaves the volume intact; only docker compose down -v wipes it.
To inspect what's in the volume:
docker run --rm -v hermes_hermes-data:/data alpine ls -la /data(Note the volume name is prefixed with the project name, which is the directory name by default. Adjust if your Compose project is named differently.)
To back up the volume to a tarball, see the dedicated backups guide. The short version is "tar -czf the volume contents from a sidecar container".
Upgrades and rollbacks
The clean upgrade flow:
cd /opt/hermes
docker compose pull
docker compose up -d
docker compose logs -f hermespull fetches the new image. up -d recreates the container against the new image, preserving the volume. The named volume is what makes this safe; the container is disposable, the volume is persistent.
If the new version misbehaves, roll back by changing the image tag to a known-good version and running up -d again. Because state is in the volume rather than baked into the image, downgrades work as cleanly as upgrades.
For automatic upgrades during a maintenance window, add a Watchtower service to the Compose file:
watchtower:
image: containrrr/watchtower
container_name: watchtower
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
WATCHTOWER_CLEANUP: "true"
WATCHTOWER_SCHEDULE: "0 0 4 * * *" # 04:00 daily
WATCHTOWER_INCLUDE_RESTARTING: "true"
WATCHTOWER_NOTIFICATION_URL: "your-webhook-here"Watchtower polls Docker Hub at 04:00, pulls if the image has changed and gracefully restarts the container with the new image. The notification URL accepts Discord, Slack and many others; it pings you when an upgrade happens, so you're not surprised if something breaks at 4 AM.
Enabling automatic upgrades depends on your tolerance for unattended changes. For a personal agent, fine. For a production agent with users, the safer pattern is manual upgrades after testing in a staging environment.
Resource sizing
The Compose example caps memory at 2 GB and CPU at 2 cores. These are reasonable starting points; tune to your load.
If you're doing browser automation (the browser_ tool family inside Hermes), each Playwright session can spike to 500 MB to 1 GB of memory on its own. If your agent runs concurrent browser sessions, lift the cap to 4 GB or risk the kernel killing the container during a heavy task.
If you're doing only chat-based work with no browser, no heavy file processing, the 2 GB cap is conservative; you could probably run on 1 GB. The trade-off is that going lower starts to bite when your skill set grows. If you're sized too tight, you'll get OOM-killed mid-conversation and the user-visible symptom is "the bot stopped responding partway through a message".
CPU caps matter less than memory in practice. Most Hermes work is IO-bound on the LLM call, so CPU usage is bursty during local processing (parsing tool outputs, running code execution skills) and idle the rest of the time. Two cores is plenty for one user; bump to four if you have many concurrent users on the same instance.
Networking notes
If you're running Hermes alongside other services on the same box (a PaaS, a workflow tool, an analytics stack), put them on a shared Docker network so they can talk to each other without going through the host:
networks:
agent-stack:
external: trueThen add networks: [agent-stack] to the hermes service. Other services on the same external network can reach Hermes by container name (http://hermes:9119) without exposing the port to the host at all.
If you're using a reverse proxy (Nginx, Caddy, Traefik) in another Compose stack, the cleanest pattern is to put the proxy and Hermes on a shared external network and have the proxy talk to Hermes by container name. The proxy publishes 80/443 to the host; Hermes publishes nothing.
Migration from native install to Docker
If you've been running Hermes natively and want to move to Compose without losing state, the trick is to copy your existing ~/.hermes contents into the Compose volume.
# Stop the native service first
sudo systemctl stop hermes
# Bring up the Compose stack briefly to create the volume
cd /opt/hermes
docker compose up -d
docker compose stop hermes
# Copy state in
docker run --rm \
-v hermes_hermes-data:/dst \
-v /home/youruser/.hermes:/src \
alpine sh -c "cp -av /src/. /dst/"
# Start Hermes pointing at the migrated state
docker compose start hermes
docker compose logs -f hermesVerify the agent remembers your context (a project name, a skill, anything that was in your native memory). If it does, the migration worked; you can disable the native systemd service and remove the native install when you're ready.
The 1-click route
If you'd rather skip writing the Compose file yourself, the LumaDock Hermes Agent VPS template ships with the agent already installed natively on Ubuntu 24.04 plus Docker CE pre-installed, so you can switch to a Compose deployment any time. The native install gets you answering messages faster than the Compose file would; you'd reach for Compose later if you outgrow the basics or want to bundle Hermes with other services on the same box.
