Hermes Agent ships an official Docker image. Three commands to setup, one to run 24/7. But there are two Docker modes that most guides conflate, and one data persistence mistake that wipes your skills. Here's the guide that covers both.
A developer on MindStudio wrote: "You will forget which container holds which agent within two weeks."
He was running four Hermes instances. Different models. Different Telegram bots. Different skill libraries. All in separate Docker containers. All with nearly identical names. And no labeling system.
That's the Docker experience in one sentence. It works. You just have to manage it.
Hermes Agent (23,000+ GitHub stars, growing fast) ships an official Docker image from Nous Research. The install is genuinely simple: three commands to setup, one to run. But the Docker deployment has two distinct modes that most guides conflate, and one data persistence mistake that silently wipes your accumulated skills on the next docker pull.
Here's the complete guide.
The setup (three commands, five minutes)
Step 1: Create the data directory.
mkdir -p ~/.hermes
This is where your config, API keys, sessions, skills, and memories live on the host machine.
Step 2: Run the setup wizard.
docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup
This drops you into the interactive wizard. It asks for your LLM provider (Anthropic, OpenAI, DeepSeek, OpenRouter, etc.), your API key, and which messaging channels to connect (Telegram, Discord, Slack, WhatsApp).
Step 3: Run the gateway in the background.
docker run -d --name hermes --restart unless-stopped -v ~/.hermes:/opt/data -p 8642:8642 nousresearch/hermes-agent gateway run
Your agent is now running 24/7. Port 8642 exposes the gateway's OpenAI-compatible API server and health endpoint. It's optional if you only use messaging platforms but required for the dashboard and external tools.
The critical detail: The -v ~/.hermes:/opt/data volume mount is what keeps your data safe. Without it, your config, skills, and memories live inside the container and vanish on the next docker pull. Always mount /opt/data to a host directory.
The two Docker modes (this is where most guides get confusing)
Here's what nobody tells you about Hermes and Docker.
Mode 1: Hermes running inside Docker. This is the standard deployment. The entire agent (gateway, skills, memory, messaging) runs inside the container. You interact through Telegram, Discord, or other channels. The container is your server. This is what the setup above configures.
Mode 2: Docker as a terminal backend. Hermes runs on your host machine (not in Docker). But every command the agent executes runs inside a Docker sandbox container. The sandbox survives across tool calls, new sessions, and subagents. This is for developers who want the agent on their machine but want command execution isolated.
The confusion: Most guides mix these two modes. "Install Hermes with Docker" could mean either. If you want a 24/7 agent on a VPS, you want Mode 1. If you want safe local development with isolated execution, you want Mode 2.
For the detailed comparison of Hermes features in v0.13, our security analysis covers how both Docker modes handle credential isolation.
The production checklist (what breaks after day one)
Problem 1: Volume mount missing. You ran docker run without -v ~/.hermes:/opt/data. The agent works. Skills accumulate. Memory grows. Then you update with docker pull and restart. Everything is gone. The container was the only copy.
The fix: Always use the volume mount. Always verify with docker inspect hermes | grep Mounts.
Problem 2: Node version mismatch inside the container. Docker users hit issues when the container's Node.js version conflicts with skills that expect a specific version. The official image pins Node, but community images vary.
The fix: Use only the official nousresearch/hermes-agent image. Community images may lag behind or use incompatible base images.
Problem 3: .venv permission issues. On some host configurations, the Python virtual environment inside the container has permission conflicts with the mounted volume. Skills fail to install with cryptic permission errors.
The fix: Ensure the container user has write permissions to the mounted directory. chown -R 1000:1000 ~/.hermes on the host before starting the container.
Problem 4: Port 8642 conflicts. If you're running multiple Hermes instances (different agents, different bots), each needs a different host port mapping. docker run -p 8643:8642 for the second instance, etc.
If managing Docker volumes, port mappings, Node version conflicts, permission issues, and multi-container orchestration for an AI agent sounds like more DevOps than agent building, BetterClaw eliminates the Docker layer entirely. No containers. No volume mounts. No port mapping. Deploy in 60 seconds from a browser. Free tier with 1 agent and BYOK. $19/month per agent for Pro.
Updating (the part that catches people)
The update process:
Pull the new image: docker pull nousresearch/hermes-agent:latest
Stop and remove the old container: docker stop hermes && docker rm hermes
Start a new container with the same volume mount: docker run -d --name hermes --restart unless-stopped -v ~/.hermes:/opt/data -p 8642:8642 nousresearch/hermes-agent gateway run
Your data survives because it lives in ~/.hermes on the host. The container is disposable. The data directory is permanent. This is the correct Docker pattern for stateful applications.
The mistake to avoid: Using docker compose up -d with a build step instead of pull. If your compose file builds from source instead of pulling the official image, updates require rebuilding, which takes longer and can introduce build failures.
Docker Compose (for the organized)
If you prefer declarative configuration, here's the pattern:
Create a docker-compose.yml with the service name hermes, using the official image nousresearch/hermes-agent, restart policy unless-stopped, port 8642:8642, volume ~/.hermes:/opt/data, and command gateway run.
Then: docker compose up -d
For multiple agents: Duplicate the service block with different names, ports, and data directories. hermes-work on port 8642 with ~/.hermes-work:/opt/data. hermes-personal on port 8643 with ~/.hermes-personal:/opt/data. Each agent has isolated skills, memory, and messaging channels.
For the comparison between managed and self-hosted agent deployment, our comparison covers what you manage yourself versus what a platform handles.
The honest assessment (Docker for Hermes vs managed alternatives)
Here's the take.
Docker is the right choice for Hermes if you want full control, you're comfortable with container management, and you're running on a VPS you already have. The official image is well-maintained. The volume mount pattern is clean. Updates are pull-stop-remove-restart.
Docker is the wrong choice if you don't want to manage containers, you're not comfortable with port mapping and volume permissions, or you need the agent running without thinking about infrastructure.
AlphaSignal's recommendation for Hermes v0.13 was "Tenacity, not Production." The Docker setup is stable. The agent inside it is still maturing. Known issues: macOS Python 3.13 conflicts, .venv permissions, and /goal's judge model can complete goals prematurely.
If you want an always-on agent without Docker, volume mounts, port mapping, and container lifecycle management, give BetterClaw a try. Free tier with 1 agent and BYOK. $19/month per agent for Pro. 15+ messaging channels. Persistent memory. No Docker required. The agent runs. The infrastructure is ours.
Frequently Asked Questions
How do I install Hermes Agent with Docker?
Three commands: create a data directory (mkdir -p ~/.hermes), run the setup wizard (docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup), then start the gateway (docker run -d --restart unless-stopped -v ~/.hermes:/opt/data -p 8642:8642 nousresearch/hermes-agent gateway run). Total time: about 5 minutes. The setup wizard asks for your API provider and messaging channels.
What's the difference between Hermes Docker Mode 1 and Mode 2?
Mode 1 runs the entire Hermes agent inside a Docker container (standard VPS deployment). Mode 2 runs Hermes on your host but uses Docker as a sandboxed terminal backend for command execution. Mode 1 is for always-on agents. Mode 2 is for local development with isolated execution. Most VPS deployments use Mode 1.
How do I update Hermes Agent in Docker without losing data?
Pull the new image (docker pull nousresearch/hermes-agent:latest), stop and remove the old container (docker stop hermes && docker rm hermes), then start a new container with the same volume mount. Your data in ~/.hermes survives because it's on the host, not inside the container. The image is stateless by design.
How much does it cost to run Hermes Agent with Docker?
The Docker image and Hermes software are free (MIT license). You need a VPS ($5-10/month for Hetzner, DigitalOcean, or Contabo with 2+ CPU cores and 8GB RAM) plus your AI model API costs (varies by provider and usage). Total: $5-50/month depending on model choice and usage volume. BetterClaw offers managed deployment at $0 (free tier) or $19/month (Pro) without Docker.
Is Hermes Agent stable enough for production Docker deployment?
For testing and personal use: yes, the Docker setup is reliable. For production business use: proceed with caution. AlphaSignal assessed v0.13 as "Tenacity, not Production." Known issues include Python 3.13 conflicts, .venv permission bugs in Docker, and the /goal judge model making premature completion decisions. Use the official nousresearch/hermes-agent image and always mount /opt/data to a host directory.
