An AI agent filesystem sandbox limits which files the agent’s tools or subprocesses can reach. macOS lets users control app access to specific locations; Linux’s bubblewrap builds a filesystem view from explicit options. Those controls address file access, not every part of an agent’s security.
Treat a sandbox as a boundary around specific access, not as a blanket security guarantee.
What does a filesystem sandbox restrict?
It restricts the paths a process can access. That matters when an agent can read or change files on the machine running it: limiting its visible workspace can keep other locations outside that boundary.
macOS location permissions and Linux filesystem namespaces use different mechanisms, so their controls should be understood on their own terms.
How does macOS control access to files?
Apple says users can choose which apps and websites may access files in specific locations, including Desktop, Downloads, and Documents. That gives you a way to manage access to those locations for individual apps and websites. Apple’s guide to file and folder access
How does Linux bubblewrap build a filesystem sandbox?
bubblewrap creates a new filesystem namespace with an initially empty root. Command-line options then assemble the filesystem visible to the command. Debian’s bubblewrap manual
A sample command for an agent lists read-only mounts for /usr, /lib, and /lib64, a read-write mount of the current directory, mounts for /dev and /proc, and a new PID namespace. It also invokes /bin/sh without listing a mount that supplies that path. The command therefore does not establish that the shell is available inside the namespace or that the setup is complete.
For unprivileged use, Debian says a user namespace is required. The manual’s --unshare-user option addresses that namespace boundary; it is distinct from assembling the filesystem itself.
| Platform | Mechanism | Documented scope |
| macOS | Files and Folders access controls | Lets users choose which apps and websites may access specific locations, including Desktop, Downloads, and Documents. |
| Linux | bubblewrap filesystem namespace | Starts with an empty filesystem namespace, which command-line options populate. |
Does a filesystem sandbox also isolate network access?
No. Network isolation is a separate boundary. Debian documents --unshare-net as the option for creating a network namespace; the sample command does not include it, so it does not establish network isolation.
Keep API tokens outside the project directory an agent scans, and separate test SSH keys, Git accounts, and work directories. That reduces how much sensitive access sits alongside the files an agent needs to handle.
Why is a sandbox only one part of agent security?
A sandbox’s protection depends on its boundaries, and it cannot control what happens to files later run outside it. In his commentary, Zack Korman discusses flawed implementations, sandboxes that retain access to too much private data, and unsafe artifacts executed after leaving the sandbox.