Run Hermes Agent in Docker: Persistent Setup & Safety

Updated 7 November 2026 · Standard formula, shown below

This guide walks you through running the Hermes agent inside a Docker container with a persistent configuration and data volume, plus the essential safety checks to keep your setup stable and secure. You will end up with a container that survives restarts, keeps its state, and runs with least-privilege principles.

What You’ll Need

Docker installed (Docker Engine 20.10+ or Docker Desktop) and the docker CLI available in your terminal.
Basic familiarity with terminal commands and editing files with a text editor.
A directory where you want to store Hermes configuration and data (e.g., ~/hermes).
An API key or authentication token if your Hermes agent integrates with external services (like an LLM API). Keep it secret.

Step-by-Step

Create a project directory. Run mkdir -p ~/hermes/config ~/hermes/data to hold configuration and persistent data separately.
Pull the Hermes image. Use the official image name from the project’s registry (e.g., docker pull ghcr.io/your-org/hermes:latest). Replace with the actual image reference from the Hermes documentation.
Write a minimal configuration file. Create ~/hermes/config/hermes.yaml with the agent’s basic settings: model endpoint, temperature, system prompt, and any tool permissions. Start with a restrictive set—only enable tools you need.
Set up environment variables. Create a file ~/hermes/.env with your API keys (e.g., OPENAI_API_KEY=sk-...). Ensure the file permissions are read-only for your user: chmod 600 ~/hermes/.env.

Run the container with a named volume. Use a Docker volume for persistent data rather than a bind mount unless you need direct host access. Example:

docker run -d \
  --name hermes-agent \
  --restart unless-stopped \
  -v ~/hermes/config:/app/config:ro \
  -v hermes-data:/app/data \
  --env-file ~/hermes/.env \
  --read-only \
  --tmpfs /tmp \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  ghcr.io/your-org/hermes:latest

This mounts config read-only, uses a volume for data, restricts filesystem, drops all capabilities, and prevents privilege escalation.

Verify the container is running. Run docker ps and check that hermes-agent is up. Then check logs with docker logs hermes-agent to confirm no startup errors.
Test persistence. Stop the container (docker stop hermes-agent), start it again (docker start hermes-agent), and confirm that any state (like conversation history or internal database) is still present.
Set up a health check. Add a --health-cmd to the run command if the image supports it (e.g., --health-cmd="curl -f http://localhost:8080/health"). This lets Docker restart the container if it becomes unhealthy.
Update safely. When a new image version is available, pull it, stop the old container, remove it (docker rm hermes-agent), and run a new container with the same volume and config. Your data persists.

Common Mistakes

Using a bind mount for data without proper permissions. The container may run as a non-root user, and the host directory may not be writable. Use a named volume unless you have a specific reason.
Hardcoding secrets in the config file. Anyone with access to the repo or host can read them. Use environment variables or Docker secrets.
Running as root inside the container. This defeats many security benefits. Use a non-root user if the image supports it (often via --user 1000:1000).
Forgetting to set --restart. Without it, the container won’t start after a reboot or Docker daemon restart.
Exposing unnecessary ports. Only publish ports if the agent has an API that you need to access from the host. Use -p 127.0.0.1:8080:8080 to bind to localhost only.

Tips

Use Docker Compose for complex setups. Define the service, volumes, and environment in a docker-compose.yml file. It makes updates and replication easier.
Keep the config minimal. Only enable tools and permissions that are necessary. Review the config regularly.
Back up the volume. Use docker run --rm -v hermes-data:/data -v $(pwd):/backup alpine tar czf /backup/hermes-data.tar.gz /data to create a backup.
Monitor resource usage. Use docker stats hermes-agent to see CPU and memory. Set memory limits with --memory=512m if needed.
Pin the image version. Instead of latest, use a specific tag like v1.2.3 to avoid unexpected breaking changes.

Troubleshooting

Container exits immediately. Check logs with docker logs hermes-agent. Likely causes: missing config file, invalid API key, or the image expects a different entrypoint. Verify the config path and environment variables.
Permission errors on the data volume. If you used a bind mount, the container user may not have write access. Change the host directory permissions (chown -R 1000:1000 ~/hermes/data) or switch to a named volume.
Cannot connect to the agent from the host. Ensure you published the port correctly and that the agent is listening on 0.0.0.0 inside the container (not just localhost).
State is lost after restart. Check that you used the same volume name and that the container’s working directory matches the volume mount point. Inspect with docker inspect hermes-agent.
Health check fails. The health command may not be available inside the container (e.g., no curl). Use a lightweight binary like wget or a built-in health check if the image supports it.

Frequently Asked Questions

How do I update the Hermes agent without losing data?

Pull the new image, stop and remove the old container, then run a new container with the same volume and environment variables. Your data in the volume remains intact.

Can I run multiple Hermes agents on the same host?

Yes, but each needs a unique container name, separate volumes, and different ports if you expose them. Use separate config directories to avoid conflicts.

How do I pass a configuration file without rebuilding the image?

Mount the config directory as a read-only volume (-v ~/hermes/config:/app/config:ro). Changes to the file on the host take effect after restarting the container.

Is it safe to use `--read-only` with Hermes?

Most agents work fine with a read-only root filesystem as long as they have a writable data directory (mounted volume) and a --tmpfs for temporary files. Test your specific image to ensure it doesn’t write elsewhere.

What should I do if my API key is exposed?

Immediately revoke the key in the provider’s dashboard, generate a new one, update the .env file, and restart the container. Also check logs and shell history for accidental exposure.

Can I use Docker secrets instead of environment variables?

Yes, if you use Docker Swarm. In standalone Docker, you can use bind-mounted secret files with --read-only and set the file permissions to 400.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.