Bash Sandbox

Learn how CodeBuddy Code's sandboxed Bash tool provides file system and network isolation for safer, more autonomous agent execution.

Overview

CodeBuddy Code features native sandbox capabilities that provide a more secure environment for agent execution while reducing constant permission prompts. Instead of requiring permission for every bash command, the sandbox creates predefined boundaries that allow CodeBuddy Code to work more freely with reduced risk.

The sandboxed Bash tool uses operating system-level primitives to enforce file system and network isolation.

Why Sandbox Matters

Traditional permission-based security requires continuous user approval for bash command execution. While this provides control, it can lead to:

• Approval Fatigue: Repeatedly clicking "approve" may cause users to pay less attention to what they're approving
• Reduced Productivity: Constant interruptions slow down development workflows
• Limited Autonomy: CodeBuddy Code cannot work efficiently while waiting for approvals

Sandbox addresses these challenges by:

1. Defining Clear Boundaries: Explicitly specifying which directories and network hosts CodeBuddy Code can access
2. Reducing Permission Prompts: Safe commands within the sandbox don't require approval
3. Maintaining Security: Attempts to access resources outside the sandbox trigger immediate notifications
4. Enabling Autonomy: CodeBuddy Code can run more independently within defined limits

WARNING

Effective sandboxing requires **both** file system and network isolation. Without network isolation, a compromised agent could exfiltrate sensitive files (like SSH keys). Without file system isolation, a compromised agent could backdoor system resources to gain network access. When configuring sandbox, it's important to ensure your configuration settings don't create bypasses in these systems.

How It Works

File System Isolation

The sandboxed Bash tool restricts file system access to specific directories:

• Default Write Behavior: Read-write access to current working directory and its subdirectories
• Default Read Behavior: Read access to the entire computer, except certain denied directories
• Blocked Access: Cannot modify files outside the current working directory without explicit permission
• Configurable: Define custom allowed and denied paths through settings

Network Isolation

Network access is controlled through a proxy server running outside the sandbox:

• Domain Restrictions: Only approved domains can be accessed
• User Confirmation: New domain requests trigger permission prompts
• Custom Proxy Support: Advanced users can implement custom rules for outbound traffic
• Comprehensive Coverage: Restrictions apply to all scripts, programs, and subprocesses spawned by commands

OS-Level Enforcement

The sandboxed Bash tool leverages operating system security primitives:

• Linux: Uses bubblewrap for isolation
• macOS: Uses Seatbelt for sandbox enforcement

These OS-level restrictions ensure all subprocesses spawned by CodeBuddy Code commands inherit the same security boundaries.

Getting Started

Enabling Sandbox

You can enable the sandbox by running the /sandbox slash command:

> /sandbox

This activates the sandboxed Bash tool with default settings, allowing access to the current working directory while blocking access to sensitive system locations.

Configuring Sandbox

Customize sandbox behavior through the settings.json file. See Settings for complete configuration reference.

TIP

Not all commands work out of the box with sandboxing. Here are some notes that may help you get the most out of sandboxing:

• Many CLI tools need access to certain hosts. When you use these tools, they will request permission to access certain hosts. Granting permission will allow them to access these hosts now and in the future, enabling them to execute safely within the sandbox.
• watchman is incompatible with running in the sandbox. If you're running jest, consider using jest --no-watchman
• docker is incompatible with running in the sandbox. Consider specifying docker in excludedCommands to force it to run outside the sandbox.

NOTE

CodeBuddy Code includes an intentional escape hatch mechanism that allows running commands outside the sandbox when necessary. When a command fails due to sandbox restrictions (like network connectivity issues or incompatible tools), CodeBuddy is prompted to analyze the failure and may retry the command using the `dangerouslyDisableSandbox` parameter. Commands using this parameter go through the normal CodeBuddy Code permission flow, requiring user permission to execute. This allows CodeBuddy Code to handle edge cases where certain tools or network operations cannot run within sandbox constraints.

You can disable this escape hatch by setting "allowUnsandboxedCommands": false in your sandbox settings. When disabled, the dangerouslyDisableSandbox parameter is completely ignored, and all commands must run in the sandbox or be explicitly listed in excludedCommands.

