agentos.guide › blog

Hermes Agent Bubblewrap: A Quick Start And Four Prompts To Sandbox Every Command In Your Agent OS

By Julian Goldie · 8 November 2026 · agentos.guide

Hermes Agent bubblewrap gives the Hermes inside your Agent OS a fenced-off terminal on Linux: every command runs in its own short-lived bwrap sandbox that can read the machine, write to one folder, and never see your credentials.

It is an official plugin, built and supported by Nous Research according to its README, and the v0.23.0 catalog pins version 1.3.0 for Hermes 0.22.6 and later.

This guide gives you a quick start, four prompts to hand your agent, and a short routine for client work.

If you would like my team to help plan your setup, book a free SEO strategy session.

Why Your Agent OS Wants A Sandboxed Terminal

An Agent OS runs lots of jobs unattended: cron tasks, kanban workers, gateway chats.

On the local backend each of those commands runs as you, with your full reach.

Bubblewrap keeps the convenience of local, with your real tools at their real paths, but mounts the host read-only and hides the folders where logins live.

There is no image to build and no daemon to keep alive, which suits a single Linux server or office PC.

Cron jobs and subagents share their parent session's sandbox, so the whole OS sits behind the same fence.

Quick Start: Five Commands On A Linux Box

sudo apt install bubblewrap            # or: dnf install / pacman -S
hermes plugins install bubblewrap
hermes config set terminal.backend bubblewrap
hermes config set plugins.entries.bubblewrap.settings.memory_mb 2048
hermes doctor

You need bubblewrap 0.9.0 or newer, prlimit from util-linux and unprivileged user namespaces.

If hermes doctor reports a failed probe on Ubuntu 24.04 or later, the AppArmor setting kernel.apparmor_restrict_unprivileged_userns is blocking it; follow Ubuntu's notes for bubblewrap.

Until the probe passes, Hermes returns a degraded result instead of running commands unprotected.

The memory line is there because the default of 256 MB is too small for pip, node, cargo and most compilers.

Choose The Profile For Each Job

Set the writable folder with terminal.cwd.

Only that folder, plus any read-write binds you add, can change.

A named Hermes profile has its own config.yaml, per the configuration docs, so a client-work profile and an audit profile can each carry their own settings.

🔥 Want the full Agent OS with Hermes already wired in?

Inside the AI Profit Boardroom you get the installable Agent OS, step-by-step video trainings, four coaching calls a week and 3,400+ members sharing their prompts.

→ Join the AI Profit Boardroom

Prompt 1: Prove The Sandbox Is Really On

Run this once after setup, and again after any Hermes update.

Check your terminal sandbox for me. Run each step and report what you see:
1. Print the terminal backend you are using.
2. Try to list ~/.ssh and ~/.aws and tell me whether they exist.
3. Try to create a file outside the working directory and report the error.
4. Create test.txt inside the working directory, then delete it.
5. Write a file to /tmp, then check in a second command whether it is still there.
Do not change any settings. Summarise in a short table.

Expected result: the credential folders are missing, the outside write fails with a read-only error, the working-folder write succeeds, and the /tmp file is gone in the second command because each command gets a fresh one.

Prompt 2: Inspect A Downloaded Script In Restricted Mode

Switch the profile to restricted first, with the script's folder as the working directory.

A script called [name] is in the working directory. Do not run it.
Read it and tell me in plain English:
- every file or folder it reads, writes or deletes
- every web address or IP it contacts
- every package it installs
- anything that touches passwords, keys or tokens
Finish with a one-line verdict: safe to test offline, needs changes, or do not use.

A bookkeeper testing a CSV clean-up tool from a forum, or a shop owner trying a feed converter, would start here.

Once the verdict comes back, switch to workspace and run it on a copy of one sample file.

Prompt 3: Build A Client Site With Room To Breathe

Keep the default network profile so installs can reach the registry, with the client repo as the working directory.

Work only inside this repository.
1. Install dependencies.
2. Run the build.
3. If a step fails with MemoryError or exit 137, stop and tell me which limit to raise (memory_mb or cpu_seconds) instead of retrying.
4. Do not start a dev server; background processes do not survive in this sandbox.
5. List the files you changed. Do not push or deploy.

Exit 137 means the CPU-time cap of 30 seconds killed the process.

Raise cpu_seconds to something like 600 for longer builds.

Prompt 4: Morning Health Check As A Cron Job

Every weekday at 8am: in the reports folder, check that yesterday's export file exists and is not empty, count its rows, and compare with the day before. Write the result to health.md in the same folder. Do not delete or move anything. If something looks wrong, say what and stop.

Run this one under workspace, since it needs no internet.

Remember that approvals still apply here, and in cron the default approvals.cron_mode is deny, so a risky command is blocked rather than approved.

