Back to Explore
GuideVibeFix editorialUpdated Nov 21, 2026

Stop letting your agent roam your real machine: add a sandbox to vibe coding

"Don't touch anything else" in a prompt is not a system rule — a sandbox is. This guide covers the sandboxes in Claude Code and Codex: how to configure the two isolation layers, three locks for credentials, five things the sandbox does not govern, and three configuration templates.

A silver padlock and a brass padlock locking a black metal mesh gate

Let me draw the boundary first. This site already has three guides about keeping an agent under control, but none of them is about this. The Agent hooks guide is about checks while the work happens: before the agent acts, a hook steps in and looks. The Agent permission contract guide is about the agreement — what it may touch, what it may not, which directories it can read, which commands need your say. And the credential management guide is about not handing your keys to the AI. This one is about a harder layer than any agreement: isolation at the operating-system level. An agreement is a rule written in a prompt or a configuration file, which the agent is supposed to follow; a sandbox is a line the operating system draws around a process, which the agent cannot cross even if it tries — a command that touches the line is refused by the system outright. Hooks and permission contracts govern what the agent should do; the sandbox governs what it can do. Also, the guest trial sandbox guide is about a trial sandbox inside a product, for users; this one is about a sandbox on your development machine for a coding agent — a different thing.

The "Squirrel Ledger" project used below is a fictional practice project: a personal finance app one person built with AI help, which records spending and produces a monthly report. Every operation, command, and error message shown with it is invented to explain how things work; it is not a real record. Every sandbox rule, setting, and default for Claude Code and Codex comes from the two products' official documentation, listed at the end.

Why "don't touch anything else" in the prompt is not enough

Start with the symptom. You ask the agent to add a feature to Squirrel Ledger: a monthly report. While it works, it runs commands: installing dependencies, running tests, starting a local server. You write in the prompt, "only change files inside the project, don't touch anything else," and it agrees cheerfully. The problem is that "don't touch anything else" is a sentence in human language, not a system rule. The agent builds the commands it runs itself; a command it assembles can carry a path it did not notice, call a script it thinks is harmless but actually changes a system file, or be steered by a malicious instruction it read somewhere — prompt injection has its own defense guide on this site, and that guide admits the defense does not catch one hundred percent. As long as the boundary of a command rests on "the model behaves itself," your whole computer is still wide open.

The sandbox takes a different approach: instead of reasoning with the model, it has the operating system watch every command the model runs. Claude Code's official documentation states it in the first sentence: the sandbox is a boundary the operating system enforces around the shell commands Claude runs on your machine. You set which files and network domains those commands can reach; inside the boundary they run freely, outside it the system refuses them directly. Codex's official documentation says the same thing in its own words: the sandbox defines what is technically possible, and the approval policy decides when the agent must stop and ask you. Together those two sentences are the sandbox's job description: it is the floor, not the manners.

The floor fails differently. When a prompt fails, you find out afterwards: the file has already been changed, the key has already been read, and the log holds one line of "sorry, I shouldn't have done that." When a sandbox fails, you know on the spot: the command errors out with "Operation not permitted" or "Read-only file system" and nothing has happened. That is the failure you want: better that the work does not get done than that it gets done in the wrong place and you only notice later.

But a sandbox is not a cure-all, so here are its three limits before the real lesson starts, so you do not read the wrong guide. First, the sandbox governs shell commands, not everything an agent does — a whole section later lists what it does not govern. Second, the sandbox is off by default in both tools; you have to turn it on yourself. Third, the default boundary is looser than you think — with Claude Code's sandbox on, commands can still read almost your whole machine by default, including ~/.ssh and ~/.aws/credentials, and that does not stop until you lock it down yourself.

What a sandbox is: two layers, two switches

First the structure, so the pile of settings later does not confuse you. A sandbox is really two layers of isolation put together. The first layer is filesystem isolation: where commands can write and where they can read. The second layer is network isolation: which domains commands can reach. The two layers are independent; you can run one without the other — for example, keeping network isolation while dropping filesystem isolation, which is what Claude Code's filesystem.disabled setting does, covered later.

Outside the sandbox there is a second switch: approvals. Approvals do not control whether a command can run, only whether it must ask you first. Both tools keep the two switches separate: the sandbox decides "can it," approvals decide "does it ask." That distinction matters, because later you will see many combinations: sandbox on with approvals fully open, sandbox on with every command asking you, sandbox off with approvals still asking. Get the combination wrong and the mild result is a prompt for every command until you switch the sandbox off in frustration; the bad result is commands running naked outside the sandbox while you believe they are inside it.

