Skip to main content
hc
Submit
guidesSource-backedReview first Safety ✓ Privacy ✓

Sandbox Environments For Claude Code Risk Boundaries

Define sandbox environment boundaries for Claude Code: managed settings, network egress, filesystem scope, worktree isolation, and when to fail closed.

by kiannidev·added 2026-06-13·
Claude Code
HarnessClaude Code
Review first — review before installing

Open the source and read safety notes before installing.

Safety notes

  • Sandbox environments reduce accidental exfiltration and destructive writes but do not replace code review, secret scanning, or MCP tool governance.
  • Managed allowManagedDomainsOnly and read-path restrictions require complete sandbox blocks—partial managed files can be ignored if sandbox keys are missing.
  • Background sessions and auto mode can still trigger network permission prompts—align sandbox policy with auto mode hard-deny rules.

Privacy notes

  • Network allowlists define which third parties may receive tool output or package download metadata.
  • Filesystem allowlists still expose repository contents to local processes—classify repos before widening read paths.
  • Worktree isolation guards prevent shared-checkout edits but transcripts may still contain sensitive diffs—follow normal log retention policy.

Prerequisites

  • A team risk model separating read-only exploration from write-capable automation.
  • Managed settings distribution for Claude Code across developer machines.
  • Documented data classification for repositories and external APIs agents may call.
  • Platform coverage plan for macOS, Linux, and WSL sandbox dependencies.

Schema details

Install type
copy
Reading time
8 min
Difficulty score
62
Troubleshooting
Yes
Breaking changes
No
Source repository stats
Scope
Source repo
Full copyable content
Map team risk tiers to Claude Code sandbox settings—network allowlists, write paths, managed domain restrictions, and worktree isolation—for desktop, CLI, and background agent surfaces.

About this resource

TL;DR

Treat Claude Code sandbox configuration as an environment boundary layer: map team risk tiers to managed sandbox settings, constrain network egress and filesystem writes, use worktree isolation for parallel agents, and fail closed when sandbox dependencies are missing on regulated machines.

Prerequisites & Requirements

  • {"task": "Risk tiers defined", "description": "Read-only, standard dev, and elevated automation tiers are documented"}
  • {"task": "Managed settings pipeline", "description": "Org can ship sandbox blocks to all Claude Code clients"}
  • {"task": "Dependency matrix", "description": "macOS, Linux, and WSL sandbox prerequisites are tracked"}
  • {"task": "API inventory", "description": "Required egress domains for package managers and APIs are listed"}
  • {"task": "Isolation policy", "description": "Rules for worktree vs shared-checkout background sessions are decided"}

Core Concepts Explained

Environments encode risk tiers

A sandbox environment is not just on/off—it combines enabled flag, network allow/deny lists, filesystem write scope, excluded commands, and fail-closed behavior into a profile matching a risk tier.

Managed settings enforce boundaries

Enterprise teams ship sandbox blocks through managed settings so individual developers cannot silently widen egress or disable sandboxing without detection.

Worktrees isolate parallel agents

Background sessions and subagents can use worktree isolation to avoid editing the shared checkout. Settings like worktree.bgIsolation trade isolation for practicality on non-git workflows.

Sandbox interacts with permissions and auto mode

Network permission prompts may still appear in auto mode or desktop surfaces. Align sandbox boundaries with autoMode.hard_deny and static deny rules.

Step-by-Step Implementation Guide

  1. Define risk tiers. Example: Tier A read-only docs, Tier B standard feature work, Tier C elevated automation with broader network needs.

  2. Draft environment profiles. For each tier, specify sandbox.enabled, network allow/deny lists, filesystem write paths, and sandbox.failIfUnavailable.

  3. Map managed restrictions. Where policy requires managed domain or read-path restrictions, ensure every managed-settings source includes a complete sandbox block so overrides cannot be ignored.

  4. Configure worktree isolation. Document when background agents must call EnterWorktree, when worktree.bgIsolation: "none" is approved, and cleanup expectations for .claude/worktrees/.

  5. Pilot on one tier. Roll Tier B to a single team, collect blocked-command reports, and adjust allowlists before org-wide managed rollout.

  6. Integrate with MCP policy. Sandbox boundaries do not limit MCP tools—pair this rollout with managed MCP allowlists for full environment control.

  7. Monitor release notes. Sandbox behavior changes frequently—revalidate profiles after Claude Code upgrades.