Sandbox Auto-Approval

In AcceptEdits permission mode, CodeBuddy Code provides sandbox auto-approval functionality to further reduce permission prompts:

How It Works

When sandbox auto-approval is enabled, Bash commands that meet all of the following conditions will be automatically approved for execution without user confirmation:

1. Currently in AcceptEdits permission mode
2. Sandbox is enabled (sandbox.enabled = true)
3. Auto-approval configuration is on (sandbox.autoAllowBashIfSandboxed = true)
4. Command will run in sandbox (not in excludedCommands list)
5. Not using dangerouslyDisableSandbox parameter

Configuration Example

Enable sandbox auto-approval in .codebuddy/settings.json:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  }
}

Usage Scenarios

Auto-approved (no user confirmation needed):

# In AcceptEdits mode, these commands are auto-approved
npm test
npm run build
ls -la
grep "pattern" file.txt

Requires approval (the following situations still require user confirmation):

# 1. Excluded commands (in excludedCommands)
git push

# 2. Commands explicitly disabling sandbox
# (using dangerouslyDisableSandbox parameter)

# 3. All commands in non-AcceptEdits mode

Sandbox Bypass Auto-Approval in Bypass Permission Mode

When a command attempts to cross sandbox boundaries (for example, writing to .git/refs/*.lock, or the model invokes Bash with dangerouslyDisableSandbox=true), the sandbox triggers a secondary "run this command outside the sandbox?" approval prompt.

Starting from v2.90.x, in bypassPermissions permission mode, such sandbox bypass approvals are automatically granted for non-high-risk commands, avoiding repeated approval prompts for routine combined commands like cd X && yarn build:

• ✅ Auto-approved: When the command's safety level is SAFE / LOW / MEDIUM, it directly continues execution as allow_once
• ⛔ Still requires confirmation: When the command's safety level is HIGH / CRITICAL (such as rm -rf /, chmod 777 /etc, etc.), interactive approval is preserved even in bypass mode

This policy is consistent with the protection semantics for dangerous Bash commands in bypass mode—bypassPermissions does not mean blind approval; high-risk operations always require explicit confirmation.

Security Guarantees

Sandbox auto-approval improves efficiency while maintaining security:

• ✅ Only within sandbox environment: Only sandboxed commands can be auto-approved
• ✅ File system isolation: Commands can only access allowed directories
• ✅ Network isolation: Commands can only access approved domains
• ✅ Configurable boundaries: Exclude high-risk commands via excludedCommands
• ✅ Security first: Any configuration errors or anomalies fall back to requiring user approval

Best Practices

1. Use cautiously: Only enable auto-approval when you understand sandbox limitations
2. Exclude high-risk commands: Add dangerous operations like git push, rm -rf to excludedCommands
3. Review regularly: Check logs to see which commands are being auto-approved
4. Use in combination: Use together with IAM permission rules for defense in depth

Security Benefits

Protection Against Prompt Injection

Even if an attacker successfully manipulates CodeBuddy Code's behavior through prompt injection, the sandbox ensures your system remains secure:

File System Protection:

• Cannot modify critical configuration files like ~/.bashrc
• Cannot modify system-level files in /bin/
• Cannot modify CodeBuddy configuration files (settings.json, settings.local.json), preventing sandbox escape through hook injection
• Cannot read files denied in CodeBuddy permission settings

Network Protection:

• Cannot exfiltrate data to attacker-controlled servers
• Cannot download malicious scripts from unauthorized domains
• Cannot make unexpected API calls to unapproved services
• Cannot contact any domain not explicitly allowed

Monitoring and Control:

• All attempts to access outside the sandbox are blocked at the OS level
• You receive immediate notification when boundaries are tested
• You can choose to deny, allow once, or permanently update configuration

Configuration File Protection

The sandbox blocks writes to CodeBuddy configuration files by default to prevent sandbox escape attacks. An attacker could use prompt injection to make the Agent write to settings.json, injecting malicious SessionStart hooks that execute malicious commands with host privileges the next time the user starts CodeBuddy.

The following configuration files are write-protected in the sandbox:

• ~/.codebuddy/settings.json - User global settings
• ~/.codebuddy/settings.local.json - User local settings
• .codebuddy/settings.json - Project shared settings
• .codebuddy/settings.local.json - Project local settings

This protection applies to both Bash commands and file editing tools (Write, Edit, MultiEdit), ensuring the sandbox's denyWrite rules are uniformly enforced across all tools.

Reduced Attack Surface

The sandbox limits potential damage from:

• Malicious Dependencies: NPM packages or other dependencies with harmful code
• Compromised Scripts: Build scripts or tools with security vulnerabilities
• Social Engineering: Attacks that trick users into running dangerous commands
• Prompt Injection: Attacks that trick CodeBuddy into running dangerous commands

Transparent Operation

When CodeBuddy Code attempts to access network resources outside the sandbox:

1. The operation is blocked at the OS level
2. You receive immediate notification
3. You can choose to:
   • Deny the request
   • Allow once
   • Update sandbox configuration to allow permanently

Security Limitations

• Network Sandbox Limitations: The network filtering system works by restricting which domains a process is allowed to connect to. It does not inspect traffic going through the proxy, and users are responsible for ensuring they only allow trusted domains in their policy.

WARNING

Users should be aware of the risks of allowing broad domain names (like `github.com`) which could allow data exfiltration. Additionally, in some cases it may be possible to bypass network filtering through [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting).

• Privilege Escalation via Unix Sockets: The allowUnixSockets configuration may inadvertently grant access to powerful system services which could lead to sandbox bypasses. For example, if using it to allow access to /var/run/docker.sock, this would effectively grant access to the host system by leveraging the docker socket. Users are encouraged to carefully consider any unix sockets they allow through the sandbox.
• File System Privilege Escalation: Overly broad file system write permissions could enable privilege escalation attacks. Allowing writes to directories containing executables in $PATH, system configuration directories, or user shell configuration files (.bashrc, .zshrc) could lead to code execution in a different security context when those files are accessed by other users or system processes.
• Linux Sandbox Strength: The Linux implementation provides strong file system and network isolation but includes an enableWeakerNestedSandbox mode to work in Docker environments without privileged namespaces. This option significantly weakens security and should only be used where additional isolation is enforced by other means.

Advanced Usage

Custom Proxy Configuration

For organizations requiring advanced network security, you can implement custom proxies to:

• Decrypt and inspect HTTPS traffic
• Apply custom filtering rules
• Log all network requests
• Integrate with existing security infrastructure

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Integration with Existing Security Tools

The sandboxed Bash tool works alongside:

• IAM Policies: Use with permission settings for defense in depth
• Development Containers: Use with devcontainers for additional isolation
• Enterprise Policies: Enforce sandbox configuration through managed settings

Best Practices

1. Start Restrictive: Begin with minimal permissions, expand as needed
2. Monitor Logs: Review sandbox violation attempts to understand CodeBuddy Code's needs
3. Use Environment-Specific Configuration: Different sandbox rules for development and production environments
4. Combine with Permissions: Use sandbox together with IAM policies for comprehensive security
5. Test Configuration: Verify your sandbox settings don't block legitimate workflows
6. Use Auto-Approval Cautiously: Only enable autoAllowBashIfSandboxed when you fully understand sandbox limitations

Open Source

The sandbox runtime is available as an open source npm package for your own agent projects. This enables the broader AI agent community to build safer, more reliable autonomous systems. This can also be used to sandbox other programs you may wish to run. For example, to sandbox an MCP server, you could run:

npx @anthropic-ai/sandbox-runtime <command-to-sandbox>

For implementation details and source code, visit the GitHub repository.

Limitations

• Performance Overhead: Minimal, but some file system operations may be slightly slower
• Compatibility: Some tools requiring specific system access patterns may need configuration adjustments, or may even need to run outside the sandbox
• Platform Support: Currently supports Linux and macOS; Windows support planned

Related Documentation

• Security - Comprehensive security features and best practices
• IAM - Permission configuration and access control
• Settings - Complete configuration reference

---

Let CodeBuddy Code work more autonomously in a secure sandbox 🛡️