Hermes Agent Docker Setup: Production Guide for 2026

Hermes Agent Docker setup combines persistent storage, automatic recovery and enough resources to handle your tasks.

The official Docker image separates application files from writable agent data. A persistent data volume preserves config, sessions, memory and logs through container restarts and image updates. Supervised processes help the gateway and optional dashboard service recover when a process fails.

This guide walks you through the setup with Docker Compose. You’ll configure the published image, create a bind mount on your host machine and run services as a non-root Hermes user. You’ll also learn to manage the supervised gateway, monitor resources and handle updates on a Linux host or cloud VPS.

What are the prerequisites for Hermes Agent Docker?

Before running Hermes Agent in a Docker container, prepare the following:

Host machine: Use Ubuntu or Debian with SSH access for a remote server. Docker Desktop supports local testing on Windows or macOS.
System resources: Minimum 1 GB RAM and one CPU core. Recommended: 2–4 GB RAM and two cores. Browser automation needs at least 2 GB RAM.
Docker tools: Install Docker Engine and Docker Compose. Your host user needs permission to run Docker commands.
Credentials: Prepare authentication details for a supported model provider. Add messaging credentials if connecting the gateway to Telegram, Discord or Slack.
Persistent storage: Create a host folder and bind mount it to /opt/data. This data volume preserves config, memory and sessions across a container restart.
Dashboard access: Configure authentication when binding beyond localhost. For public access, use HTTPS through a reverse proxy.

Verify your installation:

docker --version 
docker compose version

On an Ubuntu or Debian server, enable Docker at boot:

sudo systemctl enable --now docker

The official Docker image ships with Python, Node.js and core dependencies, so a standard setup requires no separate host installation of these components.

Also read: Hermes Agent + n8n: Build Automated Workflows That Actually Think

Step-by-step Hermes agent docker setup (Production-ready guide)

This Hermes Agent Docker setup uses persistent storage, automatic recovery and private dashboard access. The official Docker image ships with dependencies and runs supervised services as a non-root Hermes user. Its /opt/hermes install tree remains root-owned and read-only to that user.

Run the server commands over SSH as the same non-root host user with Docker access. Docker Engine, Docker Compose and OpenSSL should already be installed.

Step 1: Prepare storage and credentials

Create a project folder and persistent data directory:

mkdir -p "$HOME/hermes" "$HOME/.hermes" 
cd "$HOME/hermes"

Generate dashboard credentials and save your host user IDs:

umask 077 
cat > .env <<EOF 
HERMES_UID=$(id -u) 
HERMES_GID=$(id -g) 
HERMES_DATA_DIR=$HOME/.hermes 
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin 
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=$(openssl rand -hex 24) 
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -hex 32) 
EOF 
chmod 600 .env

Keep this file private. Saving these values ensures Docker Compose reuses the same credentials and user IDs during upgrades.

Step 2: Run the setup wizard

Use this Docker run command to configure Hermes Agent:

docker run -it --rm \ 
 -e HERMES_UID="$(id -u)" \ 
 -e HERMES_GID="$(id -g)" \ 
 -v "$HOME/.hermes:/opt/data" \ 
 nousresearch/hermes-agent:latest setup

Choose your model provider and complete authentication. Configure a messaging channel if you plan to use the gateway.

Hermes saves application credentials under ~/.hermes/.env. This is separate from the Compose settings in ~/hermes/.env.

Step 3: Create the Compose file

Save the following as ~/hermes/docker-compose.yml:

services: 
 hermes: 
   image: nousresearch/hermes-agent:latest 
   container_name: hermes 
   command: gateway run 
   restart: unless-stopped 
 
   env_file: 
     - .env 
 
   environment: 
     HERMES_DASHBOARD: "1" 
 
   volumes: 
     - "${HERMES_DATA_DIR:?Set HERMES_DATA_DIR}:/opt/data" 
 
   ports: 
     - "127.0.0.1:9119:9119" 
 
   shm_size: "1g" 
 
   deploy: 
     resources: 
       limits: 
         memory: 4G 
         cpus: "2.0"

The bind mount connects an absolute path on the host machine to /opt/data. This data volume preserves config, sessions, memory and logs across container recreation.

The dashboard service runs alongside the supervised gateway. Shared memory supports browser automation. Adjust resource limits to your host capacity.

Keep the default image entrypoint and omit init: true so the s6 supervision tree remains active. Never share this writable data folder between two gateway containers.

