Hermes Agent Sandbox: Set Up Docker Or Bubblewrap In 5 Steps

Q: What is a Hermes Agent sandbox?

A Hermes Agent sandbox is the isolated environment where Hermes runs its terminal commands. You pick it with the terminal.backend setting. The docs list local, docker, ssh, modal, daytona, vercel_sandbox and singularity, and the official bubblewrap plugin adds a Linux sandbox on your own machine.

Q: Does Hermes Agent run in a sandbox by default?

No. The default backend is local, which runs commands directly on your machine with no isolation. The docs warn that the agent then has the same filesystem access as your user account, and they suggest Docker for sandboxing.

Q: How do I switch Hermes Agent to the Docker sandbox?

Install and start Docker, check it with docker version, then run hermes config set terminal.backend docker. You can also run hermes setup terminal and pick the backend from the wizard. To go back, run hermes config set terminal.backend local.

Q: Is the Hermes Agent sandbox free?

Hermes Agent is free and open source under the MIT licence, and the docker, ssh, singularity and bubblewrap backends run on hardware you already have. The cloud options such as Modal, Daytona and Vercel Sandbox need an account with that provider and its own credentials.

A Hermes Agent sandbox is the isolated place where Hermes runs its shell commands, so a bad command hits a container or a locked-down box instead of your real computer.

You choose it with one setting, terminal.backend, and you switch it with one command.

Hermes Agent is the free, open-source agent from Nous Research, and the sandbox options are built in or sit in its official plugin catalog.

Out of the box, Hermes uses the local backend, which means commands run straight on your machine with no isolation at all.

The official docs put it plainly: the agent has the same filesystem access as your user account.

That's fine for a quick test, but it's the first thing I'd change before I let an agent run unattended.

This walkthrough shows you how to pick a sandbox, switch to it, lock down your secrets and keep the approval rules that still matter.

Everything here comes from the official Hermes docs, the plugin catalog and the release notes, and I'll tell you where a feature has limits.

The Hermes Agent Sandbox Setup At A Glance

This is the whole setup on one screen, and the rest of the page walks through each step.

Step	What you do	The command or setting
1	You pick the backend that fits your machine and your risk.	Docker for most people, bubblewrap on a Linux box, SSH or a cloud sandbox for a separate machine.
2	You install what that backend needs.	Docker Desktop or Docker Engine, the bubblewrap package, or the provider's credentials.
3	You switch Hermes to it.	`hermes config set terminal.backend docker` or `hermes setup terminal`.
4	You lock down secrets, network and resources.	`docker_forward_env`, `docker_network` and the `container_*` limits.
5	You keep your hard rules and check the setup.	`approvals.deny` plus `hermes doctor`.

What A Hermes Agent Sandbox Actually Is

Every time Hermes runs a terminal command, the terminal backend decides where that command really executes.

The official configuration docs say Hermes supports seven terminal backends.

They are your local machine, a Docker container, a remote server over SSH, a Modal cloud sandbox, a Daytona workspace, a Vercel Sandbox and a Singularity or Apptainer container.

On 21 October 2026, the plugin catalog also added an official bubblewrap backend for Linux, and the v0.22.4 release notes list it alongside Singularity/Apptainer.

So "sandbox" isn't one product.

It's the choice of where your agent's hands are allowed to touch.

I've written a wider guide to every Hermes Agent backend, and this page goes deeper on the isolation and security side.

🔥 Want my exact Hermes Agent Sandbox setup, step by step? Inside the AI Profit Boardroom you get step-by-step video trainings, my installable Agent OS and four coaching calls a week with 3,400+ members building real automations. → Join the AI Profit Boardroom

Which Hermes Agent Sandbox Should You Pick?

This table is taken from the docs' own backend overview and security comparison, with the bubblewrap row from its plugin page.

