DEV Community

Cover image for Run Hermes Agent Inside Docker: A Safer Setup for Autonomous AI Agents 🐳
Vivek Shetye
Vivek Shetye

Posted on

Run Hermes Agent Inside Docker: A Safer Setup for Autonomous AI Agents 🐳

#ai #hermes #agents #docker

Giving an AI agent unrestricted access to your entire computer is probably not a great idea.

Especially when that agent can:

  • Run terminal commands
  • Install packages
  • Create and modify files
  • Access external services
  • Work autonomously through multi-step tasks

Those capabilities are exactly what make Hermes Agent powerful.

But they also raise an important question:

Where should all of those actions actually run?

Instead of running Hermes Agent directly on my host machine, I decided to run it inside a Docker container and explicitly control what the agent can access.

The goal isn’t to make Hermes magically “secure” by putting it inside Docker.

The goal is much simpler:

Give the agent access to what it needs, not your entire computer.

In this tutorial, I’ll walk through the complete setup.

We’ll configure:

  • Hermes Agent inside Docker
  • Persistent storage for memory, sessions, and configuration
  • A limited filesystem boundary
  • Hermes Gateway
  • Hermes Dashboard
  • Dashboard authentication
  • Hermes Desktop connected to the container
  • Some important security considerations when containerizing autonomous AI agents

🎥 Prefer watching instead?

I walk through the complete setup step-by-step in the video:

Watch the full Hermes Agent Docker tutorial on YouTube →

🤖 Why Run Hermes Agent Inside Docker?

Hermes isn’t just a chatbot.

It can interact with your environment and perform actions on your behalf.

For example, depending on the tools you enable, Hermes can work with files, execute terminal commands, install dependencies, use external services, and autonomously work through tasks.

That’s incredibly useful.

But if the agent runs directly on your main machine, you need to think carefully about what files, credentials, and system resources it can reach.

That’s where Docker becomes useful.

Instead of letting Hermes operate directly across my host environment, I can put it inside a container and explicitly decide what crosses that boundary.

The architecture we’ll build looks roughly like this:

┌──────────────────── HOST MACHINE ────────────────────┐
│                                                      │
│  Docker                                              │
│                                                      │
│  ~/.hermes-docker  ───────────────┐                  │
│                                   │                  │
│                    ┌──────────────▼──────────────┐   │
│                    │      Docker Container       │   │
│                    │                             │   │
│                    │      Hermes Agent           │   │
│                    │                             │   │
│                    │  /opt/data                  │   │
│                    │  Gateway                    │   │
│                    │  Dashboard                  │   │
│                    └─────────────────────────────┘   │
│                                                      │
│  Personal files / SSH keys / other directories       │
│              NOT mounted into container              │
│                                                      │
└──────────────────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

Hermes gets a dedicated environment and a directory for its persistent data.

The rest of the machine stays outside that boundary unless I explicitly expose something.

🐳 Step 1: Install Docker

On macOS or Windows, install Docker Desktop and make sure the Docker engine is running.

On Linux, you can install Docker Engine using the instructions for your distribution.

You can verify Docker is available with:

docker --version
Enter fullscreen mode Exit fullscreen mode

Once Docker is working, we can create an isolated environment for Hermes.

📁 Step 2: Create a Dedicated Directory for Hermes

First, create a directory specifically for the Dockerized Hermes instance:

mkdir -p ~/.hermes-docker
Enter fullscreen mode Exit fullscreen mode

This directory is important for two reasons.

1. Persistence

Docker containers are disposable.

If we remove and recreate the Hermes container, we don’t want to lose things like:

  • Configuration
  • Sessions
  • Memory
  • Skills
  • Profiles
  • Logs
  • Other persistent agent data

We’ll store those outside the container in ~/.hermes-docker.

2. It becomes part of our trust boundary

Anything inside this directory is intentionally available to Hermes.

Instead of mounting my entire home directory, I’m giving the agent one dedicated location.

