Hermes Agent ships an official docker-compose.yml, and it is the cleanest way to run the agent if you already live in Docker: isolated dependencies, one-command updates, and a rollback story that is just git checkout. This guide walks through the whole setup on a fresh VPS, from installing Docker to a supervised gateway and dashboard, using only what the official compose file actually does.

If you have not decided how to run Hermes yet, start with the main Hermes Agent tutorial — the one-line installer is simpler for most people. Docker earns its keep when the VPS runs other workloads you want to keep separate, or when you want reproducible deployments across machines.

Docker or the one-line installer?

	One-line installer	Docker Compose
Setup effort	Lowest — one command	Low — Docker plus a git clone
Isolation	Runs on the host	Contained, own dependency tree
Updates	`hermes update`	`git pull` + rebuild
RAM overhead	None	Roughly 100–200 MB extra (community measurements)
Best for	A dedicated agent VPS	A VPS shared with other services

Both approaches keep the agent's memory, config, and sessions in ~/.hermes on the host, so switching between them later is not a big deal.

What does the Docker setup need?

A VPS with 2 GB of RAM covers the gateway, the dashboard, and the Docker overhead for cloud-model setups. Add more if you run many channels or heavy tools — the Hermes Agent VPS sizing guide breaks it down plan by plan. You also need Git and Docker itself.

Everything below assumes Debian 12 or Ubuntu 24.04 with a non-root user that belongs to the docker group.

Step 1: Install Docker

The official convenience script installs the engine and the compose plugin:

curl -fsSL https://get.docker.com | sh

Add your user to the docker group so you can run compose without sudo:

sudo usermod -aG docker $USER

Log out and back in for the group change to apply.

Step 2: Get Hermes Agent

The image is built from the repository — there is no prebuilt public image, which also means you always know exactly what code you are running:

git clone https://github.com/NousResearch/hermes-agent.git

cd hermes-agent

Step 3: Understand the compose file before you run it

The official docker-compose.yml defines two services, both sharing your host's ~/.hermes directory:

gateway — the agent itself and its messaging connections. Runs gateway run under s6-overlay supervision, with restart: unless-stopped.
dashboard — the web dashboard on port 9119, deliberately bound to 127.0.0.1 only.

Three details matter:

~/.hermes is mounted at /opt/data. Your agent's memory, sessions, and config live on the host, not in the container. Containers are disposable; your agent's brain is not.
HERMES_UID / HERMES_GID remap the container user to your host user, so files created inside the container stay readable outside it. Always pass them (step 4).
The entrypoint starts with /init (s6-overlay's PID 1). If you customize the compose file, do not override the entrypoint — the init stage handles permissions and service supervision, and the gateway will not work correctly without it.

Step 4: Build and start

HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d --build

The first build takes a few minutes. Check that both services are up:

docker compose ps

Step 5: Configure through the dashboard

The dashboard stores your provider API keys and channel configuration. It only listens on localhost — that is a security feature, not an oversight. Reach it through an SSH tunnel from your machine:

ssh -L 9119:localhost:9119 you@your.server.ip

Then open http://localhost:9119 in your browser, add your model provider key (OpenRouter, Nous Portal, or your own), and connect your first messaging channel. Do not be tempted to expose the dashboard with --host 0.0.0.0 — the official compose file warns against exactly that, because the dashboard holds your keys and has no built-in authentication.

How do I update Hermes Agent under Docker?

Updates are a rebuild, and your data is untouched because it lives on the host:

git pull

HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d --build

Hermes releases move fast (weekly at the current pace), so it is worth doing this regularly — release notes are on the GitHub releases page.

How do I back up a Dockerized Hermes Agent?

Everything that matters is in one directory. Archive it:

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

Copy that archive off the server on a schedule and your agent survives anything, including you deleting the whole VPS by accident. Restoring is extracting the archive to ~/.hermes on any machine and running the same compose file.

Security checklist

Keep the dashboard on localhost and use SSH tunnels. Exposed agent dashboards are the most common self-hosting mistake we see.
Leave the OpenAI-compatible API server off unless you need it. It is disabled by default; enabling it requires both API_SERVER_HOST and a mandatory API_SERVER_KEY in the compose environment.
Give the agent a dedicated provider API key with a spending limit.
Standard host hygiene still applies: SSH keys only, firewall allowing only SSH, regular OS updates. The main tutorial's hardening section covers this step by step.

What does it cost?

A 2 GB VPS runs the whole stack comfortably for cloud-model setups — that is the Starter tier at Virtua.Cloud's Hermes Agent VPS, with hourly billing if you just want to experiment for an afternoon. Model usage is whatever your API provider charges; the agent itself is free and open source.

If you are weighing Hermes against OpenClaw for a Docker deployment, both containerize fine — our Hermes Agent vs OpenClaw comparison covers how they differ in footprint and day-to-day operation.