Backend	Where commands run	Isolation	Dangerous-command check	Best for
`local`	They run on your machine directly.	There is none.	It stays on.	It suits development and personal use.
`docker`	They run in one persistent Docker container.	It is full, with namespaces and dropped capabilities.	It is skipped because the container is the boundary.	It suits safe sandboxing, CI/CD and a production gateway.
`bubblewrap`	They run in a bwrap sandbox on the same Linux machine.	It gives a read-only root and hides your credentials.	It stays on, exactly as for local.	It suits a personal machine where Docker feels too heavy.
`ssh`	They run on a remote server.	It is a network boundary.	It stays on.	It suits remote dev and powerful hardware.
`modal`	They run in a Modal cloud sandbox.	It is a full cloud VM.	It is skipped.	It suits ephemeral cloud compute and evals.
`daytona`	They run in a Daytona workspace.	It is a full cloud container.	It is skipped.	It suits managed cloud dev environments.
`vercel_sandbox`	They run in a Vercel Sandbox microVM.	It is a full cloud microVM.	It is skipped.	It suits cloud runs with snapshot persistence.
`singularity`	They run in a Singularity or Apptainer container.	It uses namespaces with `--containall`.	It is skipped.	It suits HPC clusters and shared machines.

My simple rule is this.

If you can run Docker, start with Docker.

If you're on a small Linux server and Docker feels like overkill, look at bubblewrap.

If you want the agent nowhere near your laptop, use SSH to a separate box or one of the cloud sandboxes.

If you're choosing a server for that, look for one you can wipe and rebuild without losing anything important.

Step 1: Set Up The Docker Sandbox

Docker is the backend the security docs recommend for a production gateway, so it's where I'd start.

First, install Docker Desktop or Docker Engine and make sure it's running.

The docs give you a quick check.

docker version

If that prints a version, switch Hermes over with one command.

hermes config set terminal.backend docker

You can also run the interactive wizard for just this section.

hermes setup terminal

The setting lives under terminal: in ~/.hermes/config.yaml, so the YAML version looks like this.

terminal:
  backend: docker
  docker_image: "nousresearch/hermes-sandbox:desktop"

Since v0.22.0, nousresearch/hermes-sandbox:desktop is the default image, and the release notes say existing sandboxes are kept.

That image carries a display stack, which matters later for Bot Screen and the browser.

Podman works too, and the docs say you set HERMES_DOCKER_BINARY=podman when both are installed.

How the Docker sandbox behaves

By default Hermes starts one long-lived container and routes every terminal, file and execute_code call into it.

That one container is shared across sessions, /new, /reset and delegate_task subagents.

Installed packages, files in /workspace and background processes all carry over, which is handy for dev servers and long test runs.

If you'd rather treat each chat as its own security boundary, set container_persistent: false.

Then every chat gets a fresh container that is removed when the session closes or goes idle.

The hardening you get for free

The docs list the flags Hermes applies to every Docker container.

It drops all Linux capabilities with --cap-drop ALL and adds back only DAC_OVERRIDE, CHOWN and FOWNER.
It sets --security-opt no-new-privileges, so a process can't escalate.
It caps the container at 256 processes with --pids-limit 256.
It gives /tmp, /var/tmp and /run small, size-limited tmpfs mounts.

Step 2: Or Set Up The Bubblewrap Sandbox On Linux

Bubblewrap is the new option, and it's built and supported by Nous Research as an official plugin.

The plugin page describes it as a sandbox that is "not a container", because it uses your host's own paths with a read-only root.

It needs no image and no daemon, so it fits a personal machine or a small server.

It's Linux only, and it needs bubblewrap 0.9.0 or later, prlimit from util-linux and unprivileged user namespaces.

These are the install lines from the plugin page.

sudo apt install bubblewrap     # Debian, Ubuntu
sudo dnf install bubblewrap     # Fedora
sudo pacman -S bubblewrap       # Arch
hermes plugins install bubblewrap
hermes config set terminal.backend bubblewrap

After that, hermes doctor reports whether bwrap is found and whether the sandbox probe passes.

On Ubuntu 24.04 and later, the plugin page says a failed probe usually points at the AppArmor restriction on unprivileged user namespaces.

If the probe fails, commands are never run outside the sandbox, which is exactly the behaviour you want.

The three bubblewrap profiles