That distinction matters.

⚙️ Step 3: Run the Hermes Setup Inside Docker

Now we can start the official Hermes Agent image and launch the setup process:

docker run --rm -it \
  -v ~/.hermes-docker:/opt/data \
  nousresearch/hermes-agent setup
Enter fullscreen mode Exit fullscreen mode

The most important part here is:

-v ~/.hermes-docker:/opt/data
Enter fullscreen mode Exit fullscreen mode

The -v option creates a bind mount between a directory on the host and a directory inside the container.

Think of it like this:

HOST                           CONTAINER
~/.hermes-docker   ───────▶   /opt/data
Enter fullscreen mode Exit fullscreen mode

The left side:

~/.hermes-docker
Enter fullscreen mode Exit fullscreen mode

is the directory we just created on the host.

The right side:

/opt/data
Enter fullscreen mode Exit fullscreen mode

is where that directory appears inside the Docker container.

So when Hermes saves configuration, sessions, memory, skills, or other persistent data under /opt/data, those files are actually stored in ~/.hermes-docker on the host.

That means we can destroy and recreate the container without losing the Hermes environment.

More importantly, we’re sharing one dedicated directory instead of the entire host filesystem.

🧠 Step 4: Configure Hermes Agent

The first run downloads the required Docker image and launches the Hermes setup wizard.

From there, follow the normal Hermes configuration process.

In my setup, I:

  1. Use the quick setup
  2. Authenticate with Nous Portal
  3. Select a model
  4. Keep the terminal backend local
  5. Skip messaging platform configuration for now

Once setup finishes, the configuration is stored in our persistent directory.

That means future containers using the same mount can reuse it.

🌐 Step 5: Start the Hermes Gateway and Dashboard

Now we can start Hermes as a background container:

docker run -d \
  --name hermes-docker \
  --restart unless-stopped \
  -v ~/.hermes-docker:/opt/data \
  -p 18642:8642 \
  -p 19119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run
Enter fullscreen mode Exit fullscreen mode

There are a few important things happening here.

Run in the background

-d
Enter fullscreen mode Exit fullscreen mode

starts the container in detached mode.

Give the container a name

--name hermes-docker
Enter fullscreen mode Exit fullscreen mode

makes it easier to manage later:

docker logs hermes-docker
docker stop hermes-docker
docker start hermes-docker
Enter fullscreen mode Exit fullscreen mode

Keep the persistent directory

We’re mounting the same directory again:

-v ~/.hermes-docker:/opt/data
Enter fullscreen mode Exit fullscreen mode

So Hermes sees the configuration we created during setup.

Enable the dashboard

-e HERMES_DASHBOARD=1
Enter fullscreen mode Exit fullscreen mode

enables the Hermes Dashboard.

🔌 Understanding the Port Mapping

You’ll notice I’m using:

-p 18642:8642
-p 19119:9119
Enter fullscreen mode Exit fullscreen mode

Docker port mappings follow this pattern:

HOST_PORT:CONTAINER_PORT
Enter fullscreen mode Exit fullscreen mode

So:

18642 → 8642
19119 → 9119
Enter fullscreen mode Exit fullscreen mode

The ports on the right are the ones Hermes uses inside the container.

The ports on the left are the ones exposed on my Mac.

I’m deliberately using different host ports because I already have another Hermes instance running locally and don’t want the ports to clash.

If you’re running only the Docker instance, you can use the default ports 8642 and 9119 instead of 18642 and 19119.

✅ Step 6: Verify the Container Is Running

Run:

docker ps
Enter fullscreen mode Exit fullscreen mode

You should see the hermes-docker container running.

If something isn’t working, one of the first places to look is the container logs:

docker logs hermes-docker
Enter fullscreen mode Exit fullscreen mode

This becomes particularly useful when configuring the dashboard.

🔐 Step 7: Configure Dashboard Authentication

When I initially opened the dashboard, it didn’t start correctly.

