How to Sandbox AI Coding Agents on macOS Safely

What a coding agent sandbox has to do

A coding agent is a program that reads files, edits files and runs shell commands for you. It starts with your user account, so macOS treats its actions as yours. It can read your SSH keys, your cloud credentials and every repository you own, unless something stops it.

A sandbox is that something. It is a limit the operating system enforces on a process and on everything the process starts. The agent cannot negotiate with it, forget it or be talked out of it. That is the difference between a sandbox and a rule in a prompt.

A useful sandbox answers three questions. Where can the agent write? What can it read? Where can it connect? Most failures come from answering only the first one.

• Writes: confine them to the project folder and a temp directory.
• Reads: keep home-folder secrets such as ~/.ssh and ~/.aws out of view.
• Network: decide which hosts a command may reach, if any.

Option 1: use the sandbox your agent already has

The cheapest start is the sandbox that ships with the agent. On macOS, both Claude Code and Codex build theirs on Seatbelt, the sandbox framework that is part of macOS.

In Claude Code the Bash sandbox is off by default. You turn it on by running /sandbox in a session. Once on, commands can write to the working directory and a per-user temp directory, and their network traffic goes through a proxy that checks each host against an allowed list that starts empty. The documentation is clear about the edges: the sandbox covers shell commands only, so Claude's file tools, MCP servers and hooks run outside it. It also offers an unsandboxed retry for commands that fail inside the boundary, which you can switch off.

Codex describes three modes on macOS: read-only, workspace-write and danger-full-access, and says the sandbox works out of the box with Seatbelt. Its tools, such as git, package managers and test runners, run under the same limits.

Pi, a minimal coding agent, takes the other road. Its site says it has no permission popups and tells you to run it in a container or to build your own confirmation flow. Community extensions add sandboxing, but out of the box you are the sandbox.

• Claude Code: run /sandbox to switch it on. It is off by default.
• Codex: pick workspace-write for everyday work, and avoid danger-full-access.
• Pi: nothing built in, so add a container or an OS-level wrapper yourself.
• Check the edges: file tools and MCP servers may sit outside the boundary.

Option 2: wrap any agent in a Seatbelt profile

If your agent has no sandbox, you can apply Seatbelt yourself with sandbox-exec, the command line tool that ships with macOS. You write a profile that says what is allowed, then launch the agent through it. Everything the agent starts inherits the limits.

One caveat you should know about. The sandbox-exec man page marks the tool as deprecated, a label it has carried since OS X 10.12. In practice it still works on current macOS releases and many tools rely on it, including Claude Code and Codex, but you are building on something Apple does not promise to keep. Check man sandbox-exec on your own Mac.

The cost is effort. A profile that blocks too much breaks your build tools, and one that blocks too little protects nothing. You tune it by running the agent and reading the denials.

• Start from deny-by-default, then allow the project folder for writes.
• Allow reads of system paths and your toolchain, and nothing under ~/.ssh.
• Expect to iterate. Package managers and compilers touch many paths.

Option 3: run the agent in a VM or container

A virtual machine puts the agent behind a much harder wall than a process sandbox. Apple's open source container tool runs each Linux container in its own lightweight virtual machine. It needs Apple silicon and macOS 15 or later, and full networking support arrived with macOS 26. Docker Desktop and OrbStack run containers inside one shared Linux VM instead, which is weaker, because every container on the machine shares that one VM.

The trade-off is friction. The agent now works on Linux, not on your Mac. Anything that needs Xcode, the macOS keychain or a GUI is out of reach, and you have to mount your project in. Mount it read-write only when you must, and expect file access to cost some speed.

A container is not magic either. Docker Desktop had a critical flaw, CVE-2025-9074, where its internal Docker Engine API was reachable from inside any container without authentication, so a container could reach the host with no separate escape bug needed. It was fixed in version 4.44.3. Keep the tool updated, and do not mount the Docker socket into an agent's container.

• Apple's container tool: one lightweight VM per container, needs Apple silicon and macOS 15 or later.
• Docker Desktop and OrbStack: containers share one Linux VM.
• Mount only the project, and mount it read-only when you can.
• Containers have network access by default, so set it deliberately.

Option 4: lock the agent to its folders with Forkbench

Forkbench takes a different approach on the Mac: your coding agents run in real terminals, not a container somewhere else. It can lock a Thread to its folders using the macOS kernel sandbox, so ~/.ssh, other repositories and Documents stay shut. It works with any agent you run in its terminals, including ones with no sandbox of their own.

Secrets are handled separately. The Vault keeps keys in your Keychain and lets a command use one by name, without the value reaching the prompt, the command line or the transcript.

Know the limits. The folder lock is opt-in. It does not restrict the network, so a locked agent can still send out what it is allowed to read. Without the lock, an agent has the filesystem access you have. An unpinned Vault key can still be read by the program that was run with it. Forkbench governs what the agent holds and the folders you lock, not your whole machine.

• Folder lock: opt-in, applied by the macOS kernel sandbox.
• Vault: keys stay in the Keychain and are used without being shown.
• Not covered: network access, and the rest of the machine outside the lock.

A setup you can finish today

Pick the strongest boundary you can live with, then layer the rest. A VM for risky or unfamiliar code, a Seatbelt-based sandbox for daily work, and a clean home folder underneath.

None of this replaces judgment. A sandbox limits damage. It does not tell you whether the agent's change is correct, so keep reviewing diffs before you merge.

• Turn on your agent's sandbox, or add one if it has none.
• Confine writes to the project and a temp folder.
• Keep production credentials out of any session where an agent is experimenting.
• Move keys out of .env files and into the Keychain or a secrets manager.
• Test the boundary: have a command try to write a file in your home folder and confirm it fails.
• Set network access on purpose, with an allowed list if the tool supports one.