How to Deploy Hermes Agent with Docker and Docker Compose

What does Docker change about a Hermes deployment?

Docker packages the Hermes Agent application runtime, but it does not replace persistent state, channel credentials, model access, backups, or gateway verification.

The official image keeps the installed application tree separate from user state. That makes replacement and upgrade simpler, but it also means an empty or poorly mounted /opt/data produces an assistant that loses configuration, memory, skills, and session history when the container is recreated.

Use Docker when you want a repeatable runtime definition, controlled image updates, and explicit volume and port behavior. Do not use a container as a substitute for deciding who owns secrets, backups, monitoring, and recovery.

• Read the official Hermes Docker setup
• Compare managed and self-hosted Hermes Agent

Which Docker volumes must Hermes Agent keep?

Hermes Agent needs /opt/data persisted because it is the source of truth for credentials, configuration, sessions, memory, skills, cron jobs, hooks, logs, and per-profile home files.

A simple first setup can mount a host directory such as ~/.hermes at /opt/data. For macOS or Windows Docker Desktop, consider a named Docker volume or review the SQLite journal-mode guidance below before trusting a cross-VM bind mount with production state.

• .env and config.yaml: provider credentials and runtime configuration.
• sessions/ and state.db: conversation history and runtime state.
• memories/ and SOUL.md: durable context and agent identity.
• skills/, cron/, and hooks/: reusable procedures and scheduled automation.
• logs/ and home/: operational history and credentials used by tool subprocesses.

Why does state.db care about the Docker filesystem?

Hermes Agent stores sessions in SQLite under /opt/data, and SQLite WAL behavior depends on shared-memory support that not every container mount provides.

This is the main difference between a demo container and a durable deployment. Choose the data-location strategy before the first production setup, because moving or repairing a live database is more disruptive than selecting the right volume on day one.

• Native Linux filesystems and named Docker volumes are the safest default for the state database.
• Docker Desktop virtiofs on macOS and 9p/drvfs on Windows can make WAL shared memory unsafe for concurrent writers.
• Hermes detects unsafe fresh databases and can use rollback journal mode, but an existing WAL database requires a controlled conversion.
• Stop every Hermes process that uses the data directory before converting state.db, then set the documented journal-mode configuration.
• Do not run two Hermes gateway containers against the same /opt/data directory at the same time.

What belongs in a Hermes Agent Docker Compose file?

A Compose file should define the official image, gateway command, restart policy, /opt/data volume, required environment variables, and only the ports the deployment actually uses.

The official Compose example exposes the gateway API port and the dashboard port when the dashboard is enabled. Opening either directly to the internet changes the security boundary; use authentication, localhost, a VPN, an SSH tunnel, or another approved proxy pattern.

• Image: pin an explicit production image tag instead of casually floating across every latest update.
• Command: gateway run for an always-on Telegram, Discord, Slack, WhatsApp, or other channel deployment.
• Restart: unless-stopped so a host reboot can recover the assistant without manual reconstruction.
• Volume: map a dedicated host directory or named volume to /opt/data.
• Ports: expose 8642 only if external tools need the OpenAI-compatible API or health endpoint; dashboard access requires its own explicit configuration.
• Environment: enable the dashboard and API server deliberately, then protect them with authentication and network boundaries.

• Read the Docker Compose documentation
• Use the Hermes deployment checklist

How do you verify a Hermes Docker gateway?

Verify container status, inspect logs for startup and gateway events, check the intended dashboard or health path, and send one real message through the target channel.

A green container proves only the process layer. The launch criterion is a real reply in the exact channel and conversation the assistant will serve.

• Container state: the gateway container is running and has not entered a restart loop.
• Startup logs: the supervised gateway started without credential, provider, or channel errors.
• Persistent state: configuration, memory, and skills remain visible under the mounted data directory.
• Health/API: an explicitly exposed health or API endpoint responds only through the intended network path.
• End-to-end proof: a message in the intended Telegram, Discord, Slack, or WhatsApp scope receives a useful reply.

• Troubleshoot missing Hermes messages
• Restart or redeploy safely

How do you upgrade Hermes Agent in Docker?

Back up /opt/data, pull the chosen new image, recreate the container, let Hermes run non-interactive config migrations, and repeat the channel test before returning it to production.

The official image can run configuration-schema migrations against the mounted config when it starts. A backup is still required because the operator, not the container runtime, owns the only durable copy of memory, skills, sessions, and credentials.

• Stop or quiesce activity that could write to sessions and memory during the backup.
• Copy .env, config.yaml, state.db, memories, skills, cron jobs, hooks, and per-profile home files.
• Pull the explicit target image and recreate the container with the same volume and network definition.
• Inspect logs for migration or startup errors and keep the previous image available for rollback.
• Send another real channel message before restoring schedules or high-volume automation.

When should you choose Docker, a VPS, or managed hosting?

Choose Docker when you want a repeatable self-hosted runtime definition, a VPS when you need broader host control, and managed hosting when server operations are the obstacle rather than the capability.

• Docker: useful for controlled image upgrades, explicit volumes, and reproducing the same runtime on a supported host.
• VPS: useful when you also manage networking, monitoring, storage, firewalling, and other services around the assistant.
• Managed: useful when the team wants an always-on assistant without owning container recreation, backups, restarts, and host security.

• Choose a VPS for Hermes Agent
• See managed Hermes Agent hosting