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

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 current local Bash sandbox runs through sandbox-cli, using platform-specific isolation mechanisms:

• Linux: Uses bubblewrap (the bwrap command) for isolation. Linux namespaces and mount rules restrict the resources visible to the process. Dependency checks require bubblewrap, but no longer require the old backend's socat dependency.
• macOS: Uses Seatbelt through sandbox-cli for sandbox enforcement.
• Windows: Runs sandboxed commands through the Windows backend of sandbox-cli.

Platform support does not mean the sandbox is enabled. Actual isolation also depends on sandbox settings, host toggles, and the availability of runtime dependencies.

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.

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.

• 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

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: Supports Linux, macOS, and Windows. Dependencies and isolation capabilities may differ by platform; use /sandbox to check the current environment.

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 🛡️