Hermes Agent in Docker: the compose file and 127.0.0.1:9119:9119
Hermes Agent's Docker Compose setup on a Linux server: host networking, the ~/.hermes volume, keys, the dashboard on 9119 via SSH tunnel, updates and logs.
Hermes Agent’s own Linux compose file runs two containers from one image, the gateway and the dashboard, both with network_mode: host and your ~/.hermes mounted at /opt/data, and starts the dashboard on the host’s 127.0.0.1:9119. It has no ports: section, so there is no 127.0.0.1:9119:9119 line in it. That line is in the Windows file, where host networking is not used: it publishes the container’s port 9119 on the host’s loopback address only, so nothing outside the machine can reach it. Either way, open the dashboard from a laptop with ssh -N -L 9119:127.0.0.1:9119 you@your-server and then http://localhost:9119. As of November 18, 2026 the latest release is v0.23.2, and the image tag is nousresearch/hermes-agent:v0.23.2, with the v.
What is in the repository’s two compose files
The Linux file at v0.23.2 defines a gateway service (container name hermes, command gateway run) and a dashboard service (container name hermes-dashboard, command dashboard --host 127.0.0.1 --no-open). Both mount ~/.hermes:/opt/data, restart unless-stopped, and set HERMES_UID and HERMES_GID, defaulting to 10000. Its comment says why the dashboard stays on loopback: “It stores API keys; exposing it on LAN without auth is unsafe.” It also builds the image from the checkout (build: ., tagged hermes-agent) rather than pulling Nous’s published one, so it is meant to be run from a clone of the repository.
The file has used host networking since it was added to the repository on April 21, 2026; the 127.0.0.1:9119:9119 mapping was never in it. It arrived on May 23 with docker-compose.windows.yml, whose header says it “Removes network_mode: host (not supported on Docker Desktop for Windows)” and “Uses explicit port mappings instead.” (Docker Desktop has offered host networking as an opt-in setting since 4.34; the Windows file does not use it.)
What 127.0.0.1:9119:9119 means
A port mapping reads host-address:host-port:container-port. With the address left off, as in 9119:9119, Docker publishes on every address the server has, the public one included, and Docker’s port publishing docs open with “Publishing container ports is insecure by default.” A firewall such as ufw does not stop it on its own: Docker’s firewall page says published traffic is diverted so that “Packets are routed before the firewall rules can be applied, effectively ignoring your firewall configuration.” Writing 127.0.0.1: in front publishes the port on the host’s loopback only. Programs on the server can reach it; the internet cannot. That is why it is reached by an SSH tunnel or over Tailscale, never by the server’s IP address.
In the Windows file the mapping is not the whole story. Inside its container the dashboard binds 0.0.0.0, so the mapping can reach it, and it still passes --insecure. Nous’s dashboard docs now say the flag is “accepted for backward compatibility but ignored, with a warning,” and that a bind to anything other than 127.0.0.1, ::1 or localhost needs a sign-in method; without one, a dashboard started by Docker, where nobody can answer its prompt, fails closed at startup. Read together, the Windows file’s dashboard starts only once a sign-in method is configured, such as the HERMES_DASHBOARD_BASIC_AUTH_USERNAME and HERMES_DASHBOARD_BASIC_AUTH_PASSWORD variables from the Docker page. If its log begins “Refusing to bind dashboard to 0.0.0.0”, that is the cause. The same applies to the single-container example on Nous’s Docker page, which sets HERMES_DASHBOARD=1 and publishes 9119:9119 on every address.
environment:
- HERMES_DASHBOARD_HOST=0.0.0.0
ports:
- "127.0.0.1:9119:9119"
command: ["dashboard", "--host", "0.0.0.0", "--port", "9119",
"--no-open", "--insecure"]CopiedWhy the Linux file uses host networking
With network_mode: host the container “shares the host’s networking namespace,” in Docker’s words, so --host 127.0.0.1 means the server’s own loopback. The dashboard counts as a loopback bind, needs no sign-in, and there is no Docker port rule involved at all; any ports: line would be ignored with “Published ports are discarded when using host network mode.” Nous’s Docker page gives a second reason: a dashboard in its own container is supported only “when that container shares the host PID and network namespace,” because it checks whether the gateway is alive, and it names the repository’s file as the example. The trade-off is that whatever Hermes binds to 0.0.0.0 inside lands on the server’s public address too, so the API server stays as the file ships it, off, unless you mean to expose it with a key.
Running it on a Linux server
To use the published image instead of building one, keep the repository’s Linux file and replace its build: and image: lines with a pinned tag. The result, with the file’s comments and commented-out options left out:
services:
gateway:
image: nousresearch/hermes-agent:v0.23.2
container_name: hermes
restart: unless-stopped
network_mode: host
volumes:
- ~/.hermes:/opt/data
environment:
- HERMES_UID=${HERMES_UID:-10000}
- HERMES_GID=${HERMES_GID:-10000}
command: ["gateway", "run"]
dashboard:
image: nousresearch/hermes-agent:v0.23.2
container_name: hermes-dashboard
restart: unless-stopped
network_mode: host
depends_on:
- gateway
volumes:
- ~/.hermes:/opt/data
environment:
- HERMES_UID=${HERMES_UID:-10000}
- HERMES_GID=${HERMES_GID:-10000}
command: ["dashboard", "--host", "127.0.0.1", "--no-open"]CopiedThen run Hermes’s setup once, which writes your provider keys and messaging tokens into ~/.hermes/.env, and start both services with your own user and group IDs, as the file’s usage line does:
mkdir -p ~/.hermes
docker run -it --rm -v ~/.hermes:/opt/data \
nousresearch/hermes-agent:v0.23.2 setup
HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -dCopiedPassing your IDs matters because the container otherwise runs Hermes as UID 10000, and files it creates in ~/.hermes would not be yours on the host. Everything Hermes keeps is in that one folder: .env with the keys, config.yaml, sessions, memories, skills, scheduled jobs, logs, and a home/ that tools like git and ssh use inside the container. The code in /opt/hermes is read-only and replaced with the image. Nous’s warning about the folder: “Do not make the whole data tree world-readable. It contains credentials.” A key can also be set in the compose file’s environment:, which overrides .env; that is Docker Compose’s own variable handling, covered in Compose’s .env and env_file.
Nous asks for at least 1 GB of memory, 2 to 4 GB recommended, and 2 GB once the browser tools are in use, which also want --shm-size=1g. Port 8642 belongs to the OpenAI-compatible API server and health endpoint, which Nous calls optional for chat-only use and this layout leaves off. What up -d does with an existing container is in what docker compose up -d does.
Opening the dashboard from a laptop
From the laptop, forward a local port to the server’s loopback and leave the command running:
ssh -N -L 9119:127.0.0.1:9119 you@your-serverCopiedThen open http://localhost:9119. This works the same for the Linux file and the Windows-style mapping, needs no sign-in on the dashboard, and opens nothing to the internet. If you reach the server over Tailscale SSH, the tunnel runs over your tailnet in the same way. Putting Tailscale Serve or any reverse proxy in front of the dashboard is a different case: the dashboard then needs a sign-in method and its dashboard.public_url set, as the guide to Hermes’s dashboard and web UI explains. For tunnels in general, including the VS Code and Tailscale Serve routes, see opening a localhost app on a remote server. To confirm nothing is listening on a public address afterwards, check the open ports from inside and outside.
Logs
Both services write to Docker’s log, and Hermes also keeps rotated log files on the volume, which survive the container being removed while docker logs does not:
docker compose logs -f gateway
docker logs --tail 50 hermes
docker exec hermes hermes logs --follow --level WARNING
tail -F ~/.hermes/logs/gateways/default/current
tail -F ~/.hermes/logs/container-boot.logCopiedThe first line uses the compose service name, the second the container name; default in the fourth is the profile. The gateway’s files rotate at 1 MB, ten kept.
Updating the container
Inside the image, hermes update does not apply: it “refuses image-owned code changes; replace the image to update the application.” With a pinned tag, change both image: lines to the new release and recreate the containers:
# edit the two image: lines to the new tag, then
docker compose pull
HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -dCopiedOn start the new image migrates config.yaml if it needs to, writing timestamped backups of it and .env first. If you build from the repository’s own file instead, check out the release tag and rebuild:
git fetch --tags
git checkout v0.23.2
HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d --buildCopiedOn Docker Hub, as of November 18, latest, stable and v0.23.2 point at the same image. latest moves at the next release; a version tag does not. Releases come often, and when an update does not go as expected, hermes update’s failure messages covers the source install, where the update command does the work.
A known gap with two containers
The dashboard’s “Restart Gateway” button fails in a split gateway and dashboard setup with “no such gateway ‘default’”, and the dashboard can show the gateway as stopped while it runs, as reported in #78803 (open as of November 2026); one commenter reproduced it with two network_mode: host containers. The working restart is from the server: docker compose restart gateway. An open pull request, #36235, proposes dropping the separate dashboard service from both compose files, so the layout above may change. For installing Hermes without Docker, see how to install Hermes Agent on a Linux server.