8.5 Sandbox Mode

Course: Claude Code - Power User Section: Configuration Video Length: 3-4 minutes Presenter: Daniel Treasure

Opening Hook

Sandbox mode is your safety bubble. When you're working with unknown code, testing risky changes, or doing demos—lock Claude Code into a restricted environment. Filesystem isolation, network isolation, blocked commands. Full control.

Key Talking Points

1. Why Sandbox Mode Exists

Test untrusted code safely
Prevent accidental destructive operations
Demo sensitive projects without risk
Comply with security policies
Experiment without fear

What to say: "Sandbox mode is like a controlled laboratory. You can run Claude Code and know exactly what it can access and what it can't."

What to show on screen: Show a simplified before/after: - Without sandbox: Claude Code has normal file access, network access, bash access - With sandbox: Restricted filesystem, no network, blocked commands only

2. Sandbox Configuration Options

sandbox.enabled: true/false (master switch)
sandbox.autoAllowBashIfSandboxed: Allow bash with restrictions
sandbox.excludedCommands: Array of commands to block (git, docker, etc.)
sandbox.network.allowedDomains: Whitelist domains for web fetch
sandbox.network.allowLocalBinding: Allow connections to localhost
sandbox.filesystem.allowedPaths: Whitelist specific directories

What to say: "Sandbox has granular controls. You can allow some things and block others. It's not all-or-nothing."

What to show on screen: Show the structure of a sandbox config section in settings.json, highlight 3-4 key options

3. Filesystem Isolation

Restrict file read/write access
By default: full access to repo
With sandbox: only specified paths
Examples:
Allow: ./src, ./tests
Block: ~/.ssh, /etc/passwd, ../.env
Typical setup: Allow project directory, block home directory and system areas

What to say: "Filesystem isolation is the foundation. You tell Claude Code: 'You can only touch these specific files and folders.'"

What to show on screen: Show a config that restricts filesystem:

"sandbox": {
  "enabled": true,
  "filesystem": {
    "allowedPaths": ["./src", "./tests", "./config.json"]
  }
}

Explain: "Claude can only read/write in src, tests, and config.json. Everything else is blocked."

4. Network Isolation

Block all outbound network by default
Whitelist specific domains
Use case: Prevent data exfiltration, control API access
Examples:
Allow: github.com, npmjs.org, api.stripe.com
Block: everything else by default
allowLocalBinding: Allow localhost connections (for local services)

What to say: "Network isolation means Claude Code can't phone home or talk to unexpected APIs. You whitelist what's safe."

What to show on screen: Show a network config:

"sandbox": {
  "network": {
    "allowedDomains": ["github.com", "*.npmjs.org"],
    "allowLocalBinding": true
  }
}

5. Command Blocking

excludedCommands: List commands that are forbidden
Even with permissions allowing it, excluded commands are blocked
Examples:
Block: ["git", "docker", "rm -rf"] for safety
Block: ["sudo", "ssh"] for security
Common pattern: Block destructive and privileged commands

What to say: "Command blocking is your last line of defense. Even if a permission says 'allow bash', if git is excluded, git won't run."

What to show on screen: Show config:

"sandbox": {
  "autoAllowBashIfSandboxed": true,
  "excludedCommands": ["git", "docker", "rm", "sudo", "ssh"]
}

Explain: "Bash is allowed but only safe commands. Git, docker, destructive ops are blocked."

6. Common Sandbox Scenarios

Reviewing untrusted code: Full sandbox, minimal file access, no network
Testing risky changes: Sandbox for dev environment only, normal for production
Team demos: Restrict filesystem and network to prevent accidents
CI/CD safety: Locked-down sandbox with only whitelisted operations
Open-source contributions: Sandbox prevents Claude Code from modifying outside the PR files

What to say: "Different situations call for different sandbox levels. Know your risk tolerance and set accordingly."

What to show on screen: Show 2-3 realistic sandbox configs and explain each use case

7. Enabling Sandbox: Where and How

Can be enabled in settings.json at any level (user, project, local)
User level: applies everywhere (strict policy)
Project level: shared with team, enforced for that repo
Local level: machine-specific overrides
CLI flag: claude code --sandbox (if supported)

What to say: "You can enforce sandbox for your whole machine, or just enable it for specific projects. It's flexible."

What to show on screen: Show examples: - User settings with sandbox enabled globally - Project settings with stricter sandbox - How project overrides/augments user sandbox

Demo Plan