Step 4: Start and verify Hermes

Run these commands from ~/hermes:

docker compose config --quiet 
docker compose up -d 
docker compose ps 
docker exec hermes hermes gateway status

Check recent logs:

docker logs --tail 100 hermes

Send a test message through your configured channel to confirm the agent responds.

Step 5: Access the dashboard securely

On your local computer, open an SSH tunnel:

ssh -N -L 9119:127.0.0.1:9119 your-user@SERVER-IP

Keep the tunnel running and open http://127.0.0.1:9119. Sign in using the credentials saved in the server’s ~/hermes/.env.

For public dashboard access, configure supported OAuth or OIDC authentication with HTTPS through a reverse proxy. Follow the dashboard guidance for public URLs and trusted proxies.

Step 6: Manage recovery and updates

s6 restarts failed supervised processes. Docker’s unless-stopped policy handles container exits and daemon restarts, while manually stopped containers stay stopped.

Task	Command
Restart the Hermes gateway	docker exec hermes hermes gateway restart
Perform a container restart	docker restart hermes
Check resource usage	docker stats –no-stream hermes
Stop Hermes for a backup	docker compose stop

Back up ~/.hermes and ~/hermes/.env while Hermes is stopped. Then update the published image:

docker compose pull 
docker compose up -d

Optional: Add another profile

Create and configure a separate agent profile before starting its gateway:

docker exec hermes hermes profile create coder 
docker exec -it hermes hermes -p coder setup 
docker exec hermes hermes -p coder gateway start

Per-profile gateways are registered dynamically as supervised services. Each profile maintains separate configuration, memory and sessions within the same Docker container.

Production maintenance checklist

Keep your Hermes Agent Docker deployment stable with these practices:

Back up the ~/.hermes data volume regularly.
Use restart: unless-stopped for container recovery.
Keep the supervised gateway enabled.
Monitor CPU and RAM with docker stats.
Use authentication for dashboard access.
Put public services behind HTTPS and a secure reverse proxy.
Avoid running Hermes commands as root unless required.
Never share one writable data volume between multiple gateway containers.
Pull updated Docker images and recreate containers when upgrading.
Use SSH instead of an unreliable browser console for server administration.

This approach keeps the Hermes Agent, Docker image and persistent agent data clearly separated. It also makes upgrades, container recovery and ongoing management easier.

Common Hermes Agent Docker problems and how to fix them

A Hermes Agent Docker setup can start successfully and still encounter storage, configuration or resource problems. Here’s what to check when workflows stop working.

1. Host interruptions

Docker Desktop supports local testing on Windows or macOS. Problems arise when the host machine sleeps, shuts down or loses network access, interrupting agent workflows.

For unattended tasks, use a local server or cloud VPS that stays powered on with reliable connectivity. A restart policy helps recover the Docker container when Docker restarts, but manually stopped containers remain stopped with unless-stopped.

2. Configuration errors

The official Docker image ships with core dependencies. Its /opt/hermes install tree is root-owned and read-only to the non-root Hermes user. Attempts to modify source code or run uv sync there during normal operation can fail.

Build additional dependencies into a custom image. Check permissions on /opt/data and preserve the default image entrypoint so supervised processes initialize correctly. If the dashboard service fails to start, confirm that supported authentication is configured when it binds beyond localhost.

3. Missing persistent data

A normal container restart preserves the same container’s writable files. Data loss becomes a risk when that container is removed or recreated without reusable persistent storage.

Map a bind mount or named data volume to /opt/data in your Docker Compose file. This preserves config, sessions, memory and logs across container replacement. Never point two gateway containers at the same writable folder.

4. Browser and scheduling failures

Browser automation can fail when RAM or shared memory is insufficient. For browser workloads, allocate at least 2 GB RAM and configure shared memory using:

shm_size: “1g” in the Compose file
–shm-size=1g in a Docker run command

These settings address memory requirements; website or network errors still need separate investigation.

Scheduled jobs also depend on the gateway. If a job does not run, check the supervised gateway, paused schedules, provider credentials and execution errors. A completed job can also have a separate delivery failure.

5. Resource bottlenecks

Concurrent tasks can exhaust available CPU or RAM. Check usage with docker stats hermes, then adjust concurrency and resource allocation for the workload. Resource limits control consumption but do not add capacity to the host machine.

