AnthropicClaude Certified Architect – Professional2026-105.1 Implement guardrails and safety controls
Contain execution with centrally enforced settings
Completed by the knowledge check
Learning objective
Constrain agent execution environments with sandboxing, network restrictions, and centrally managed settings
Core idea
A permission rule decides whether an action may start. A sandbox constrains what a running process can reach. Managed settings determine who can change that configuration. A production containment design needs all three questions answered without assuming they cover the same surfaces.
Claude Code’s built-in sandbox wraps shell commands. It does not surround the whole agent process. If your requirement includes file tools, hooks, and MCP servers, a shell-only sandbox leaves part of that requirement outside its boundary. Anthropic recommends running Claude Code itself inside a container, virtual machine, or sandbox runtime when those processes need one encompassing boundary.
Most of this Bite covers Claude Code and Agent SDK hosts; hosted Managed Agents use the separate environment control described here.
How it works
Select the boundary by what it covers
The built-in sandbox uses operating-system enforcement around Bash, PowerShell, and Monitor commands and their child processes. It runs on macOS, Linux, and WSL2. On native Windows, shell commands run unsandboxed; move a required sandbox workload to a supported environment rather than treating a Windows permission dialog as equivalent isolation.
The coverage distinctions are consequential:
| Surface | Built-in shell sandbox coverage | Additional control |
|---|---|---|
| A shell command and its children | Filesystem and network limits apply | Configure the required paths and hosts |
| Read, Edit, Write, WebFetch, WebSearch | Run outside that sandbox | Their permission rules |
| Hooks and local MCP servers | Run outside that sandbox with the host’s access | Trusted deployment and an enclosing environment when required |
| Explicitly excluded shell commands | Run unsandboxed | Remove the exception or constrain the enclosing environment |
Enable the shell sandbox with sandbox.enabled: true. If isolation is mandatory, also set sandbox.failIfUnavailable: true: otherwise a missing dependency or unsupported platform can lead to unsandboxed execution. Set sandbox.allowUnsandboxedCommands: false to stop Claude from retrying a failed command through the unsandboxed escape hatch.
Review sandbox.excludedCommands separately. A matching command runs without the sandbox’s filesystem or network limits. An exception for a general interpreter or deployment CLI can expose far more authority than the one failing operation that motivated it.
For a hosted alternative, Claude Managed Agents environments are beta and use anthropic-beta: managed-agents-2026-04-01. Set networking.type: "limited" with allowed_hosts; allow_package_managers and allow_mcp_servers optionally permit additional destinations. "unrestricted" permits outbound access subject to a general safety blocklist. An API create request that omits networking gets unrestricted, although the Console form starts with Limited selected. Specify the API setting explicitly rather than inferring a restrictive default from the hosted sandbox.
Restrict filesystem and network together
By default, sandboxed commands can write to the working directory, a per-user temporary directory, and added directories, with protected paths still denied. Reads are broader: the documented default includes most of the machine, including credential files. Therefore, “sandbox enabled” is not a claim that secrets are unreadable.
Use sandbox.filesystem.denyRead for prohibited reads and sandbox.filesystem.allowWrite and denyWrite to define shell write access. Anthropic also documents sandbox.credentials for protecting credential files and environment values. Protect the separate file-tool surface with permission rules; a sandbox denyRead entry does not block the Read tool.
Network connections go through a local filtering proxy. Use sandbox.network.allowedDomains and deniedDomains to express permitted and prohibited destinations. The domain list starts empty, but that is not necessarily a hard deny: permission mode and approval behavior affect requests for other hosts.
For an organization-controlled allowlist, set sandbox.network.allowManagedDomainsOnly: true in managed settings. It blocks unlisted domains and prevents local additions from widening the managed list. For a strict user, managed, or CLI policy, sandbox.network.strictAllowlist: true denies hosts outside the allowlist instead of prompting; setting that key in repository settings has no effect.
The built-in proxy does not inspect encrypted traffic by default. An approved host can still carry an unwanted disclosure, so restrict reachable secrets and tool effects too.
Deliver policy from an administrative source
A project .claude/settings.json is convenient shared configuration, but centralized enforcement belongs in managed settings. Endpoint delivery can protect the policy file at the operating-system level. The system file is /Library/Application Support/ClaudeCode/managed-settings.json on macOS and /etc/claude-code/managed-settings.json on Linux and WSL.
Server-managed settings let Team and Enterprise organization owners deliver configuration from the Claude administration console. Verify credential coverage: direct Anthropic connectivity and an eligible credential are required. A Console API key receives policy from its own Console organization, which is separate from the claude.ai Team or Enterprise organization. Exported third-party-provider variables or a non-default ANTHROPIC_BASE_URL cause the documented direct-fetch path to be skipped.
Do not assume all administrative sources merge. By default, Claude Code selects the first managed source delivering a policy key, with server-managed settings ahead of endpoint sources, subject to documented cross-source exceptions. managedSourcesBehavior: "merge" opts into combination across administrative sources on Claude Code v2.1.242 or later; different kinds of keys combine differently. Inspect the effective policy after delivery rather than predicting it from two configuration files.
On Claude Code v2.1.285 or later, a sandbox made admin-required by managed sandbox.allowUnsandboxedCommands: false ignores repository settings that loosen it, including excludedCommands. This stops a repository from restoring the package-manager escape; user settings can still supply exceptions unless a managed lock covers them.
In managed sandbox settings, allowManagedReadPathsOnly: true honors only managed allowRead entries. On v2.1.285 or later, a managed filesystem.denyRead or credentials.files deny also makes Claude Code ignore repository allowRead and allowWrite entries at or under the denied path. These locks constrain sandboxed commands; file tools still need their own permission rules.
Use /status to inspect the active source and /permissions for effective permission rules. claude doctor reports the server-managed fetch outcome in its Managed settings (remote) line on Claude Code v2.1.248 or later. Delivery success and effective containment are separate acceptance checks.
Key distinctions and trade-offs
Convenience versus containment: Auto-allowing sandboxed commands can reduce prompts within the defined boundary. It does not widen the boundary’s coverage to file tools or servers.
Local flexibility versus policy integrity: Managed Booleans override local values; array merging needs the domain and read-path locks described here. Test attempts to widen both.
Compatibility versus exceptions: A blocked dependency download might justify an approved mirror. Excluding the package manager entirely removes isolation for those commands. Prefer the smallest change that satisfies the workload and retest the resulting reach.
Shell containment versus whole-process containment: Include local servers and hooks when choosing an enclosing environment; a shell-only boundary does not contain them.
Architecture / decision scenario
A financial-services platform team supports 120 developers and Linux automation runners. The requirement permits dependencies only from an approved package mirror and forbids repository code from reading host credentials. A prototype enables the Bash sandbox locally; another proposal excludes the package manager whenever networking fails.
The architect rejects both as complete solutions. Default shell reads still include credential files, non-shell tools remain outside the boundary, and exclusions lose network isolation. The team uses an enclosing controlled runner for automation and centrally manages shell settings on supported workstations. Credential access and file-tool permissions are restricted separately.
Managed settings enable the sandbox, fail startup when it is unavailable, make it admin-required, lock the mirror domains, and deny credential reads with managed-only read exceptions. The platform team verifies the effective managed source on a workstation and runner; it does not assume the Team console policy reaches a runner using a Console API key.
Acceptance probes attempt an external connection, a credential read through shell and Read, local domain-list expansion, repository excludedCommands, repository allowRead under a denied credential path, and startup without a sandbox dependency. Each must fail at its intended boundary. The platform owner accepts mirror maintenance and startup failures as costs of the containment requirement; an exception needs a reviewed policy change rather than an automatic retry outside isolation.
Common exam traps
- Treating the Bash sandbox as a boundary around every tool.
- Omitting hosted-environment
networkingand assuming restricted access. - Assuming its default read policy hides credentials.
- Enabling isolation while allowing unsandboxed fallback.
- Reading an empty domain list as an unconditional network deny.
- Assuming repository settings can enforce every sandbox key.
- Assuming server and endpoint policies always merge or reach every credential.
What to remember
Choose the boundary by process coverage. Lock filesystem, secrets, and network together, disable required-isolation fallback, and deliver policy through a managed source that actually reaches the runtime. Verify effective settings and blocked behavior separately.
Knowledge check
A platform team requires that everything Claude Code runs on its CI runners — shell commands, local MCP servers and hooks — be unable to reach hosts outside an approved list. Which design meets the requirement?
allowedDomainssandbox.network.strictAllowlistWebFetch(domain:…) allow rule for each approved hostWebFetch rules govern one tool, so neither reaches the servers and hooks.Managed settings enable the shell sandbox with sandbox.enabled: true and sandbox.allowUnsandboxedCommands: false. On some Linux runners the sandbox’s dependency is missing, and isolation is mandatory. What should the policy add?
sandbox.excludedCommands entries for the commands that failsandbox.network.allowManagedDomainsOnly: truesandbox.failIfUnavailable: trueallowUnsandboxedCommands: false only removes the per-command unsandboxed retry; failIfUnavailable: true makes Claude Code exit at startup instead. Excluding the failing commands runs them unsandboxed, and a domain lock does nothing when no sandbox is running.A team adds ~/.aws to sandbox.filesystem.denyRead so that Claude Code on developer laptops cannot read cloud credentials. A probe shows that cat ~/.aws/credentials fails, but asking Claude to open the file succeeds. What closes the gap?
Read deny permission rule covering the credentials pathsandbox.filesystem.denyWrite entry for the same pathsandbox.allowUnsandboxedCommands to falsesandbox.failIfUnavailable to truedenyRead constrains sandboxed shell commands; the Read tool runs outside the sandbox and follows permission rules instead. A Read deny rule protects that second surface. The other settings tighten the shell sandbox, which already blocked the cat .A team creates a Claude Managed Agents environment through the API for an agent that should reach only an internal package mirror. The create request omits networking, because a teammate saw Limited preselected in the Console’s environment form. What outbound access does the environment get?
allowed_hostsnetworking gets unrestricted , which permits outbound access except for a general safety blocklist. The Console form’s Limited preselection is a form default, not the API’s. The request should set networking.type: "limited" with the mirror in allowed_hosts explicitly.A company configures sandbox policy as server-managed settings in its claude.ai Enterprise organization. Its CI jobs run Claude Code with an API key created in the company’s Claude Console organization. The runners have no endpoint-managed settings file, and a probe on a runner shows the sandbox is off. What explains the result?
/status . A managed Boolean is not overridden by repository settings.References
- Anthropic, Configure the sandboxed Bash tool
- Anthropic, Deploy managed settings
- Anthropic, Configure server-managed settings
- Anthropic, Cloud environment setup