Show sandbox configuration in settings.json (1 min)
Open a .claude/settings.json or ~/.claude/settings.json
Point out the sandbox section
Explain each field
Enable sandbox for a project (1 min)
Open a sample project
Add sandbox config to .claude/settings.json
Show allowed and blocked paths
Test sandbox in action (1 min)
Try to read a file outside the sandbox (blocked)
Try a command in the excluded list (blocked)
Show the error message clearly
Explain why it was blocked
Configure network isolation (1 min)
Set allowed domains
Try to fetch from a whitelisted domain (succeeds)
Try to fetch from a blocked domain (fails)
Explain the use case (data security)
Scenario: Reviewing untrusted code (1 min)
Create a minimal sandbox config for high security
Explain the restrictions
Show how it protects you
Wrap-up and lead-out (30 sec)
"That completes the Configuration section. You now have settings, permissions, model selection, environment variables, and sandbox mode. You control Claude Code."

Code Examples & Commands

Enable sandbox with default restrictions:

{
  "sandbox": {
    "enabled": true
  }
}

Filesystem isolation example:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowedPaths": [
        "./src",
        "./tests",
        "./package.json",
        "./.claude"
      ]
    }
  }
}

Restrict both filesystem and network:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowedPaths": ["./src"]
    },
    "network": {
      "allowedDomains": ["github.com", "npmjs.org"],
      "allowLocalBinding": false
    }
  }
}

Block dangerous commands:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": [
      "git",
      "docker",
      "rm",
      "rm -rf",
      "sudo",
      "ssh",
      "curl -X DELETE",
      "curl -X POST"
    ]
  }
}

Strict sandbox for untrusted code review:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowedPaths": ["./"]
    },
    "network": {
      "allowedDomains": [],
      "allowLocalBinding": false
    },
    "autoAllowBashIfSandboxed": false,
    "excludedCommands": ["*"]
  }
}

Development machine with optional sandbox:

{
  "sandbox": {
    "enabled": false
  }
}

Project-level sandbox for team:

{
  "model": "balanced",
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowedPaths": [
        "./src",
        "./tests",
        "./config",
        "./.env.local"
      ]
    },
    "network": {
      "allowedDomains": [
        "github.com",
        "*.npmjs.org",
        "api.example.com"
      ],
      "allowLocalBinding": true
    },
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": [
      "git push",
      "docker",
      "rm -rf",
      "sudo"
    ]
  }
}

CI/CD pipeline sandbox (maximum isolation):

{
  "model": "balanced",
  "permissions": {
    "allow": ["bash(npm run test)", "bash(npm run build)"],
    "deny": ["bash(*)", "edit(*)", "WebFetch(*)"]
  },
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowedPaths": ["./"]
    },
    "network": {
      "allowedDomains": ["npmjs.org"],
      "allowLocalBinding": false
    },
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker", "sudo", "rm -rf"]
  }
}

Gotchas & Tips

Sandbox blocks recursively: If you block a directory, all subdirectories are blocked too. Be specific with allowedPaths.
Network blocking is strict: If no domains are whitelisted, no web fetch is allowed. Add domains you need.
Commands must match exactly: excludedCommands: ["git"] blocks git, but maybe not git push (depends on implementation). Test to verify.
Sandbox adds latency: Enforcing restrictions takes computational overhead. It's usually small but noticeable in tight loops.
Local binding is important: If you're running services on localhost (databases, APIs), set allowLocalBinding: true.
Sandbox doesn't protect secrets in RAM: It prevents file access and network calls, but doesn't encrypt sensitive data in memory.
Filesystem paths are relative to project root: Use ./ for current directory, not absolute paths unless needed.
Errors should be clear: When something is blocked, Claude Code should say why. Use those errors to refine your config.

Lead-out

You've now mastered the Configuration section: settings hierarchy, permissions, model selection, environment variables, and sandbox mode. You control every aspect of how Claude Code behaves. In the next section, we'll look at advanced workflows and real-world patterns. You're no longer a user—you're an operator.

Reference URLs

Claude Code sandbox documentation: https://claude.ai/docs/claude-code/sandbox
Security best practices: https://claude.ai/docs/security
Configuration reference: https://claude.ai/docs/claude-code/configuration

Prep Reading

Understand the concept of filesystem isolation
Know the difference between local and network security
Review your own threat model (what are you protecting against?)
Think about where you'd use sandbox mode in your workflow
Understand command blocking and whitelisting concepts

Notes for Daniel: Sandbox mode is the "serious security" topic. It appeals to security-conscious developers and enterprises. Demo it with a relatable scenario (reviewing code from GitHub, testing a risky change). The errors when something is blocked are your friend—they show the sandbox working. Keep the energy: "This is how you work safely with untrusted code." End on a high note: "You're now in complete control of Claude Code at every level."

Quick Reference