Profile	Working directory	Network	Use it for
`restricted`	It is read-only.	There is none beyond loopback.	It suits inspection and read-only analysis.
`workspace`	It is writable.	There is none beyond loopback.	It suits builds and edits that must not reach the network.
`network`	It is writable.	It shares the host network.	It covers everything else and is the default.

You set the profile with this command from the plugin page.

hermes config set plugins.entries.bubblewrap.settings.profile workspace

Bubblewrap hides .ssh, .aws, .gnupg, .config/gcloud, .azure, .docker, .kube, .npmrc, .pypirc, .netrc and .env in your home directory.

It hides the Hermes home too, apart from its own state and scratch folders.

The default limits are tight, with 256 MB of memory, 30 seconds of CPU time and 256 processes per command.

The plugin page warns that pip, node, cargo and most compilers need more memory, so raise memory_mb to 1024 or 2048 for real builds.

Be honest with yourself about the gaps too.

The file tools such as read_file and write_file still run on the host, there's no seccomp filter, and background processes die as soon as the command ends.

🔥 Want my Hermes setups done with you, step by step? Inside the AI Profit Boardroom, I've got a full Hermes Agent course plus the Agent OS, with video walkthroughs on profiles, models and plugins. You'll be learning alongside 3,400+ members with four coaching calls every week. → Get access here

Step 3: Use A Remote Or Cloud Sandbox Instead

Sometimes the safest sandbox is a different machine.

SSH to a separate box

The security docs suggest running the gateway on a separate machine or VM for maximum isolation.

You set terminal.backend: ssh in config.yaml and put the host details in ~/.hermes/.env.

TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu

The docs keep these details in .env so they aren't shared with profile exports.

Modal, Daytona and Vercel Sandbox

Each cloud backend needs its own credentials, and the docs list them clearly.

Modal needs MODAL_TOKEN_ID and MODAL_TOKEN_SECRET, or a ~/.modal.toml file.
Daytona needs DAYTONA_API_KEY, and it caps disk at 10 GiB.
Vercel Sandbox needs VERCEL_TOKEN, VERCEL_PROJECT_ID and VERCEL_TEAM_ID.

Persistence in these cloud sandboxes keeps the filesystem, not live processes, so a dev server won't still be running next time.

For SSH, Modal and Daytona, Hermes syncs its own state back on teardown, but the docs say you should copy important work files out yourself before the sandbox is destroyed.

Singularity or Apptainer

Singularity is for HPC clusters and shared machines where Docker isn't available.

It needs apptainer or singularity on your PATH, and it runs with --containall --no-home so it never sees your home directory.

The plugin catalog now lists it as an official plugin too, and the plugin page says existing users are migrated automatically.

Step 4: Lock Down Secrets, Network And Resources

A sandbox only protects you if you don't hand it your keys.

For Docker, docker_forward_env is an explicit allowlist, and the docs say an empty list keeps secrets out of the container.

If you add a name such as GITHUB_TOKEN, code in the container can read it and send it somewhere, so add only what a job truly needs.

To cut the network completely, set docker_network: false, which runs the container with --network=none.

terminal:
  backend: docker
  docker_forward_env: []
  docker_network: false
  container_cpu: 1
  container_memory: 5120
  container_disk: 51200
  container_persistent: true

Those CPU, memory and disk numbers are the documented defaults of one core, 5 GB and 50 GB.

Mount only the folders the agent needs with docker_volumes, and add :ro to make a mount read-only.

The docs also warn that extra flags in docker_extra_args can silently weaken isolation if they clash with the hardening.

Step 5: Keep Your Hard Rules With approvals.deny

Here's the part people miss.

On docker, singularity, modal, daytona and vercel_sandbox, Hermes skips its dangerous-command prompts, because the container itself is the security boundary.

Your own deny list still applies, though.

The v0.22.0 release notes say approvals.deny now works in sandboxes, and the security docs say deny rules apply to every terminal backend before any backend-specific shortcut.

approvals:
  deny:
    - "git push --force*"
    - "*curl*|*sh*"
    - "dd if=* of=/dev/*"

Deny rules even run before --yolo, /yolo and approvals.mode: off.

