
How to Sandbox AI Coding Agents with Bubblewrap (bwrap) on Linux
Isolate Agent Commands Without Exposing the Host
An autonomous coding agent can run untrusted terminal commands. If it sees your home directory, environment variables, network, and project write access, a single tool call can read secrets or damage work. On Linux, Bubblewrap (bwrap) offers a lightweight way to build a restricted namespace for a subprocess.
But a sandbox is only as strict as its mounts and namespace flags. A command that includes --unshare-all --share-net does not block the network: the latter flag restores the original network namespace. See the official Bubblewrap option reference.
Security review updated November 13, 2026: An earlier runnable example lacked a convincing file-aliasing and process-ownership security boundary. It was withdrawn. The discussion below shows filesystem aliasing through a safe synthetic example and documents remaining threats; it does not claim that a specific Bubblewrap escape was proven on our host.
Threat Model and Boundaries
The table below describes proposed requirements for a future isolated runner, not behavior demonstrated by an executable sandbox configuration in this article. Each mount, namespace and resource boundary must be explicitly implemented and verified on the target Linux host.
| Resource | Proposed behavior (not implemented here) | What it does not guarantee |
|---|---|---|
| Project source tree | Mounted read-only as /workspace |
Other writable aliases can still change the same files; mounted files and accessible sockets can still be read or used |
| Temporary working files | Writable scratch dir /scratch |
Scratch files appear on the host; do not put secrets there |
| Network | Fresh network namespace via --unshare-net |
Not a substitute for host egress policy or application-level controls |
| Environment variables | Replaced with a minimal env -i environment |
Any secrets explicitly passed in arguments remain visible to the process |
| Host home directory | Not mounted; private temporary /home |
Other bind mounts still matter; audit them carefully |
| CPU and memory | Not capped by Bubblewrap alone | Use cgroups/timeouts from a supervisor for resource limits |
Unprivileged user namespaces may be restricted by the Linux distribution, kernel settings, or AppArmor policy. If bwrap fails to create them, stop rather than disabling isolation flags just to make the command run.
Why the old runner was removed
An older example accepted a project directory and a writable scratch directory but did not establish a secure underlying file-object boundary. If a writable host path is nested inside a read-only project mount, the same host file can be accessible by a second, writable path. Changing one mount alias to read-only does not establish that every other alias is also read-only. The former executable runner was withdrawn, and this article does not distribute a replacement.
Even non-nested host paths may reference the same data. The official Linux link(2) manual documents hard links to a common inode. A link created in a writable scratch tree can refer to the same regular file as a different name in a project tree. A path-prefix guard that only compares directory names does not detect this case. That is a filesystem property, not evidence that a specific Bubblewrap exploit was observed.
Reproduce the hard-link alias without running a sandbox
The following disposable Python fixture uses two temporary directories and one fixed tiny file. It does not invoke bwrap, change a real project or access privileged host resources:
from pathlib import Path
from tempfile import TemporaryDirectory
import os
with TemporaryDirectory(prefix="bwrap-hardlink-example-") as tmp:
root = Path(tmp)
project = root / "project"
scratch = root / "scratch"
project.mkdir()
scratch.mkdir()
source = project / "example.txt"
alias = scratch / "alias.txt"
source.write_text("original", encoding="utf-8")
os.link(source, alias) # Two names for one regular file on this filesystem
alias.write_text("changed", encoding="utf-8")
assert source.read_text(encoding="utf-8") == "changed"
assert source.stat().st_ino == alias.stat().st_ino
print("synthetic hard-link alias observed")
This fixture can demonstrate hard-link aliasing when the test filesystem supports hard links. It does not reproduce Bubblewrap namespace isolation, demonstrate escape from correctly configured mounts, or prove a vulnerability in a particular version. Filesystem policy, mount ordering, bind mounts, and file-descriptor inheritance must be reviewed independently before running untrusted code.
A private temporary filesystem such as --tmpfs /scratch is one potential design building block if scratch output need not persist, but it does not establish total containment by itself. Any exported outputs require a separate, permission-checked boundary and a race-resistant design.
Network namespaces and Unix sockets
An isolated network namespace and read-only project mount should not be treated as a complete Unix-socket access policy. The Linux unix(7) documentation explains pathname Unix-domain sockets and their filesystem permissions. If a host service socket is intentionally bind-mounted and accessible inside a sandbox, its effective connection permissions must be checked, rather than assuming that TCP network isolation makes the host service inaccessible.
This article does not supply an independently verifiable recording of the previously described sandboxed Unix-socket connection or TCP failure. Those assertions are therefore not being used as proof. Consult the Bubblewrap namespace option reference and evaluate a disposable host-socket test with the actual kernel policy and approved service before relying on it.
Checks for a replacement
Before running untrusted commands, define which files, sockets, host services, outputs, network routes, and resources the process may access. A read-only project is still readable. Environment variables are not the only possible source of secrets: mounted files, arguments, inherited descriptors, and exposed services also matter.
Use disposable data to test direct writes, equal and nested paths, hard-link and mount aliases, accessible sockets, and the routes relevant to your environment. Record the kernel and Bubblewrap versions and repeat the checks on the target host. Account for setup races, output export, timeouts, and resource limits. If namespace creation fails, investigate rather than removing isolation flags to make a command run. A path guard or a successful individual test is not a complete security review.
Choose isolation by what can be proven
Bubblewrap uses Linux namespaces and configurable mounts, as its official option reference documents. This is useful when designing a restricted execution environment, but it does not automatically set cgroup limits, sanitize every inherited descriptor, remove host Unix sockets, or make a writable mount alias safe.
Other approaches such as containers, user-space kernel interception and microVMs have different and configuration-dependent boundaries. This article intentionally does not rank them or assert a particular Docker, Firecracker or gVisor security guarantee without corresponding source and environment evidence. For a real comparison, identify and test filesystem mounts, host service access, kernel/syscall exposure, network routes, credentials, cgroup limits, measured startup time and the ability to escape through provided interfaces.
A boot-time target from a microVM project is not a verified end-to-end startup time for an arbitrary agent workload. We have not run comparative container/Bubblewrap/microVM startup or sandbox-escape benchmarks.
Primary sources and limitations
- Bubblewrap project and user namespaces
- Bubblewrap documented namespace options
- Linux user namespaces
Source and synthetic-fixture review: 2026-11-13. This article does not attest prior Bubblewrap benchmark or penetration-test results. Production use requires a threat model and independent, target-host sandbox verification.