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

> Source: <https://dev.to/vivek_shetye/run-hermes-agent-inside-docker-a-safer-setup-for-autonomous-ai-agents-2992>
> Published: 2026-09-22 16:35:22+00:00

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

Especially when that agent can:

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:

🎥 Prefer watching instead?

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

Watch the full Hermes Agent Docker tutorial on YouTube →

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              │
│                                                      │
└──────────────────────────────────────────────────────┘
```

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.

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
```

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

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

```
mkdir -p ~/.hermes-docker
```

This directory is important for two reasons.

Docker containers are disposable.

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

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

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.

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
```

The most important part here is:

```
-v ~/.hermes-docker:/opt/data
```

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
```

The left side:

```
~/.hermes-docker
```

is the directory we just created on the host.

The right side:

```
/opt/data
```

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.

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:

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

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

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
```

There are a few important things happening here.

Run in the background

```
-d
```

starts the container in detached mode.

Give the container a name

```
--name hermes-docker
```

makes it easier to manage later:

```
docker logs hermes-docker
docker stop hermes-docker
docker start hermes-docker
```

Keep the persistent directory

We’re mounting the same directory again:

```
-v ~/.hermes-docker:/opt/data
```

So Hermes sees the configuration we created during setup.

Enable the dashboard

```
-e HERMES_DASHBOARD=1
```

enables the Hermes Dashboard.

You’ll notice I’m using:

```
-p 18642:8642
-p 19119:9119
```

Docker port mappings follow this pattern:

```
HOST_PORT:CONTAINER_PORT
```

So:

```
18642 → 8642
19119 → 9119
```

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.

Run:

```
docker ps
```

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
```

This becomes particularly useful when configuring the dashboard.

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
```

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
```

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

You can also enter the running container directly:

```
docker exec -it hermes-docker bash
```

Then start Hermes:

```
hermes
```

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.

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

Open Hermes Desktop and navigate to:

```
Settings → Gateway → Remote Gateway
```

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

In my setup, that’s my url:

```
http://localhost:19119
```

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.

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
```

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
```

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

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
```

as a dedicated location instead.

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

The same principle applies to API keys and tokens.

Only provide the credentials Hermes actually needs.

Avoid unnecessarily exposing things such as:

```
~/.ssh
```

or unrelated cloud credentials and secrets.

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

Another thing I’m deliberately not mounting is:

```
/var/run/docker.sock
```

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.

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
```

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.

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
```

But:

```
Agent
  │
  ├── Required files
  ├── Required credentials
  ├── Required network services
  └── Required tools
```

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 is not the only way to isolate an autonomous agent.

You could also use:

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
```

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

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
```

Hermes still has the environment it needs to work.

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

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.