Instead of hiding that part from the tutorial, I kept it in because it’s a useful troubleshooting example.

Checking:

docker logs hermes-docker
Enter fullscreen mode Exit fullscreen mode

showed that the dashboard needed an authentication provider.

Hermes provides authentication options for securing dashboard access.

I configured mine using Nous Portal authentication.

Once authentication was configured, the dashboard started successfully.

With my port mapping, I can access it at:

localhost:19119
Enter fullscreen mode Exit fullscreen mode

And now the Hermes Dashboard is running while Hermes itself remains inside the container.

💬 Step 8: Chat With Hermes Inside the Container

You can also enter the running container directly:

docker exec -it hermes-docker bash
Enter fullscreen mode Exit fullscreen mode

Then start Hermes:

hermes
Enter fullscreen mode Exit fullscreen mode

At this point you’re interacting with Hermes from a terminal inside the Docker container, rather than running Hermes directly on the host.

That’s useful for testing.

But I don’t necessarily want to enter the container every time I want to use the agent.

There’s a better option.

🖥️ Step 9: Connect Hermes Desktop to the Docker Instance

Hermes Desktop can connect to the Gateway running inside our container.

Open Hermes Desktop and navigate to:

Settings → Gateway → Remote Gateway
Enter fullscreen mode Exit fullscreen mode

Then configure it to use the Gateway exposed by your Docker container.

In my setup, that’s my url:

http://localhost:19119
Enter fullscreen mode Exit fullscreen mode

After authenticating, save the configuration and reconnect.

Now Hermes Desktop communicates with the Dockerized Hermes instance.

So from the user’s perspective, I still get the convenient desktop interface.

But the agent itself is operating inside the container.

🛡️ What Does Docker Actually Protect?

This is probably the most important part of the tutorial.

Running an AI agent inside Docker does not automatically make it safe.

Docker gives us a useful isolation boundary, but that boundary depends heavily on how the container is configured.

For example, imagine doing this:

Host machine
      │
      ▼
Entire home directory
      │
      ▼
Docker container
      │
      ▼
Hermes Agent
Enter fullscreen mode Exit fullscreen mode

You’ve technically containerized Hermes.

But you’ve also exposed a huge portion of your machine to it.

That’s not the setup I want.

Instead:

Host machine
      │
      ├── Personal files       ❌
      ├── SSH keys             ❌
      ├── Other projects       ❌
      ├── Docker socket        ❌
      │
      └── ~/.hermes-docker     ✅
                │
                ▼
          Hermes Container
Enter fullscreen mode Exit fullscreen mode

The container should get access only to the resources required for the task.

🚫 1. Don’t Mount Your Entire Home Directory

If you mount your complete home directory into the container, Hermes could potentially access whatever the container’s permissions allow within that mount.

That might include personal files, source code, configuration files, credentials, or other sensitive data.

That’s why I’m using:

~/.hermes-docker
Enter fullscreen mode Exit fullscreen mode

as a dedicated location instead.

If Hermes doesn’t need something, don’t expose it.

🔑 2. Be Careful With Credentials

The same principle applies to API keys and tokens.

Only provide the credentials Hermes actually needs.

Avoid unnecessarily exposing things such as:

~/.ssh
Enter fullscreen mode Exit fullscreen mode

or unrelated cloud credentials and secrets.

Containerization doesn’t help much if you put every sensitive credential inside the container anyway.

⚠️ 3. Don’t Expose the Docker Socket Without a Very Good Reason

Another thing I’m deliberately not mounting is:

/var/run/docker.sock
Enter fullscreen mode Exit fullscreen mode

Giving a container access to the host Docker daemon can dramatically expand what that container is capable of doing.

For an autonomous agent, that’s an especially important boundary to think about.

If Hermes doesn’t need to control Docker on the host, don’t give it that capability.

🧩 4. Docker Doesn’t Solve Prompt Injection

There’s another important limitation.

An AI agent can still encounter malicious or adversarial content.