On enforcement, both tools use the operating system's own mechanisms, not a check they wrote themselves. On macOS it is the built-in Seatbelt framework; on Linux and WSL2 it is bubblewrap plus seccomp; on Windows, Codex has its own MXC mechanism, while Claude Code has no sandbox at all on native Windows — the official docs say it plainly: to use the sandbox on a Windows machine, run Claude Code inside WSL2.

Claude Code: turn it on, set the boundary, verify it

Start with Claude Code. The sandbox is off by default, and there are three ways to turn it on: run the /sandbox command in a session, which opens a panel where you pick a mode; set sandbox.enabled to true in your user settings at ~/.claude/settings.json, which applies to all of your projects; or pass it for one session with --settings. Once you pick a mode in the panel, Claude Code saves the choice to the current project's .claude/settings.local.json, which applies to that project only. To enforce it for a whole team, use managed settings, which come up again in the strict-mode section below.

Once on, the default boundary looks like this. Writes: only the working directory, a per-user temp directory, and directories you have added. Some paths cannot be written even inside a writable directory (protected paths, such as the .claude settings files and .git hooks). Reads: almost the whole machine by default, including credential files such as ~/.ssh and ~/.aws/credentials — looser by default than you would expect, and not locked until you lock it. Network: no domain is allowed by default; a command's outbound connections go through a proxy on your machine that checks each host against your allowed domains, which start empty. Environment variables: commands inherit Claude Code's own environment, including any secrets in it.

On Linux and WSL2, install two packages before turning the sandbox on: bubblewrap and socat — the first enforces filesystem isolation, the second relays network traffic to the sandbox proxy. On Debian and Ubuntu it is one line: sudo apt-get install bubblewrap socat. Restart Claude Code afterwards and the panel will tell you what is still missing. On macOS nothing needs installing; Seatbelt is built into the system.

Once it is on, verify it — do not trust a panel that says "enabled." The official docs give a direct test: ask Claude to run two commands. The first is touch ~/sandbox-probe, which should fail inside the sandbox — "Operation not permitted" on macOS, "Read-only file system" on Linux and WSL2. The second is curl --noproxy '*' https://example.com, which should fail with "Could not resolve host," because the command has no route around the sandbox proxy. One trap: Claude has to run these commands. Typing them yourself after the ! prompt does not count — commands you type run outside the sandbox in most sessions. If touch actually succeeds, the sandbox is not working; delete the stray ~/sandbox-probe file, then go back to the /sandbox panel to find out why.

Which of the two modes? The filesystem and network restrictions are the same in both; the only difference is whether sandboxed commands need your approval. In auto-allow mode, a command that runs inside the sandbox is approved automatically, with no prompt; a command that runs outside the sandbox still goes through the regular permission flow. In regular permissions mode, every Bash command goes through the regular permission flow, even when sandboxed. When you start, pick regular permissions mode for a week: you will see what commands the agent actually runs, and once you know, switch to auto-allow. Before switching, read the next two sections on credential locks and escape hatches.

When the boundary is too tight, do not rush to take the command out of the sandbox — widen the allowlist first. If a tool needs to write to another directory, add the path with sandbox.filesystem.allowWrite; if it needs a domain, add it with network.allowedDomains; to block a domain, use network.deniedDomains. The official docs say plainly: whatever an allowlist entry can fix, do not fix with excludedCommands. One detail when adding paths: a relative path . means the project root in project settings, but ~/.claude in user settings — the same configuration means different things in the two places. On Linux there is another detail: an allowlist entry for a path that does not exist yet has no effect, so create the path first.

Codex: three sandbox modes, approvals as the other hand

Codex works on the same model as Claude Code, but its tiers are spelled out more plainly: three sandbox modes plus a separate approval policy. The three modes first. read-only: read files and run commands that do not write anything; changing things needs your approval first — right for reading unfamiliar code, reviewing, or chatting without changing anything. workspace-write: read, edit, and run commands inside the workspace, with network off by default — the default tier for everyday work. danger-full-access: no filesystem or network limits, and the official docs say in so many words to use it only in a "controlled environment" — one that is already inside a container or virtual machine, which is itself the isolation.

Codex also looks at your folder when it starts: a version-controlled folder gets a recommendation of Auto (workspace-write plus on-request approvals); a folder without version control gets read-only. To set it yourself, one line does it: codex --sandbox workspace-write --ask-for-approval on-request. Or write it into ~/.codex/config.toml: sandbox_mode = "workspace-write" and approval_policy = "on-request". To see which tier you are on right now, run /status in a session to see which directories are in the workspace; to switch tiers without changing the configuration, use the /permissions command.

