Claude Code sandbox: how to isolate it on a Mac (and when to use a VM)
The Claude Code sandbox is a fence that macOS itself enforces around the shell commands Claude runs. It is off until you turn it on with /sandbox. It fences commands only, so the rest of Claude Code runs outside it, and Anthropic says it reduces risk without being a complete isolation boundary. For runs without prompts, Anthropic's docs say to use containers, VMs or dev containers without internet access.
This page covers the Claude Code sandbox on a Mac. It shows what the fence limits and what it leaves open. It also shows how to check that it works, and when a container or VM is the better place to run the agent.
01What the Claude Code sandbox does
A sandbox is a fenced area. A program inside it can touch only what the fence allows, even if it wants more. This fence is built by the operating system, not by Claude, so it holds whatever the model decided to run. On a Mac it uses Seatbelt, a macOS feature that lets the system restrict what a process can touch.
It applies to the shell commands Claude runs, including Bash, PowerShell and Monitor. That is different from the permission prompts in Claude Code permissions. A permission asks you before an action. The fence limits what an approved action can reach.
02Turn it on and check that it works
Start a session and run this command.
/sandboxYou can also set it in a settings file such as ~/.claude/settings.json.
{
"sandbox": {
"enabled": true
}
}The /sandbox panel then asks you to pick a mode. In auto-allow mode, Claude Code approves a command automatically, with no prompt, when the command runs inside the fence. The other mode keeps the usual permission prompts. Auto-allow means fewer questions for you.
To see the fence work, ask Claude to run touch ~/sandbox-probe. That tries to write a file in your home folder, outside the project. On macOS you should see "Operation not permitted".
03What commands can touch by default
Reading is wide open and writing is narrow.
| Area | Default |
|---|---|
| Writing files | The current working directory and its subdirectories, a per-user temp folder, and folders you've added |
| Reading files | The entire computer, except certain denied directories |
| Credential files | Still readable by default |
| Environment variables | Inherited from Claude Code, including any secrets in them |
Config files such as .zshrc, .gitconfig, hooks inside .git | Protected from writes in your working directory |
Two rows matter most. A command inside the fence can still read an SSH key or a token file unless you deny it. The secrets in Claude's own environment travel with it. Start Claude Code in the project folder, not in your home folder, so the area it can write to stays small.
The protected-config row has a reason. A command that could edit those files could grant itself permissions, or add a hook or MCP server that Claude Code runs outside the fence. A hook is a script of yours that runs around tool calls. An MCP server is a helper program that gives Claude extra tools.
04The network limit
The file rules are half of it. Effective sandboxing needs both filesystem and network isolation, because without the network side a compromised agent could send out sensitive files such as SSH keys. Sending data out of your machine like that is called exfiltration.
The network side works through a proxy on your machine. It checks each host against your list of allowed domains, and that list starts empty. An allowlist is simply a list of what is permitted; everything else is refused.
Be careful what you add. Broad domains such as github.com can create paths for data to leave. The built-in proxy also does not inspect encrypted traffic by default, so the contents of those connections are not examined.
05What runs outside the sandbox
Here is the surprise for most people. The fence covers shell commands only. Claude's file tools, MCP servers and hooks run outside it. So an edit Claude makes with its own file tool is not checked by the fence at all.
To fence those too, put the whole Claude Code process in a dev container with its firewall script. A dev container is a container your editor opens your project in. The setup is on Claude Code devcontainer.
06Ways a command gets out
The fence has doors, and it helps to know them.
- The retry. When a command fails inside it, Claude analyzes the failure and may retry it with a parameter called
dangerouslyDisableSandbox. This is the escape hatch. - The
!prompt. A command you type at the!shell-mode prompt runs unsandboxed in most sessions. - The silent fallback. If your platform does not support the sandbox, or the startup check fails, Claude Code runs commands without it by default. A setting named
failIfUnavailablechanges that. - Apple Events. They are blocked by default on macOS. Turning on
allowAppleEventsremoves code-execution isolation, because commands can then launch other applications unsandboxed with no prompt.
Escapes have been fixed before, for example CVE-2026-55607. The advisories are listed on Claude Code security. Keep Claude Code updated.
07Which fence to pick
Three common wishes, three answers.
| What you want | Use |
|---|---|
| Fewer prompts on your own Mac | The built-in sandbox in auto-allow mode |
| MCP servers, hooks and file tools fenced too | A dev container with firewall |
| No prompts at all | A container or a VM |
A container is a lightweight isolated environment for running programs. A VM, or virtual machine, is a whole separate computer simulated inside yours. For the no-prompt flag, see dangerously-skip-permissions. For a container you start yourself, see Claude Code in Docker.
Even inside a container, keep your own keys out of it. Anthropic's docs say not to mount host secrets such as ~/.ssh or cloud credential files into one, and to prefer repository-scoped or short-lived tokens.
08Can you run Claude Code in a VM, on a VPS or remotely?
You can run Claude Code in a VM, and a VM is one of the places named for the no-prompt mode. A VPS is a rented virtual machine in a data center, so the same rule holds. Put only what the task needs on it. Keep your own SSH keys and cloud credentials off it.
For remote work, a dev container can run locally or remotely, in a private or public cloud. With Claude Code installed in it, the commands run inside the container, not on your host machine. Edits to your project files still appear in your local repository. The same container is how you use Claude Code in Visual Studio Code, and the steps are on the devcontainer page.
09Should you rely on the Claude Code sandbox?
Use the Claude Code sandbox to cut prompts on a Mac you work on, and treat it as one layer. It does not protect credential files from reading by default, it leaves MCP servers and hooks outside, and it reduces risk without being complete isolation. For the no-prompt flag, use a container or VM.
The other agents work differently. See Codex sandbox, Cursor sandbox and the side-by-side sandbox for an AI agent comparison.
A sandbox limits what a command can touch; it doesn't show what already ran. The sandbox leaves file tools, MCP servers and hooks outside; Artificial Immunity's free, open-source core watches Claude Code sessions, MCP servers and program starts on your Mac and reports what it finds.
FAQ
Is the Claude Code sandbox on by default?
No. The sandbox is off by default. You turn it on with /sandbox inside a session, or with sandbox.enabled set to true in a settings file.
Can I run Claude Code in a VM or on a VPS?
Yes. A VM is one of the places Anthropic's docs name for the no-prompt mode, and a VPS is a rented virtual machine. Keep your own SSH keys and cloud credentials off that machine.
Is there a way to run Claude Code remotely?
Yes. A dev container can run locally or remotely, in a private or public cloud. The commands Claude runs then execute inside that container, not on your laptop.
How do I run Claude Code in Visual Studio Code?
Open your folder in a dev container with the VS Code Dev Containers extension and install Claude Code inside it. The steps are on the devcontainer page.
Does the sandbox stop Claude from reading my SSH keys?
Not by default. The default read rule covers the whole computer except some denied directories, and it still allows credential files, so you must protect those yourself.
Is the Claude Code sandbox a complete isolation boundary?
No. Anthropic's docs say sandboxing reduces risk but is not a complete isolation boundary.