The docs are clear that deny rules are a shell-command policy and not a full sandbox, so pair them with an isolated backend rather than relying on them alone.

For writes, there's also an optional guard called HERMES_WRITE_SAFE_ROOT, which limits write_file and patch to the folders you list.

When you've finished, run hermes doctor to check the backend is healthy.

How Bot Screen, Computer Use And The Browser Follow The Sandbox

This is the v0.22 change I covered in the video above.

With a Docker, SSH or Singularity backend, the release notes say the bot's screen, computer use and the browser run inside the sandbox, never on your host.

The Bot Screen docs add that Modal, Daytona and Vercel Sandbox can't host a display yet, so Hermes refuses to start the screen there rather than quietly running it on your host.

If you really want the old behaviour, bot_desktop.placement: gateway puts the screen on the gateway host as an explicit opt-in.

If you are new to bots, start with my Hermes Agent bot mode guide.

Common Hermes Agent Sandbox Problems And Fixes

The docs have a short troubleshooting list, and these are the ones you'll hit first.

If Docker commands fail, run docker version, and if that fails, fix Docker or run hermes config set terminal.backend local.
If SSH fails, check that both TERMINAL_SSH_HOST and TERMINAL_SSH_USER are set.
If Modal fails, check MODAL_TOKEN_ID or ~/.modal.toml, then run hermes doctor.
If bubblewrap fails, check hermes doctor for the probe result and your distribution's user-namespace setting.
If a build dies inside bubblewrap with a memory error, raise memory_mb, because the default is only 256 MB.

When in doubt, the docs say to set the backend back to local and check that commands work there first.

Tips I'd Follow Before Going Live

These come straight from the docs' production checklist.

Use a container backend for any gateway that strangers can message.
Set explicit user allowlists and never allow all users in production.
Set terminal.cwd so the agent doesn't work from a sensitive folder.
Run the gateway as a normal user and never as root.
Run hermes update regularly so you get security fixes.

If you're also connecting outside tools, read my sister guide on the Hermes Agent MCP server, because MCP tools need the same care.

If you'd like a second pair of eyes on how agents fit your SEO business, you can book a free SEO strategy session with my team.

🔥 Want help picking the right Hermes setup for your business? The AI Profit Boardroom has Hermes Agent training, the Agent OS and four weekly coaching calls where you can ask me which backend to switch on first. → Join the AI Profit Boardroom

Also On Our Network

FAQ: Hermes Agent Sandbox

What is a Hermes Agent sandbox?

It's the isolated environment where Hermes runs its terminal commands, and you choose it with terminal.backend.

The docs list seven backends, and the official bubblewrap plugin adds an eighth option for Linux.

Does Hermes Agent run in a sandbox by default?

No, the default is local, which has no isolation.

The docs suggest switching to Docker if you want sandboxing.

How do I switch Hermes Agent to the Docker sandbox?

Check Docker with docker version, then run hermes config set terminal.backend docker.

You can also run hermes setup terminal and pick it from the wizard.

Do approval prompts still work inside a Hermes sandbox?

Container backends skip the dangerous-command prompts, but your approvals.deny rules still apply everywhere.

The local, SSH and bubblewrap backends keep the normal approval checks.

Is the Hermes Agent sandbox free?

Hermes is free under the MIT licence, and the local, Docker, SSH, Singularity and bubblewrap options run on your own hardware.

The cloud sandboxes need an account with Modal, Daytona or Vercel.

If you run an agency and want help mapping agents to your client work, you can book a free strategy session and we'll talk it through.

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉

About Julian

I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.

I help business owners scale with AI agents, automation and SEO.

I've built a 7-figure SEO and link-building agency, Goldie Agency, with 70+ people in Bangkok.
I've grown a YouTube channel to 400,000+ subscribers.
I wrote the book "Link Building Mastery", which covers nine link building strategies.
I run GoldieBench, where I score AI models on real one-shot builds.

→ Get my best AI training inside the AI Profit Boardroom

Pick Docker or bubblewrap, switch with one command, keep your deny list, and you'll have a Hermes Agent sandbox that protects your real machine.