How to run Hermes Agent in Docker

Short answer

Yes, Docker is officially supported. The official docs list the Docker container on x86_64 and aarch64 as Tier 1, and publish the image nousresearch/hermes-agent.

Docker suits servers and anyone who wants Hermes isolated from the rest of the machine. The image has no desktop app. If you want the app on your own computer, use the Windows, Mac or Linux install guides instead.

One thing to know: Docker installs do not support hermes update. You update by pulling a new image.

What you need

Docker installed on the host. The official docs give these resource figures:

• Memory: 1 GB minimum, 2 to 4 GB recommended.
• CPU: 1 core minimum, 2 cores recommended.
• Disk (data volume): 500 MB minimum, 2 GB or more recommended.

The docs say 1 GB is enough if you do not need browser tools. With browser tools active, allocate at least 2 GB.

Image tags: latest or stable for the stable release, main for development builds, or X.Y.Z to pin a version.

First run: the setup wizard

Create a data folder on the host, then run the wizard. It saves your settings into that folder.

sh

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

The wizard is the same one native installs use. It asks for your model provider and keys. The official docs say Hermes needs a model with at least 64,000 tokens of context.

Chat or run the gateway

For an interactive chat in the terminal:

sh

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

sh (persistent gateway)

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

The second command runs the messaging gateway in the background and restarts it unless you stop it. Port 8642 is the OpenAI-compatible API server and health endpoint. The docs say it is optional if you only use chat apps, so leave out -p 8642:8642 if you do not need it.

The docs also include a Docker Compose example on the same page.

Where your settings live and how to update

Everything lives in the mounted folder: ~/.hermes on the host, /opt/data in the container. That includes .env, config.yaml, SOUL.md, sessions/, memories/, skills/ and logs/. Back up this folder and you have backed up the agent.

To update, pull the new image and recreate the container:

sh

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

With Compose, run docker compose pull then docker compose up -d. See How to update Hermes Agent safely before big upgrades.

Common problems

• Two gateways on one data folder: never run two gateway containers on the same data directory.
• Browser tools crash: add --shm-size=1g to the run command.
• Permission errors on the data folder: the container runs as UID 10000, which may not match the folder owner. Set PUID and PGID (or HERMES_UID and HERMES_GID) to match.
• Database errors with Docker Desktop on Mac or Windows: bind mounts there can corrupt SQLite databases. Use a named volume, or set database.journal_mode: delete.
• Pasted commands fail on a VPS: browser-based consoles mangle characters like : and @. Connect over SSH instead.
• Opening ports: the docs warn that opening any port on an internet-facing machine is a security risk. The dashboard requires an auth provider on any non-local address.

Not the same as the Docker terminal backend

Running Hermes in Docker is different from the Docker terminal backend. With the backend, Hermes runs on your machine and sends its shell commands into a sandbox container (hermes config set terminal.backend docker). Compare the options in Hermes Agent terminal backends: local, Docker, SSH, cloud.

Next: connect a chat app with Hermes Agent messaging gateway explained, or keep it running around the clock with How to run Hermes Agent 24/7 on a VPS or home server.

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher