Built-in Read, Edit and Write operations and direct WebFetch or WebSearch calls use Claude Code's permission system instead. Sandbox auto-allow is also different from permission Auto. The real boundary depends on the platform, active filesystem and network layers, read and write scope, network destinations and any fallback, so verify the behaviour you rely on.
For the broader distinction between attachments and agent workspaces, compare chat uploads with coding-agent workspace access.
What the Claude Code sandbox does
Claude Code's local sandbox limits what a Bash command can reach through two independently configurable layers: filesystem isolation and network isolation. Anthropic's current sandboxing documentation describes this as an operating-system-enforced boundary for sandboxed Bash commands and the processes they start.
That is narrower than saying the entire Claude Code session is inside one sandbox. A request to read a file can travel through the built-in Read tool, while a shell command can read through Bash. The first route is permission-governed. The second can be both permission-governed and OS-sandboxed. Direct web tools likewise follow their own permission route rather than inheriting the Bash network boundary.
The sandbox therefore answers a specific question: what can this Bash command and its descendants access or change? It does not decide whether the command is sensible, whether a document is trustworthy or whether an output is correct.
Check the boundary before running the command
Use harmless synthetic paths and destinations when testing. Record what actually happened rather than assuming that one successful or denied operation describes every route.
| Test | Execution route | Relevant boundary | Verify with harmless material |
|---|---|---|---|
| Read a sample file | Sandboxed Bash | Active read scope, separate from writable locations | Exact file reads or is denied as expected |
| Write disposable output | Sandboxed Bash | Working directory, session temporary location and any intentional writable additions | Output stays in the expected location |
| Start a child process | Sandboxed Bash | Child inherits the command's sandbox boundary | Child has the expected restricted access |
| Request a test domain | Sandboxed Bash | Active network isolation, proxy and destination rules | Exact destination is allowed, denied or prompts |
| Read or edit a sample file | Built-in Read, Edit or Write | File-tool permissions and active mode | Observed result; this does not test Bash isolation |
| Fetch a public page | Direct WebFetch or WebSearch | Direct web-tool permissions | Observed result; this does not test Bash networking |
Before a real run:
- Identify the exact command, read path, write path and network destination the task needs.
- Distinguish sandboxed Bash from built-in file tools and direct web tools.
- Confirm that the Bash operation will actually run sandboxed and that both required isolation layers are active.
- Inspect read and write scope separately, then confirm only the necessary network destination.
- Note the current platform, approval behaviour and any documented fallback before testing.
- Test on harmless, recoverable material.
- Retain the observed result as evidence of the effective boundary for that platform and configuration.
Sandbox versus permissions: two control questions
Sandboxing and permissions overlap in a workflow, but they do different jobs. The sandbox enforces a technical boundary around Bash. Permissions decide whether Claude Code may use a tool or resource, ask first or refuse it.
Claude Code also uses similar-sounding labels for separate features. In sandbox auto-allow, an eligible command can run without another permission prompt because it stays inside the active sandbox. Sandbox regular permissions sends Bash through the normal permission flow while retaining the same filesystem and network restrictions. Permission Auto, by contrast, is a separate classifier-based permission mode. A command running under sandbox auto-allow does not mean every action in the session has been approved by permission Auto.
Anthropic's permissions documentation covers rule order, modes and directory scope; the practical version is in configure Claude Code permissions and workspace access. The routing is:
- What constrains a Bash command and its child processes? The sandbox.
- Which files or actions should Claude Code allow, ask about or deny? Permissions.
- How does agent workspace access differ from uploading a chat attachment? The file-access guide linked above.
Filesystem isolation: ask about reads and writes separately
Anthropic documents the current working directory, a session temporary location and deliberately added directories as default writable locations for sandboxed Bash. That statement does not prove that Bash can only read those locations. A write boundary and a read boundary are different controls, and the effective result can change with configuration.
Describe the requirement precisely. “Work on this project” hides several decisions: read source files, write generated files, use a temporary directory and perhaps read a dependency elsewhere. List each path and operation, then test it. An unexplained successful read is not evidence of a successful write, and neither result says what the built-in file tools can do.
This distinction also helps troubleshoot blocked commands. If a formatter can read source but cannot write its output, broadening all file access is unnecessary. Find the exact missing write location and review the smallest supported change.
Bash network isolation versus direct web tools
The Bash network boundary applies to traffic originating in sandboxed Bash and its descendants. It can constrain destinations through Claude Code's documented network path. It does not automatically govern WebFetch, WebSearch, connectors or other routes simply because they appear in the same session.
Test the route you intend to use. A successful WebFetch does not demonstrate that a shell command can reach the same domain. A domain allowance also says nothing about whether the retrieved content is accurate or safe to follow. Network destination control is not content inspection.
Filesystem and network isolation are independent. A session can retain one layer while the other is absent or differently configured. Record both rather than referring to “the sandbox” as a single yes-or-no state.
Child processes and the inherited environment
A process started by sandboxed Bash inherits the sandbox boundary. That matters for package scripts, build tools and other commands that launch further processes: moving work into a child does not move it outside the OS-enforced boundary.
The process also inherits its launching environment by default. The sandbox does not prove that environment variables, tokens or other credentials are absent. Before running generated commands, minimise what the process receives and avoid using sensitive values as test material. If a task genuinely needs a credential, use the narrow, approved mechanism for that environment rather than placing the value in a file or prompt for convenience.
These controls belong inside a broader workflow. You can place sandboxing inside the wider agent harness to see how task scope, permissions, isolation and verification work together.
What remains outside the Bash boundary
Built-in Read, Edit and Write tools use Claude Code permissions. Direct WebFetch and WebSearch calls use their own permission route. Their presence in a session with sandboxed Bash does not silently put them inside the Bash sandbox.
Permission rules are therefore still necessary. They can govern recognised tool calls and resources, while OS sandboxing supplies stronger enforcement for arbitrary commands and subprocesses. Neither control replaces human judgement about the task or input.
Documents are a useful example. A sandbox may limit where a command can read, but it does not determine whether instructions embedded in a readable document will influence an AI workflow. See how to understand prompt injection in documents without treating every instruction-like string as proof of malicious intent.
Platform, configuration and fallback differences
Current official documentation describes the built-in sandbox on macOS, Linux and WSL2. Native Windows and WSL1 do not have the same support. Recheck this before configuring access and whenever the execution environment changes.
Two fallback situations deserve separate attention. First, sandbox initialisation may be unavailable on a platform or deployment. Second, a particular command may require an unsandboxed retry through the regular permission flow. In either case, do not infer that the intended boundary remained active. Read the message, identify the blocked resource and decide whether the task can be redesigned or moved to a verified disposable environment.
Avoid copying old settings from a forum answer. Claude Code changes quickly, and a setting that once described a safe default may now have a different name, scope or fallback.
A safe way to verify the effective boundary
Use a disposable folder with invented files, no secrets and a harmless public test destination. Exercise each intended route separately: sandboxed Bash read, sandboxed Bash write, a child process, Bash network, a built-in file tool and a direct web tool. Record whether each operation was allowed, denied or prompted.
If observed access differs from the intended scope, stop and resolve the difference before using real material. Check the platform, active isolation layers, directory additions, permission behaviour and any fallback. This produces useful evidence without testing on customer documents or trying to escape the boundary.
Documents made available to a coding-agent workspace
A document can influence an AI workflow even when the commands processing it stay inside a sandbox. .mdSiren checks incoming versions for supported prompt-injection and document-borne risks before they become AI context. Each version receives an Approved, Needs review or Quarantine decision, with the current eligible Approved copy ready for retrieval and reuse.
Revised files need their own checks. In a manual Claude Code workflow, you would place the retrieved copy in the intended workspace, where permissions and sandboxing would still govern its use.
See the document checkpoint and its supported security scope, or Coming soon. Decisions cover the reported checks; Quarantine is a document-handling state, not operating-system quarantine.
Frequently asked questions
What is the Claude Code sandbox?
It is an operating-system-enforced filesystem and network boundary for local Bash commands that actually run sandboxed and for their child processes. The two isolation layers are separate and must be checked on the current platform and configuration.
Does the Claude Code sandbox cover every tool?
No. Built-in Read, Edit and Write operations and direct WebFetch and WebSearch calls use Claude Code's permission system. Do not infer their boundary from a Bash test.
Does a Bash child process inherit the sandbox?
Yes, when it is started by a Bash command that is running sandboxed. It also inherits the launching environment by default, so sandboxing does not prove that credentials are absent.
Is the Claude Code sandbox the same as permissions?
No. Sandboxing enforces the Bash boundary. Permissions decide whether tools and resources are allowed, require review or are denied. Sandbox auto-allow and permission Auto are also different features.
Does sandboxing make documents safe to use with Claude Code?
No. It can reduce what a command can reach or change, but it does not assess a document's suitability, trustworthiness or instructions. Document checks, access decisions and output review remain separate.
Should I disable or bypass the Claude Code sandbox?
Treat that as a last-resort diagnosis, not a routine fix. Identify the exact blocked path, destination or operation and change only the smallest relevant boundary through current supported controls. Redesign the task where possible. For genuinely high-risk automation that requires broad access, prefer a verified disposable container or virtual machine rather than weakening the primary workspace.