Approvals are the other hand, and they mind their own business. on-request is the default: what the sandbox allows runs directly, and Codex stops to ask only when it needs to go beyond the sandbox boundary — editing outside the workspace, for example, or using the network. never means never ask: the command does its best within the sandbox limits, and what it cannot do it simply does not do — right for scripts and CI jobs nobody watches. There is also a finer granular approval policy: keep some prompt categories interactive while others are rejected automatically, for people who want precise control. One retired setting to watch for: approval_policy = "untrusted" is explicitly retired by the official docs, and leaving it in place can prevent the client from starting — delete it wherever you see it in a configuration file. To keep the effect of "untrusted project by default," the official replacement is to add trust_level = "untrusted" for that project in your user configuration, so commands require approval by default and the project's own configuration is disabled.

On the network side, Codex keeps it off by default; to turn it on you say so explicitly. Write network_access = true under [sandbox_workspace_write] and commands can reach the network. Turning it on is not enough on its own — the official docs also offer the network_proxy feature: once enabled, a command's outbound traffic passes through a proxy that enforces the domain rules you write. The rules are allowlist-first: an exact hostname allows only itself; *.example.com allows subdomains but not example.com itself; **.example.com allows both the apex and the subdomains; a global * allows every public host, and the official advice is to avoid it when you can. Deny always wins over allow — that rule is fixed. Three more things are locked by default: local and private destinations are blocked (allow_local_binding = false), and to reach one local target you write a separate rule with an exact IP literal or localhost — wildcards do not count; a hostname that resolves to a private address stays blocked even if it matches the allowlist; and the DNS rebinding check is best-effort only — the official wording is that it reduces the risk but does not eliminate it.

There are paths Codex protects by name: even inside a writable root in workspace-write mode, .git (including the real directory a gitdir pointer file resolves to), .agents, .codex, and .aws are read-only, and the protection is recursive. Those four are fixed in the sandbox; you do not configure them. Claude Code has similar protected paths; both tools share the same idea: inside the agent's workspace there are things that belong to the tool itself, and an agent's commands may not touch them no matter how free they are.

Finally, two danger lines, which the official docs mark "Elevated Risk, not recommended." The first is --dangerously-bypass-approvals-and-sandbox (shorthand --yolo): it switches off approvals and the sandbox together, so every command the model generates runs with your full user privileges — only inside an environment that is already hardened, such as a dedicated virtual machine you can throw away. The second is full access inside a devcontainer: when the container itself is the isolation boundary, you can run danger-full-access inside it, but the official warning is direct — a malicious project inside the container can steal anything available inside the container, including Codex's own credentials, so this pattern is only for repositories you trust.

Three locks for credentials: cannot read, cannot use, cannot see

Credentials are the part of the sandbox people underestimate most. As noted above, Claude Code's sandbox can read ~/.ssh and ~/.aws/credentials by default; on the Codex side the .aws directory has fixed protection, but other credential files — a token in ~/.config, a .env in the project — are outside that fixed protection. Credential protection is do-it-yourself work, in three locks, each tighter than the last.

The first lock is: cannot read. In Claude Code's sandbox.credentials you name files and environment variables with mode deny. A file listed there cannot be read by sandboxed commands; an environment variable listed there is removed from the environment before each sandboxed command runs. The usual three are: ~/.aws/credentials, the ~/.ssh directory, and the GITHUB_TOKEN and NPM_TOKEN environment variables. Note this: there is no built-in deny list — what you do not name, the sandbox does not protect. Codex follows the same idea in a different configuration file: first list your own credentials, then configure them.

The second lock is: cannot use, but the network still works. Some commands must reach the network to do their job, and reaching the network needs a key for authentication — a deny would cut the job off entirely. Claude Code's answer is mask: the command sees a per-session placeholder for the key, and the real value is substituted by the proxy only when the request goes to a host you allow. That way the command and its logs never hold the real credential, but the request still authenticates. Masking has two prerequisites: first, turn on network.tlsTerminate so the proxy terminates TLS itself and can see the request contents to substitute into; second, the hosts a masked credential may reach (injectHosts) must also be on the network.allowedDomains list, or the proxy will not substitute for them. AWS keys must be masked as a pair: mask AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY together, and the proxy detects the SigV4 signature and re-signs the request with the real values; mask only the secret and the signature will not match, so the request fails at AWS.

