Is --restricted the same thing as "Claude Code now has a sandbox"?
No. Official documentation is explicit about this: --restricted is a useful low-authority starting point for reviewing an unfamiliar repository or running a narrow CI task, but it is not an operating-system-level sandbox. What it does is shrink the tools, file scope, and settings sources that the Claude Code application itself can access — it doesn't isolate the whole process, network connections, or credential access at the OS level.
If your scenario involves input that's completely untrusted and requires the ability to execute arbitrary code, official guidance is to put the entire process inside a hardened container or VM, and apply Claude Code's own sandbox controls as an additional layer on top. --restricted can be part of that pipeline, but it can't carry the weight of "isolating untrusted input" on its own.
Why are "user, project, and local settings ignored" and "MCP servers unaffected" handled separately instead of being tightened together?
This reflects a real difference in what these two categories of configuration actually are. The user, project, and local settings layers are mostly personal preferences and habits — how a person or project typically uses Claude Code day to day. Ignoring them ensures this session doesn't accidentally inherit habitual rules you've built up in some other project. MCP servers, on the other hand, are connection points to external systems — whether they should exist usually depends on whether the current task genuinely needs to reach some external service, a different dimension of the question entirely from "personal habits."
If --restricted automatically cleared MCP servers too, a genuinely narrow task that still needs to reach an internal tool through MCP — say, a read-only internal knowledge-base MCP Server — would become unnecessarily constrained, forcing you to find another way to add it back. Splitting "clear personal configuration" and "decide whether to keep the MCP connection" into two separate decisions — the latter requiring you to actively trigger it with --strict-mcp-config — lets users adjust each dimension based on what the task actually needs, rather than being forced into all-or-nothing.
If I want to use --restricted for a purely read-only repository review, how do I actually combine these options?
The most direct combination is explicitly declaring both the tool list and the MCP configuration at the same time, rather than just turning on --restricted and expecting it to automatically become read-only. In practice this looks something like: --restricted --tools "Read,Grep,Glob" --strict-mcp-config --mcp-config ./restricted-mcp.json — using --tools to explicitly list only read-type tools, excluding anything that executes commands or edits files, and --strict-mcp-config paired with an MCP configuration file you prepared yourself, either empty or containing only servers genuinely needed, to make sure no MCP Server from another source can unexpectedly get involved.
If, during this review, you discover you genuinely need to make an edit, the more conservative approach is to add a narrowly-scoped file-editing tool specifically for that, while keeping approval handling for protected files, rather than swapping the whole effect of --restricted for broad Bash permissions and telling yourself the session is still "low authority." Once you restore a tool that executes commands, you're no longer in the kind of low-authority state --restricted was meant to maintain.
If my team already has organization-managed settings in place, is there anything special to watch for when using --restricted?
The most important thing to confirm first is that managed settings aren't bypassed by --restricted — meaning if your organization already enforces certain security policies through managed settings (disabling bypassPermissions, restricting certain high-risk tools), those policies remain in effect within a --restricted session. There's no need to worry that --restricted accidentally weakens protections your organization already has in place.
But the reverse is also worth watching for: --restricted ignores the user, project, and local layers. If your team is in the habit of writing certain security-related custom rules — extra deny rules, say — into project-level settings files rather than into managed settings, those rules get ignored in a --restricted session. That means if you were relying on a project-level rule to shore up a specific risk, --restricted could actually leave that gap temporarily uncovered — worth confirming whether rules like that should be promoted to the managed-settings tier, so they keep applying no matter how the session is launched.
Claude Code 2.1.248 (August 27, 2026) added a startup flag called --restricted, along with its equivalent environment variable, CLAUDE_CODE_RESTRICTED=1. This mode has a clear positioning: it isn't an operating-system-level sandbox — it's a startup configuration that defaults to minimal authority, letting you decide yourself which capabilities to add back one at a time. It's particularly well suited to working with a codebase you're unfamiliar with and haven't established trust in yet.
With --restricted enabled, the built-in command-execution and code-execution tools (Bash, for instance), along with WebFetch, are removed by default unless you explicitly name them back with --tools. It also ignores your user, project, and local settings files. File-tool access is confined to the working directory you started in (plus any directories you explicitly add with --add-dir), and it refuses bypassPermissions — the mode that skips permission confirmation entirely.
The first misunderstanding is that "settings files are ignored" doesn't mean "every setting stops applying." Organization-managed settings, along with a settings file you explicitly point to with --settings, still take effect. If you see "user, project, and local settings are ignored" and conclude the session is completely clean without checking whether managed settings are still operating behind the scenes, you risk misjudging the actual scope of authority in play.
The second misunderstanding is that MCP servers are handled differently from other tools — --restricted on its own doesn't automatically clear existing MCP configuration. If your scenario needs to guarantee that no external MCP Server can get involved at all, you need to separately add --strict-mcp-config, paired with a reviewed MCP configuration file you prepared yourself. Enabling --restricted alone doesn't mean the MCP channel gets tightened along with everything else.
If what you've done before is audit and tighten Bash wildcard rules — turning an overly broad Bash(git *) into something more precise — that operates on the premise that the command-execution tool already exists, restricting which commands it's allowed to run. --restricted addresses a layer earlier than that: whether the command-execution and code-execution tools should exist in this session at all. The default answer changes to "they don't exist," and you have to actively decide whether to add them back — rather than having them exist by default and only narrowing what they can do through rules.
A more prudent starting point: first pin down the version actually running (different install methods and interfaces can end up pointing at different versions, so confirm what --version actually prints first), then start from a directory small in scope that contains no production credentials, rather than launching from your home directory or a whole monorepo root out of convenience — because --add-dir directly expands what file tools can reach, and every directory added is worth a clear reason first. For a straightforward read-only code review scenario, explicitly listing --tools "Read,Grep,Glob", paired with an MCP configuration file containing no servers at all, is clearer than enabling first and checking afterward.