Prompt 5: Let A Tool See Its Config, Safely

Some tools need a dot folder to work, such as an editor or a linter config.

A command failed because it could not find its config in my home folder.
Tell me which dot entry it was looking for, without guessing.
If it is a credential store (.ssh, .aws, .gnupg, tokens, browser profiles), say so and stop.
Otherwise give me the exact hermes config set command to add it to home_allow, and remind me it will be read-only.

Credential stores stay hidden even if you add them, so the worst outcome is a warning in the log.

Troubleshooting In Your Agent OS

• Probe fails in doctor: user namespaces are blocked; on Ubuntu 24.04+ check the AppArmor restriction.
• Files in /tmp disappear: each command gets a fresh one; save to the working folder or the Hermes scratch directory instead.
• Python variables vanish between calls: execute_code has no persistent kernel here, so write state to a file.
• TLS errors on the network profile: a CA bundle kept inside the Hermes home needs to move somewhere like /usr/local/share/ca-certificates.
• Writes fail after a cd: only terminal.cwd is writable, wherever the agent moves to.

Members of the AI Profit Boardroom share fixes for exactly these snags on the weekly calls.

What The Agent Can And Cannot Reach

Hidden from every command: your SSH folder, cloud logins for AWS and gcloud, GPG keys, browser profiles and keyrings, registry tokens such as .npmrc, saved git credentials, any other dot entry not on the allowlist, and the Hermes home itself. Masked: ssh-agent, gpg-agent, keyring and D-Bus sockets, plus the docker socket. Still reachable: the rest of the host filesystem for reading, other Unix sockets if a command knows their path, and the full internet under the network profile.

There is no seccomp filter and no cgroup cap, so treat it as a file and process boundary.

Allow a tool's config with home_allow; it appears read-only, and credential stores stay hidden even if you list them.

🔥 Want a second opinion on your Agent OS server?

Book a free SEO strategy session and my team will look at how your agents are set up and where the sandbox fits.

→ Book a free SEO strategy session

A Short Routine For Agency Work

1. Create one folder per client under /srv/clients.
2. Point terminal.cwd at the client you are working on.
3. Run Prompt 2 on any new script before it goes near client files.
4. Use workspace for reports, network only when installs are needed.
5. Review changed files yourself; for any client email the agent drafts, write "draft only" into the job and send it yourself.

For more add-ons to pair with this, see the guide to the best Hermes Agent plugins.

Three Small-Business Set-Ups, With Approvals Still On

• A bookkeeping practice keeps client exports on an office Linux PC. The Agent OS points terminal.cwd at one client folder, runs on workspace, and writes month-end summaries beside the files, with no internet and no sight of saved logins.
• A local estate agency has its Agent OS draft listing write-ups into a folder of property notes. restricted lets it read the notes; workspace lets it save the drafts. A person checks every draft before it goes anywhere.
• A small marketing agency runs client site builds on a shared server. Each build gets its own working folder on the network profile with memory at 2048 MB, so one client's job cannot rewrite another client's files.

In all three, the sandbox draws the line, and a person still makes the final call.

Approvals stay on

The README says Hermes keeps its dangerous-command approval on this backend exactly as for local, hardline floor included.

That differs from docker, modal, daytona and vercel_sandbox, which skip the check according to the security guide.

Bubblewrap shipped among the new official plugins in the v0.23.0 Hearth Release.

FAQ

How do I check the sandbox is working in my Agent OS?

Ask the agent to list ~/.ssh, write outside the working folder and write inside it. The first two should fail and the last should succeed.

Which profile should a cron job use?

Use workspace for jobs that only handle local files. It is writable but has loopback-only networking.

Why does my build exit with code 137?

The 30-second CPU cap killed it. Raise cpu_seconds in the bubblewrap settings.

Can the agent run a preview server in the sandbox?

No. Background processes die when their command ends, and the agent is told they are unavailable on this backend.

Final word on Hermes Agent Bubblewrap

Run the quick start, paste Prompt 1 to prove the fence holds, then book a free SEO strategy session or join the AI Profit Boardroom when you want help building your routine around Hermes Agent bubblewrap.

Related guides on agentos.guide

→ Hermes Agent Hooks: Add Guardrails, Turn Blocks And Dashboard Events To Your Agent OS With Five Copy-Paste Prompts

→ Hermes Agent Inbox: A Morning Check-In For Your Agent OS

→ Hermes Agent Cron Job: Schedule, Stop And Recover Jobs In Your Agent OS With 5 Copy-Paste Prompts

→ Hermes Agent For Business: Start With One Job, Then Grow It With Five Copy-Paste Prompts In Your Agent OS

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

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

← all guides on agentos.guide