The third lock is understanding that "read" and "use" are two different things. A file's deny-read protection belongs to the filesystem isolation layer: if you set filesystem.disabled to true and switch filesystem isolation off, the file's deny-read protection goes away with it — but environment variable deny and mask entries are independent and keep working. So before switching filesystem isolation off, think about whether you are relying on it to protect credential files. The safer approach is: do not switch it off; add an allowWrite entry for whichever directory is missing.

One more trap: the narrower rule wins. Claude Code's docs give two examples: with denyRead on ~/ and allowRead on ~/projects, ~/projects is readable and the rest of the home directory is not; the other way round, with allowRead on ~/ and denyRead on ~/.env, ~/.env stays blocked. When writing rules, write the broad one first and the narrow exception after, and verify with a real command afterwards instead of trusting the configuration file at a glance.

Three-layer sandbox diagram: filesystem isolation, network isolation, and what sits outside the sandbox

What the sandbox does not govern: escape hatches and failure modes

The most dangerous way to use a sandbox is to believe it governs everything. This section lists what it does not govern, one item at a time, all written in black and white in the official docs.

First, the agent's own read and write tools are not in the sandbox. Claude Code's built-in tools — Read, Edit, Write, WebFetch — follow permission rules, not the sandbox: a denyRead entry in the sandbox configuration does not stop the Read tool from reading the same file, and allowedDomains does not limit WebFetch. Codex is the same: the sandbox governs commands, and tool calls have their own approvals. The sandbox wraps shell commands; when the agent reads a file directly through a tool instead of through the shell, it is not inside that wrapper.

Second, the processes the agent starts — MCP servers, hooks, plugins, LSP servers — run outside the sandbox with your full access. Claude Code's official docs list them all: command hooks, local MCP servers, plugin monitors, LSP servers, status line commands, apiKeyHelper. Mods are the same: a mod runs its own code inside Claude Code, so its file access, network requests, and programs started with $.process are not sandboxed. On the Codex side, MCP tool calls have their own approvals and annotations, and a tool call with a destructive annotation always requires approval — but that is approval, not a sandbox. The point is: the more powerful the MCP servers you connect for the agent, the bigger the hole outside the sandbox, so think first about whether a server deserves your full access.

Third, the escape hatch: the unsandboxed retry. When a command fails inside the sandbox, Claude Code analyzes the failure and may ask whether to retry it outside the sandbox. A retried command runs naked: no filesystem limits, no network proxy. Whether it needs your approval depends on your permission mode: in bypassPermissions mode it runs without asking; in manual mode and acceptEdits mode you get a prompt titled "Bash command (unsandboxed)"; in auto mode a classifier model evaluates the command first; in dontAsk mode the retry is refused. To close this hatch completely, set allowUnsandboxedCommands to false and add failIfUnavailable (refuse to start if the sandbox cannot start); the /sandbox panel calls this pair strict sandbox mode. One stronger move: add an ask rule for Bash(dangerouslyDisableSandbox:true), so a retry must ask you first in every mode — that rule takes precedence over any matching allow rule.

Fourth, excludedCommands is another hatch. List a command such as docker compose there and it runs outside the sandbox, with no filesystem restrictions and no network proxy. The official advice is: whatever an allowlist entry can fix, do not fix with this; use it only for a tool that cannot work inside the sandbox at all and that you trust with your full access. Watch the matching rules: docker matches only the bare word docker, while docker * matches docker with or without arguments; every command in a chained call has to match; a script or make target that calls docker internally does not match, because the match is against the text of the call itself.

Fifth, when the sandbox cannot start, the default is silent degradation. If the platform is not supported or bubblewrap is not installed, Claude Code carries on and runs commands unsandboxed, and the session looks exactly the same as usual — you will not notice unless you check. That is what failIfUnavailable is for: set it to true and Claude Code refuses to start instead of running naked. During your first week with the sandbox on, run the verification commands before finishing each day (touch ~/sandbox-probe should fail); confirming the sandbox is still alive beats writing a hundred rules.

One last line, in the spirit of Claude Code's official docs: to put the tools, processes, and commands behind a single boundary, run the Claude Code process itself inside a container, a virtual machine, or the sandbox runtime. A sandbox is a wall inside the process; a container or virtual machine is a wall outside the process. Stacked together, they are the state where the agent cannot leave the yard no matter what it does. The sandbox alone is enough for everyday development; for a repository of unknown origin or a whole project someone sent you, put a container around it before you start.

