Hermes Agent Bubblewrap: Set Up The Linux Sandbox In 6 Steps

Hermes Agent bubblewrap is the official Linux plugin that wraps every shell command your agent runs in its own throwaway bwrap sandbox, with no container image and no daemon to babysit.

It is part of the Hermes Official Plugins repo, which describes it as built and supported by Nous Research.

The Hermes v0.23.0 catalog entry pins version 1.3.0, lists Linux as the only platform and asks for Hermes 0.22.6 or later, so 1.3.0 is the version this walkthrough covers.

Below is the six-step setup I would follow on a fresh box, the settings I touch, and the traps that bite on day one.

If you want my team to look over how your agents are wired, book a free SEO strategy session.

What The Bubblewrap Backend Actually Does

Hermes sends shell work through a terminal backend.

The default local backend runs commands straight on your machine as your user.

Bubblewrap is a plugin backend that slots into the same place.

Each terminal call and each execute_code call gets a brand-new sandbox, and that sandbox is torn down when the command finishes.

The plugin README states plainly that it is not a container: the command sees your real filesystem at its real paths, but read-only, with one writable working directory and your credentials hidden.

The underlying tool is bubblewrap, the small unprivileged sandboxing program from the containers project.

The README pitches it for a personal machine or a small server where local feels too open and Docker feels like too much machinery.

Step 1: Confirm The Box Meets The Four Requirements

Check these before you install anything.

Linux. There is no macOS or Windows build of this backend.
bubblewrap 0.9.0 or newer. Run bwrap --version if it is already there.
prlimit from util-linux, which ships on every mainstream distro.
Unprivileged user namespaces switched on, or a setuid bwrap.

You also need Hermes 0.22.6 or later, because that is the release where file tools started running inside sandboxing backends.

Run hermes --version and update first if you are behind.

Step 2: Install bwrap From Your Package Manager

Pick the line that matches your distro.

sudo apt install bubblewrap     # Debian, Ubuntu
sudo dnf install bubblewrap     # Fedora
sudo pacman -S bubblewrap       # Arch

That is the only system package involved.

The catalog notes the plugin has no Python dependencies and makes no network calls of its own; it just drives the bwrap and prlimit binaries.

Step 3: Install The Plugin And Switch The Backend

Two Hermes commands do the rest.

hermes plugins install bubblewrap
hermes config set terminal.backend bubblewrap

The first pulls the plugin from the catalog.

The second tells Hermes to send terminal work through it instead of the local backend.

If you prefer menus, hermes setup shows bubblewrap as a backend once the plugin is installed and asks which profile you want.

Installing with NousResearch/hermes-official-plugins#bubblewrap instead pulls the repo's main branch, which has already moved past 1.3.0, so read the README for whatever version you end up on.

🔥 Want the exact Hermes backend config our members run on their servers? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS, four coaching calls a week and 3,400+ members swapping their Hermes setups. → Join the AI Profit Boardroom

Step 4: Run hermes doctor And Fix The Ubuntu 24.04 Probe

hermes doctor

Doctor reports three things for this backend: whether bwrap was found, which version it is, and whether a test sandbox starts.

If the probe fails, your user is not allowed to create user namespaces.

On Ubuntu 24.04 and later the usual cause is the AppArmor setting kernel.apparmor_restrict_unprivileged_userns.

Follow your distribution's own notes for letting bubblewrap use user namespaces, then run doctor again.

Here is the part I like: while the probe is failing, Hermes does not quietly fall back to running commands on the host.

The terminal tool returns a degraded result that names the missing package, or a hard error if you set terminal.degraded_mode: fail.

The README is explicit that commands never run outside the sandbox.

Step 5: Pick A Profile And Pin The Working Directory

Version 1.3.0 ships three profiles.

Profile	Working directory	Network	When I use it
`restricted`	Read-only	Loopback only	Reading and analysing code or files I do not trust yet
`workspace`	Writable	Loopback only	Edits and builds that have no business on the internet
`network`	Writable	Host network	Installs, git pulls, API calls (this is the default)

hermes config set plugins.entries.bubblewrap.settings.profile workspace
hermes config set terminal.cwd /srv/client-site

The working directory is the whole writable set.

Everything under terminal.cwd can change; everything else is read-only.

A cd somewhere else moves where the command starts, but it runs read-only there.

Point it at one project or one scratch folder, never at /, which the plugin refuses anyway.

If you leave it unset, Hermes uses the directory it was launched from, the same as the local backend.

Step 6: Raise The Limits Before pip Hits Them

Each command runs under three per-process limits, applied by prlimit before the sandbox starts.

Setting	Default	What it caps
`memory_mb`	256	Virtual memory per process
`cpu_seconds`	30	CPU time per process
`max_procs`	256	Processes and threads the command can add

Those defaults are tight on purpose, and the README warns that pip, node, cargo and most compilers want more than 256 MB of address space.

You will see a MemoryError or a similar message when memory runs out, and an exit code of 137 when a long compile runs out of CPU time.

For any box that installs packages, I set this on day one:

hermes config set plugins.entries.bubblewrap.settings.memory_mb 2048
hermes config set plugins.entries.bubblewrap.settings.cpu_seconds 600

Setting any of the three to 0 switches that limit off.

I leave max_procs alone; the kernel counts it per user, so a runaway fork loop stops near 256 processes without dragging down the rest of the machine.