For example, content from a webpage, repository, document, or other external source could attempt to manipulate the agent into performing unintended actions.

Putting the agent inside Docker doesn’t eliminate that problem.

The difference is what happens after the agent attempts the action.

If Hermes only has access to:

/opt/data
Enter fullscreen mode Exit fullscreen mode

then we’ve limited the environment available to it.

If we’ve mounted our entire computer, exposed sensitive credentials, and given it access to the Docker daemon, the potential impact is very different.

That’s why I think containerization is better understood as blast-radius reduction, not a magic AI security solution.

🎯 The Principle: Least Privilege for AI Agents

As AI agents become increasingly capable, I think one traditional security principle becomes even more important:

Least privilege.

An agent should receive the minimum access required to complete its task.

Not:

Agent
  │
  └── Everything on my computer
Enter fullscreen mode Exit fullscreen mode

But:

Agent
  │
  ├── Required files
  ├── Required credentials
  ├── Required network services
  └── Required tools
Enter fullscreen mode Exit fullscreen mode

Nothing more.

This becomes increasingly important as agents gain longer-running autonomy, terminal access, browser access, external integrations, scheduled execution, and the ability to coordinate multiple tools.

Docker vs VM for AI Agents

Docker is not the only way to isolate an autonomous agent.

You could also use:

  • A virtual machine
  • A dedicated VPS
  • A sandboxed execution environment
  • A separate physical machine
  • More restrictive container runtimes

A VM generally provides a stronger isolation boundary than a standard application container because it virtualizes a larger portion of the environment.

Docker, however, is lightweight and convenient for local development.

For my Hermes setup, it gives me a useful middle ground:

Direct Host Execution
        ↓
Docker Container
        ↓
Virtual Machine / Dedicated Environment
Enter fullscreen mode Exit fullscreen mode

The appropriate boundary ultimately depends on what capabilities you’re giving the agent and what resources it can access.

Final Architecture

After everything is configured, my setup looks roughly like this:

                   ┌─────────────────────────────┐
                   │        Host Machine         │
                   │                             │
                   │      Hermes Desktop         │
                   └──────────────┬──────────────┘
                                  │
                           Remote Gateway
                                  │
                                  ▼
              ┌─────────────────────────────────┐
              │       Docker Container          │
              │                                 │
              │       Hermes Gateway            │
              │       Hermes Dashboard          │
              │       Hermes Agent              │
              │                                 │
              │       /opt/data                 │
              └───────────────┬─────────────────┘
                              │
                         Bind Mount
                              │
                              ▼
                    ~/.hermes-docker
                              │
              ┌───────────────┴──────────────┐
              │ Config • Memory • Sessions   │
              │ Skills • Profiles • Logs     │
              └──────────────────────────────┘
       Rest of host filesystem → NOT MOUNTED
       SSH keys                → NOT EXPOSED
       Docker socket           → NOT EXPOSED
Enter fullscreen mode Exit fullscreen mode

Hermes still has the environment it needs to work.

But we’re being much more deliberate about what crosses the boundary.

Final Thoughts

Autonomous AI agents are becoming capable of doing much more than generating text.

They’re increasingly able to:

⚡ Execute commands
🗂️ Manipulate files
🌍 Interact with external systems
🧰 Use specialized tools
🔄 Run multi-step workflows autonomously

That’s exciting.

But the more capable the agent becomes, the more important its execution environment becomes.

Running Hermes Agent inside Docker doesn’t solve every security problem.

It does, however, give us a practical way to control what the agent can access and reduce the potential blast radius when something unexpected happens.

The rule I follow is simple:

Only give an AI agent access to what it actually needs.

Everything else should stay outside the boundary.

Top comments (1)

Collapse
 
vivek_shetye profile image
Vivek Shetye •

If you’re already running Hermes Agent or another autonomous AI agent, I’m curious how you’re isolating it:

Docker, VM, VPS, sandbox or directly on your host machine?

Drop your setup in the comments. 👇