Three configuration templates and a checklist

Here is the whole guide as three templates — pick the one that matches your nerve. The first is the everyday development template: Claude Code with the sandbox on in regular permissions mode; Codex with the default Auto preset (workspace-write plus on-request). List your credentials as deny entries (~/.aws/credentials, ~/.ssh, GITHUB_TOKEN, NPM_TOKEN), and allowlist only the two or three domains you actually use (registry.npmjs.org and github.com, adding each as you need it). This template is for your own projects and code you know, and its goal is "few prompts, no accidents."

The second is the unfamiliar repository review template: Claude Code with the sandbox on in regular permissions mode, plus allowUnsandboxedCommands=false and failIfUnavailable=true; Codex with a read-only sandbox plus on-request approvals. In read-only mode the agent can read code and run commands that write nothing, and changing anything requires asking you. This template is for a repository you are opening for the first time, a project someone sent you, or a whole codebase downloaded from the internet.

The third is the unattended script template: Codex with a read-only sandbox plus never approvals, for CI jobs that only read and report; or a workspace-write sandbox plus never approvals, for a script you wrote yourself and will check the results of afterwards. never means approvals are off but the sandbox is still there, so commands can only move inside the boundary. Never put danger-full-access or --yolo in this template, unless the commands run inside a container or virtual machine you can throw away.

And the checklist. Before turning it on: confirm your platform has a sandbox (macOS, Linux, and WSL2 do; native Windows does not — use WSL2); on Linux, install bubblewrap and socat first. After turning it on: run the verification commands — touch ~/sandbox-probe should fail, and curl --noproxy '*' https://example.com should fail; failing is what proves the sandbox is alive. For credentials: list your own credentials, with files and environment variables as separate deny entries; use mask, not deny, for credentials needed to authenticate network requests. For the escape hatches: do not configure excludedCommands unless you need it; let retries ask you, and if the prompts annoy you, add an ask rule for Bash(dangerouslyDisableSandbox:true); refuse to start when the sandbox cannot start instead of running naked. One last rule: every time you connect an MCP server or install a plugin, ask yourself, "this thing runs outside the sandbox — do I trust it with my full access?" If not, do not connect it.

Sources: the official Claude Code documentation, "Configure the sandboxed Bash tool" (code.claude.com/docs/en/sandboxing, read 2026-11-17); the official Codex documentation, "Agent approvals & security" (learn.chatgpt.com/codex/agent-approvals-security, read 2026-11-17).

Views 7Comments 0

Comments (0)

ME
0/1000
Loading comments...

Sources

Browse projectsPublish your project

Related articles

Real photo: a woman in an office sticking colorful sticky notes in rows on a white wall, holding a pink note in her hand
Guide
Stop shimming with margins: Flexbox one-dimensional layout, explained plainly

Flexbox lays things out in one direction at a time, and when it is done right, the nav bar, the card wall, and the cart rows all behave. This guide follows MDN's Basic concepts of flexbox, Aligning items in a flex container, and Controlling ratios of flex items along the main axis: the two axes, containers and items, direction and wrapping, free space, the three flex properties, alignment on both axes, and gaps and auto margins.

Developer WorkflowFrontend EngineeringAI Coding
Real photo: top-down view of hands sorting handwritten index cards on a dark desk, with clipboards holding tables beside them
Guide
Put the data in a labeled box first: objects and JSON, explained plainly

One order is one object: table, dishes, total, paid — all filed by label. This guide follows MDN's Working with objects, JSON, and Object references: object literals, dot vs bracket notation, adding and deleting properties, for...in with hasOwn, methods and this, getters and setters, references vs copies, Object.assign and friends, null-prototype objects, JSON's strict rules, and stringify and parse with their number-precision trap.

Developer WorkflowFrontend EngineeringAI Coding
A developer with glasses types on a laptop at a wooden desk, an external monitor to the left showing C code on a dark background, a small plant on the desk
News
Microsoft's Coding Model Stops Playing Second Fiddle: MAI Code 2 Scores 96% of Opus 5.5 for 5% of the Cost — Read the Three Caveats First

On 17 November 2026, Microsoft launched MAI Code 2 and Code 2 Flash: the larger model has 77 billion active parameters and a one-million-token context, averaging 63.2% across four benchmarks — close to GPT-6.1 Sol and Claude Opus 5.5 — at $0.309 per task. Read the three caveats first: promotional pricing, the lowest score of the three, and no long-horizon work.

Developer WorkflowProduct LaunchModel Updates