Hermes supports multiple profiles within one container. Per-profile gateways are registered dynamically as supervised services. Use separate containers when workloads need independent resource limits, image versions or network boundaries, with a separate data folder for each.

Also read: How to Run Hermes Agent 24/7 on a VPS (The Complete 2026 Guide)

Final thoughts

Getting Hermes Agent running is easy. Keeping it stable is the real challenge. Most setups fail because they treat it like a simple app, when it actually depends on continuous execution, persistent memory, and a reliable runtime.

A production-ready setup comes down to three things: the right infrastructure, proper container configuration, and strong persistence. Skip any one of these, and issues will show up over time.

Focus on stability over shortcuts. Use isolated environments, map your data correctly, and monitor performance as workloads grow.

If you want to simplify the process, we at Bluehost provide a more streamlined path. With our VPS, you can deploy faster using a one-click Hermes setup built into the process, while still keeping full control over your environment.

Ready to run Hermes Agent without the setup headaches? Get started with Bluehost Hermes VPS and launch a stable, production-ready environment today.

FAQs

How do I secure my Hermes Agent Docker container in production?

For a production setup, restrict exposed ports and use an SSH tunnel or VPN for private dashboard access. For a public dashboard service, configure supported OAuth or OIDC authentication and HTTPS through a reverse proxy. Protect credential files with restrictive permissions and limit access to the Docker daemon.

How do I update the Docker image without losing data?

Stop Hermes and back up the data volume, compose file and environment settings. Keep the bind mount connected to the same absolute path on your host machine, with /opt/data as the container mount point. From the project folder, run:
docker compose pull docker compose up -d
Verify logs and agent responses after updating to the new version.

How do I access the Hermes Agent CLI after installation?

Use docker exec to run a command inside your container. For a container named hermes, check gateway status with:
docker exec hermes hermes gateway status
For an interactive Bash session as the Hermes user, run:
docker exec -it --user hermes hermes bash
These commands provide CLI access without opening another network port.

Does Hermes Agent Docker Compose work on Windows?

Yes. Docker Desktop runs Linux containers through WSL2 on supported Windows systems. Keep project files in the WSL Linux filesystem for better bind mount performance. Paths, permissions and resource settings still need attention. For continuous production use, choose a Linux environment or configure the Windows host to remain available.

Can I deploy Hermes Agent on Tencent Cloud Lighthouse?

A compatible Linux virtual server on Tencent Cloud Lighthouse should support this approach. Tencent documents Docker deployment on the platform. Check that the server architecture matches the published image and allow sufficient CPU, RAM and storage for your automation tasks. Configure outbound model-provider access and monitor actual workloads to confirm performance.

Do I need to install dependencies or modify the source code?

The image ships with Python, Node.js and bundled dependencies. Its build uses uv sync to prepare Python packages. The application install tree at /opt/hermes is root owned and read only to the runtime Hermes user. For persistent changes to bundled dependencies or source code, build a derived Docker image.

What does the non root Hermes user do?

It runs the main program and supervised processes after initialization. The Hermes CLI wrapper detects root callers and transparently re-executes standard Hermes commands under that account; non root callers proceed directly. Match the runtime UID/GID to the host user when needed for file ownership. Arbitrary docker exec commands do not automatically drop root privileges.

Why should I preserve the default image entrypoint?

The image entrypoint normally launches s6-overlay as PID 1, prepares storage during boot and starts the supervision tree. If another init system owns PID 1, the dispatcher uses a fallback path without s6-supervised services. Keep the default entrypoint and avoid adding –init to your Docker run command or init: true to the Compose file.

Does a Hermes restart require a container restart?

Usually, you can restart only the supervised gateway:
docker exec hermes hermes gateway restart
In normal gateway mode, s6 restarts a supervised service when it fails while a sleep infinity heartbeat keeps the container alive. With gateway supervision disabled, the gateway acts as the container’s main process: the container exits when the main program exits and returns its exit code. Inspect docker logs hermes for error details.

Can one container run multiple Hermes profiles?

Yes. Per profile gateways are registered dynamically within the supervision tree. Each profile maintains separate config, credentials, memory and sessions. At boot, gateway_state.json helps restore gateways previously recorded as running; explicitly stopped gateways stay stopped. Use separate containers when workloads need independent resource limits, image versions or network isolation. Give each container a separate writable data folder.

Hermes Agent Docker: Production Setup Guide That Works