Risk Boundary Matrix (example)

Tier Sandbox Network Writes Worktree
A explore enabled deny default workspace only optional
B dev enabled package APIs workspace + tmp recommended
C automation enabled + fail closed reviewed allowlist workspace + artifacts required

Troubleshooting

Managed domain restrictions ignored

Ensure the active managed-settings merge includes a sandbox section; release notes document cases where missing sandbox blocks skipped restrictions.

Background agents edit shared checkout

Verify worktree isolation guards, EnterWorktree availability, and whether worktree.bgIsolation: "none" was intentionally set.

Sandbox differs between desktop and CLI

Test both surfaces—release notes mention sandbox permission prompts in desktop, IDE extensions, and SDK hosts.

Orphan worktrees after retention sweeps

Document cleanup for .claude/worktrees/ after background job retention policies remove stale sessions.

Source Verification Notes

Verified against the public anthropics/claude-code repository README and CHANGELOG.md on 2026-06-13:

  • CHANGELOG.md documents sandbox network permission prompts in auto mode for desktop, IDE extensions, and SDK integrations.
  • CHANGELOG.md adds worktree.bgIsolation: "none" for background sessions that must edit the working copy directly when worktrees are impractical.
  • CHANGELOG.md records security fixes for allowManagedDomainsOnly and allowManagedReadPathsOnly being ignored when managed settings lacked sandbox blocks.
  • CHANGELOG.md covers worktree isolation guards for background subagents, cleanup of .claude/worktrees/, and EnterWorktree availability in sessions.
  • Official docs at code.claude.com/docs/en/sandbox-environments describe user-facing environment concepts aligned with these settings.

Duplicate Check

This guide complements sandboxed-bash-setup-for-autonomous-coding-agents.mdx, which focuses on bash auto-allow and dependency verification. This guide maps org-wide sandbox environment profiles to risk tiers and managed rollout.

References

#claude-code#sandbox#risk-management#managed-settings#worktree#enterprise

Source citations

Add this badge to your README

Show that Sandbox Environments For Claude Code Risk Boundaries is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.