What Stays Hidden From Every Command

This is why you install it.

Credential stores are always hidden: .ssh, .aws, .gnupg, .kube, .docker, .netrc, .npmrc, .pypirc, .pgpass, .git-credentials, .config/gh, .config/gcloud, browser profiles and desktop keyrings.
Every other dot entry in your home folder is hidden too unless it sits on an allowlist.
The Hermes home, with its .env and auth files, is hidden.
/run/user/<uid> is an empty tmpfs, so ssh-agent, gpg-agent, keyring and D-Bus sockets cannot be reached.
The docker socket, if you have one, is swapped for an empty file.
Each command gets its own pid namespace, so it cannot see or signal host processes.
Provider API keys stay out of the command environment.

Need a tool config inside the sandbox, such as your editor settings?

Add it with home_allow; allowed dot entries show up read-only.

hermes config set plugins.entries.bubblewrap.settings.home_allow '[".config/nvim"]'

Naming a credential store there does nothing except log a warning.

What The Sandbox Leaves Open

Know these limits before you trust it with anything.

The rest of the host filesystem is readable, including /etc and any secrets sitting inside project folders.
There is no seccomp filter, so system calls are not filtered.
There are no cgroup limits; the caps are per process, so a command that forks can use more memory in total.
Network is all or nothing: the network profile shares the host network with no outbound filtering.
Other Unix sockets outside the masked ones stay connectable if a command knows the path.
Background processes die as soon as their command's shell exits.
execute_code has no persistent kernel, so Python state does not carry between calls.

My rule: move secrets out of project folders and into the hidden paths before you switch the backend on.

Approvals Still Fire, Just Like Local

People assume a sandbox means fewer prompts.

Not here.

Because the working directory is a real host folder, the README says Hermes keeps its dangerous-command approval exactly as it does for the local backend, hardline blocklist included.

Compare that with the container backends in the Hermes security guide: docker, modal, daytona and vercel_sandbox skip the dangerous-command check because the container is treated as the boundary.

So with bubblewrap you keep both layers: the sandbox and the approval prompt.

Cron jobs still follow approvals.cron_mode, which defaults to deny, so an unattended job that hits a risky command gets blocked rather than waved through.

📞 Running Hermes for client work and want a second pair of eyes? Book a free SEO strategy session and my team will walk through your agent setup with you. → Grab a free call with my team

Three Small-Business Setups I Would Copy

A bookkeeper testing a script from a forum

Drop the script into /srv/inbox-scripts and set that as the working directory.

Switch the profile to restricted.

Ask Hermes to read the script and explain every file it would touch and every host it would call.

Flip to workspace and run it against a copy of one export, with no network.

Only then decide whether it earns a place in your real routine.

A two-person web agency building client sites

Set the working directory to the client repo and keep the default network profile so npm install can reach the registry.

Raise memory_mb to 2048 before the first build.

The agent can edit and build inside that one repo, while your SSH keys and git credentials stay hidden.

Push from your own shell, not from the agent.

A plumbing firm with a Telegram assistant on a mini PC

The gateway runs on a small Linux box in the office.

Set the profile to workspace and point the working directory at a /srv/jobs folder of job sheets.

The assistant can sort and summarise files there, but it has no internet from the shell and cannot read anything in your dot folders.

Gotchas That Catch People On Day One

Writing to /tmp. Each command gets a fresh /tmp, so files vanish. Use the working directory or the Hermes scratch directory that TMPDIR points to, which persists for the session.
Long-running servers. A dev server started with background: true dies right after it starts. The model is told background processes are unavailable.
CA bundles in the Hermes home. Move them to a path like /usr/local/share/ca-certificates, or TLS can break.
Extra data folders. Mount them with binds; they are read-only unless you add "readonly": false.
File tools cost a spawn. read_file, write_file, patch and search_files all run inside the sandbox now, one sandbox per call.

Want the bigger picture on what else to bolt on? Our rundown of the best Hermes Agent plugins covers the rest of the catalog.

The plugin landed in the catalog through PR #142548 and is listed under new official plugins in the v0.23.0 release notes.

Also On Our Network

FAQ: Hermes Agent Bubblewrap

What command switches Hermes to the bubblewrap backend?

After installing the plugin, run hermes config set terminal.backend bubblewrap. Then run hermes doctor to confirm the sandbox probe passes.

Why does hermes doctor say the bubblewrap probe failed?

Your user cannot create unprivileged user namespaces. On Ubuntu 24.04 and later this is usually the AppArmor kernel.apparmor_restrict_unprivileged_userns restriction.

Why does pip fail with MemoryError inside the sandbox?

The default memory_mb is 256, which pip, node, cargo and most compilers exceed. Raise it to 1024 or 2048.

Can I run a dev server in the background with bubblewrap?

No. Each command is its own sandbox, so a background job dies once its shell exits.

Which profile is the default?

The network profile: writable working directory and the host network. Restricted and workspace both keep loopback only.

📺 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 a team of 70+ SEO experts.
I've grown a YouTube channel to 400,000+ subscribers.
I wrote "Link Building Mastery".
My Udemy courses have taught over 29,000 students.

→ Get my best AI training inside the AI Profit Boardroom

Install bwrap, flip the backend, run doctor, raise memory, and when the box is ready book a free SEO strategy session or join the AI Profit Boardroom to keep building with Hermes Agent bubblewrap.