This guide shows you how to run AI agents inside OS-level sandboxes—like macOS App Sandbox, Windows Sandbox, or Linux’s firejail—without using Docker or other container runtimes. You’ll get isolation for untrusted code, file system restrictions, and network controls, all using built-in OS features or lightweight tools. No container daemon, no images, no orchestration.
What You’ll Need
- A Unix-like OS (Linux, macOS) or Windows 10/11 Pro/Enterprise (for Windows Sandbox).
- Administrator/root access to install sandboxing tools (firejail on Linux, or enable Windows Sandbox feature).
- Basic command-line familiarity.
- For macOS, a developer account is not required, but you’ll need to enable App Sandbox in your project.
Step-by-Step
On Linux (using firejail)
- Install firejail: On Debian/Ubuntu:
sudo apt install firejail. On Fedora:sudo dnf install firejail. On Arch:sudo pacman -S firejail. - Create a profile for your agent: Firejail uses profiles to define restrictions. Create a custom profile file, e.g.,
~/.config/firejail/agent.profile. Start with a basic template:include /etc/firejail/default.profilethen add restrictions likenet none(disable network) ornetfilterto allow specific ports. - Run your agent inside the sandbox: Use
firejail --profile=agent.profile python my_agent.py. Replace with your actual command. Firejail will confine the process to a new mount namespace, hide the rest of the file system, and apply network restrictions. - Test the sandbox: Inside the sandbox, try to read a sensitive file like
/etc/shadowor access the internet (if disabled). You should get a permission denied error or a network failure. - Optional: Add a dedicated user: Create a low-privilege user for the agent:
sudo useradd -m agentuser. Then run the agent as that user:firejail --profile=agent.profile sudo -u agentuser python my_agent.py(or better, usesuorrunuser). This adds OS-level user isolation on top of firejail.
On macOS (using App Sandbox)
- Enable App Sandbox in your Xcode project: If you’re developing a macOS app that embeds an AI agent, open your project in Xcode, go to the target’s “Signing & Capabilities” tab, and click “+ Capability” then select “App Sandbox”.
- Configure sandbox entitlements: In the entitlements file, set the sandbox to
YES. Then specify which resources the agent can access. For example, setcom.apple.security.network.clienttoYESif the agent needs to make outbound network calls, or leave it off for offline operation. - Restrict file access: By default, the sandbox gives the app read-only access to the user’s home directory. To give your agent write access to a specific folder, add a security-scoped bookmark or use the
com.apple.security.files.user-selected.read-writeentitlement and prompt the user to select a folder. - Run your agent as a sandboxed process: When you build and run your app, the agent code runs inside the sandbox. If you’re running a script directly, you can use
sandbox-execwith a profile file, but that’s deprecated; better to wrap it in a small Swift app that uses the Sandbox API. - Test the sandbox: Try to write to a location outside the allowed folders. The OS will deny the write and log an error in the console.
On Windows (using Windows Sandbox)
- Enable Windows Sandbox: Open Control Panel > Programs > Turn Windows features on or off. Check “Windows Sandbox” and click OK. Restart if prompted.
- Launch Windows Sandbox: Search for “Windows Sandbox” in the Start menu and open it. This launches a fresh, isolated Windows environment with its own kernel, file system, and network stack. It’s a lightweight VM that uses the host’s kernel, so it’s not a container but a full OS sandbox.
- Copy your agent code into the sandbox: You can copy files from the host into the sandbox by pasting them into the sandbox window (shared clipboard). For larger projects, create a shared folder by editing the .wsb configuration file (see next step).
- Create a .wsb configuration file (optional): Write a text file with extension .wsb, e.g.,
agent.wsb, with content like this:<Configuration> <MappedFolders> <MappedFolder> <HostFolder>C:\myagent</HostFolder> <ReadOnly>true</ReadOnly> </MappedFolder> </MappedFolders> <Networking>Disable</Networking> </Configuration>This maps your agent folder into the sandbox as read-only and disables networking. Double-click the .wsb file to launch the sandbox with these settings.
- Run your agent inside the sandbox: Open a command prompt in the sandbox and run your agent script. The sandbox is isolated from the host, so any damage is contained.
- Close the sandbox: When done, just close the window. All changes are discarded; the sandbox is reset to a clean state every time.
Common Mistakes
- Forgetting to restrict network access: Many agents need to download models or call APIs, but if you leave network unrestricted, the sandbox offers little protection against data exfiltration. Always disable network unless absolutely needed.
- Using a shared home directory: On Linux, if you don’t set a private home, firejail may still allow read access to your real home. Use
privateorprivate-hometo isolate. - Not testing the sandbox: After setting up, always test with a malicious command like
cat /etc/passwdorrm -rf /(in a test environment) to verify restrictions work. - On Windows, running the agent as admin inside the sandbox: Even inside Windows Sandbox, running as admin gives the agent full control within that sandbox. It’s still isolated from the host, but it can do anything inside the sandbox. Use a standard user account inside the sandbox for better control.
- Ignoring seccomp on Linux: Firejail alone doesn’t restrict system calls. For deeper protection, combine with seccomp profiles (e.g.,
seccompin firejail profile) to block dangerous syscalls.
Tips
- Combine OS-level sandbox with a dedicated user: On Linux, running the agent as a non-root user adds a second layer of isolation. Even if firejail is bypassed, the user account limits damage.
- Use read-only file systems: Mount the agent’s working directory as read-only if the agent only needs to read data. This prevents it from modifying its own code.
- Set resource limits: Use
rlimitin firejail to limit CPU and memory usage. This prevents a runaway agent from consuming all system resources. - Log everything: Redirect the agent’s output to a log file outside the sandbox. This helps debug issues and audit actions.
- On macOS, use the sandbox’s built-in network filter: The App Sandbox allows you to specify which domains the agent can connect to via the
com.apple.security.network.cliententitlement. Use it to whitelist only the necessary endpoints.
Troubleshooting
- Agent cannot write to a file: Check the sandbox’s file access rules. On Linux, ensure the directory is within the private home or explicitly allowed. On macOS, check the entitlements for the folder. On Windows, ensure the folder is mapped and not read-only.
- Network requests fail: If you disabled networking, that’s expected. If you enabled it but still fail, check your firewall rules. On Linux, firejail’s netfilter may block ports; allow them in the profile. On Windows, ensure the sandbox has network access (or disable it if you intended to block).
- Firejail command not found: Ensure firejail is installed and in your PATH. On some distros, it’s installed to
/usr/bin/firejail, but you may need to runsudo firejailfor some operations. - Windows Sandbox won’t start: Check that your CPU supports virtualization and that it’s enabled in BIOS. Also, ensure you have at least 4GB of RAM and 1GB of free disk space. If it still fails, check the Windows Event Viewer for errors.
- macOS sandbox-exec is deprecated: If you’re using
sandbox-execand getting warnings, switch to using the App Sandbox API in a proper Xcode project. The command-line tool still works but may be removed in future macOS versions. - Agent still sees the host file system: On Linux, if you didn’t use
privateorprivate-home, firejail gives read-only access to the entire file system by default. That’s not enough for sensitive data. Addprivateto the profile to hide everything except the current directory.
Frequently Asked Questions
Can I run multiple agents in separate sandboxes?
Yes. On Linux, each firejail invocation creates a separate sandbox. On Windows, you can run multiple Windows Sandbox instances, but they are resource-heavy. On macOS, each app process has its own sandbox context.
Is this as secure as containers?
OS-level sandboxes are generally lighter but may not provide the same isolation as a full container (which uses kernel namespaces and cgroups). However, for many AI agent workloads, they are sufficient. For high-risk tasks, consider adding additional layers like a dedicated VM.
Can I use these sandboxes for cloud AI agents?
These are local OS features. For cloud, you’d typically use cloud-native sandboxing or container services. But you can apply the same principles on a cloud VM.
How do I give the agent access to a specific folder?
On Linux, use --bind or --private-home in firejail. On macOS, use security-scoped bookmarks. On Windows, map a folder in the .wsb file.
Can I limit the agent’s CPU and memory?
Yes. On Linux, use rlimit in firejail. On Windows, you can set process priority and affinity, but not hard limits without extra tools. On macOS, use setrlimit in your app code.
What if my agent needs to use a GPU?
OS-level sandboxes typically allow GPU access by default, but this can be a security risk. On Linux, you can use --no3d to disable GPU. On Windows, the sandbox has its own virtual GPU. On macOS, the sandbox restricts GPU access to the app’s own processes.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- AI for Playwright Locators: Draft, Verify, and Refine
- How to Fact-Check Artificial Intelligence Claims
- Sony Bravia 3 II vs Hisense U6SF Pro: Which to Buy?
- Best Fire Emblem Games Without Monastery Grind
- Are AI Agents Safe for Private Information?
- Best MMORPG Games: Top Picks for Every Play Style