Listed on HeyClaude
[![Listed on HeyClaude](https://heyclau.de/badge/guides/sandbox-environments-for-claude-code-risk-boundaries.svg)](https://heyclau.de/entry/guides/sandbox-environments-for-claude-code-risk-boundaries)

How it compares

Sandbox Environments For Claude Code Risk Boundaries side by side with 3 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.

FieldSandbox Environments For Claude Code Risk Boundaries

Define sandbox environment boundaries for Claude Code: managed settings, network egress, filesystem scope, worktree isolation, and when to fail closed.

Open dossier 		Managed MCP Allowlists for Enterprise Claude Code

Deploy enterprise managed MCP allowlists and denylists in Claude Code: allowedMcpServers, deniedMcpServers, managed-mcp.json, enforcement on reconnect, and rollout testing.

Open dossier 		Sandboxed Bash Setup For Autonomous Coding Agents

Enable Claude Code bash sandboxing for autonomous agents: filesystem and network boundaries, auto-allow rules, dependency checks, and fail-closed settings.

Open dossier 		Auto Mode Hard-Deny Policies For Safe Automation

Configure Claude Code auto mode hard-deny rules that block high-risk actions unconditionally, complement soft-deny prompts and team permission policy.

Open dossier
Trust
Install riskReview firstReview firstReview firstReview first
Notes Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓
Categoryguidesguidesguidesguides
Sourcesource-backedsource-backedsource-backedsource-backed
Authorkiannidevkiannidevkiannidevkiannidev
Added2026-06-132026-06-142026-06-132026-06-13
Platforms
Claude Code
Claude Code
Claude Code
Claude Code
Source repo————
Safety notes✓Sandbox environments reduce accidental exfiltration and destructive writes but do not replace code review, secret scanning, or MCP tool governance. Managed allowManagedDomainsOnly and read-path restrictions require complete sandbox blocks—partial managed files can be ignored if sandbox keys are missing. Background sessions and auto mode can still trigger network permission prompts—align sandbox policy with auto mode hard-deny rules.✓Denylist gaps let users attach unreviewed remote MCP servers—default to allowlist-first in regulated environments. Invalid allowlist entries previously discarded entire policy; validate JSON in staging and monitor `claude doctor` warnings. Subagent MCP servers must respect the same managed policy as parent sessions.✓Sandboxing reduces blast radius but does not eliminate malicious code—review diffs and keep branch protection enabled. Missing sandbox dependencies previously caused silent disable; use fail-closed settings and verify `/sandbox` status after upgrades. autoAllowBashIfSandboxed auto-approves some commands—pair with deny rules for destructive patterns.✓Hard-deny rules block regardless of user intent or allow exceptions—misconfiguration can halt legitimate workflows. Auto mode classifiers can still fail open with evaluation errors; hard deny is not a substitute for branch protection and CI gates. Do not rely on auto mode alone for secrets handling; deny credential reads and outbound bulk transfers explicitly.
Privacy notes✓Network allowlists define which third parties may receive tool output or package download metadata. Filesystem allowlists still expose repository contents to local processes—classify repos before widening read paths. Worktree isolation guards prevent shared-checkout edits but transcripts may still contain sensitive diffs—follow normal log retention policy.✓Allowlists control which third-party operators receive prompts and tool arguments—record data processors per approved server. Managed MCP URLs may appear in support logs; avoid embedding internal hostnames you do not want broadly visible. OAuth tokens for allowed servers remain on user machines until revoked during offboarding.✓Sandboxed commands still read repository files within allowed paths; do not store secrets in sandbox-writable directories. Network-allowed domains determine where agent output or tokens might be sent—document allowed egress. Sandbox logs and permission prompts may capture command text including paths and environment variable names.✓Auto mode classifiers evaluate tool names, arguments, and session context that may include file paths and repository metadata. Denial messages and debug logs can retain snippets of blocked commands; restrict log access on shared machines. Managed settings sync may expose rule text to all enrolled clients—avoid embedding internal codenames you do not want widely visible.
Prerequisites
  • A team risk model separating read-only exploration from write-capable automation.
  • Managed settings distribution for Claude Code across developer machines.
  • Documented data classification for repositories and external APIs agents may call.
  • Platform coverage plan for macOS, Linux, and WSL sandbox dependencies.
  • Enterprise or team tier with managed settings distribution.
  • An inventory of approved MCP servers with URLs, OAuth scopes, and owners.
  • A test cohort machine to validate allowlist predicates before org-wide push.
  • Documented rollback to remove bad managed-mcp.json entries without blocking all policy.
  • Claude Code on macOS, Linux, or WSL with sandbox dependencies available or installable.
  • Permission to edit project or managed settings.json sandbox blocks.
  • Representative build and test commands your agents run in CI.
  • A rollback plan if sandbox misconfiguration blocks legitimate workflows.
  • Claude Code with auto mode available on your provider and organization policy.
  • Permission to edit project or managed settings.json for the target repositories.
  • A list of actions that must never run without explicit human approval.
  • Pilot engineers who can trigger both allowed and blocked auto mode actions safely.
Install————
Config————
Citations
ClaimUnclaimedUnclaimedUnclaimedUnclaimed

Signals

Loading live community signals…

More like this, weekly

A short, calm digest of reviewed Claude resources. Unsubscribe any time.