Overview
CodeBuddy Code features native sandboxing, providing a safer environment for agent execution while reducing persistent permission prompts. Instead of requesting permission for each bash command, the sandbox predefines boundaries that allow CodeBuddy Code to work more freely with reduced risk. The sandboxed Bash tool uses OS-level primitives to enforce file system and network isolation.
Why Sandboxes Matter
Traditional permission-based security requires continuous user approval to execute bash commands. While this provides control, it can lead to:
Approval fatigue: Repeatedly clicking "Approve" can cause users to pay less attention to what they are approving.
Reduced productivity: Constant interruptions can slow down development workflows.
Limited autonomy: CodeBuddy Code cannot work efficiently while waiting for approval.
The sandbox addresses these challenges in the following ways:
1. Clearly defined boundaries: Specify which directories and network hosts CodeBuddy Code can access.
2. Fewer permission prompts: Safe commands within the sandbox do not require approval.
3. Maintain security: Attempts to access resources outside the sandbox immediately trigger a notification.
4. Achieve autonomy: CodeBuddy Code can operate more independently within defined limits.
Note:
An effective sandbox requires both file system and network isolation. Without network isolation, a compromised agent may steal sensitive files such as SSH keys. Without file system isolation, a compromised agent may backdoor system resources to gain network access. When a sandbox is configured, it is important to ensure that your configuration settings do not 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: Has read and write access to the current working directory and its subdirectories.
Default read behavior: Has read access to the entire computer, except for certain denied directories.
Block access: Files outside the current working directory cannot be modified without explicit permission.
Configurable: Define custom allow and deny paths through settings.
Network Isolation
Network access is controlled by a proxy server running outside the sandbox:
Domain restriction: Only approved domains can be accessed.
User confirmation: New domain requests trigger a permission prompt.
Custom proxy support: Advanced users can enforce custom rules for outbound traffic.
Comprehensive coverage: Restrictions apply to all scripts, programs, and subprocesses generated by commands.
OS-Level Enforcement
The sandboxed Bash tool leverages operating system security primitives:
macOS: Uses Seatbelt for sandbox enforcement.
These operating system-level restrictions ensure that all subprocesses spawned by CodeBuddy Code commands inherit the same security boundary.
Getting Started
Enabling the Sandbox
You can enable the sandbox by running the /sandbox slash command:
This activates the sandboxed Bash tool with default settings, allowing access to the current working directory while blocking access to sensitive system locations.
Configuring the Sandbox
Customize sandbox behavior through the settings.json file. For a complete configuration reference, see Settings.
Note:
Not all commands work with the sandbox out of the box. The following considerations can help you get the most out of the sandbox:
Many CLI tools need access to certain hosts. When you use these tools, they request permission to access those hosts. Granting permission allows 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 are 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.
CodeBuddy Code includes an intentional escape hatch mechanism that allows commands to run outside the sandbox when necessary. When a command fails due to sandbox restrictions, such as network connectivity issues or incompatible tools, CodeBuddy is prompted to analyze the failure and may retry the command with the `dangerouslyDisableSandbox` parameter. Commands using this parameter go through the normal CodeBuddy Code permission flow and require 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 the sandbox settings. Once disabled, the dangerouslyDisableSandbox parameter is completely ignored, and all commands must run in the sandbox or be explicitly listed in excludedCommands. Automatic Sandbox Approval
In AcceptEdits permission mode, CodeBuddy Code provides an automatic sandbox approval feature to further reduce permission prompts:
How It Works
When automatic sandbox approval is enabled, Bash commands that meet all of the following conditions are automatically approved for execution without user confirmation:
1. Currently in AcceptEdits permission mode
2. Sandbox is enabled (sandbox.enabled = true).
3. Automatic approval is enabled (sandbox.autoAllowBashIfSandboxed = true).
4. The command will run in the sandbox (not in the excludedCommands list).
5. The dangerouslyDisableSandbox parameter is not used
Configuration Example
Enable automatic sandbox approval in .codebuddy/settings.json:
{
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true,
"excludedCommands": ["git", "docker"]
}
}
Use Cases
Automatic approval (no user confirmation required):
npm test
npm run build
ls -la
grep "pattern" file.txt
Approval required (user confirmation is still required in the following cases):
Automatic Sandbox Bypass in Bypass Permission Mode
When a command attempts to cross the sandbox boundary (for example, writing to .git/refs/*.lock or the model invoking Bash with dangerouslyDisableSandbox=true), the sandbox prompts for a second approval asking whether to run this command outside the sandbox.
Starting from v2.90.x, in bypassPermissions mode, such sandbox escape approvals are automatically granted for non-high-risk commands, preventing routine combined commands like cd X && yarn build from repeatedly triggering approvals:
Auto-allow: When the command security level is SAFE, LOW, or MEDIUM, execution continues directly with allow_once.
Still requires confirmation: When the command security level is HIGH / CRITICAL (such as rm -rf / or chmod 777 /etc), interactive approval is retained even in bypass mode.
This policy is semantically consistent with the protection of dangerous Bash commands in bypass mode: bypassPermissions does not mean unconditional approval, and high-risk operations always require explicit confirmation.
Security Assurance
Automatic sandbox approval improves efficiency while maintaining security:
Only within the sandbox environment: Only sandboxed commands can be automatically approved.
File system isolation: Commands can only access permitted directories.
Network isolation: Commands can only access approved domains.
Configurable boundary: Exclude high-risk commands through excludedCommands.
Security first: Any configuration error or exception falls back to requiring user approval.
Tips
1. Use with caution: Enable automatic approval only when you understand the sandbox limitations.
2. Exclude high-risk commands: Add dangerous operations such as git push and rm -rf to excludedCommands.
3. Periodic review: Check logs to see which commands were automatically approved.
4. Combined use: Use it together with IAM permission rules to provide defense in depth.
Security Benefits
Preventing Prompt Injection
Even if an attacker successfully manipulates CodeBuddy Code's behavior through prompt injection, the sandbox ensures that your system remains secure:
File system protection:
Critical configuration files cannot be modified, such as ~/.bashrc.
System-level files in /bin/ cannot be modified.
CodeBuddy configuration files (settings.json and settings.local.json) cannot be modified, preventing sandbox escape through hook injection.
Network protection:
Data cannot be exfiltrated to an attacker-controlled server.
Malicious scripts cannot be downloaded from unauthorized domains.
Unexpected API calls cannot be made to unapproved services.
No domains that are not explicitly allowed can be contacted.
Monitoring and control:
All attempts to access outside the sandbox are blocked at the operating system level.
You are notified immediately when a boundary is tested.
You can choose to deny, allow once, or permanently allow the configuration update.
Configuration File Protection
The sandbox blocks writes to CodeBuddy configuration files by default to prevent sandbox escape attacks. An attacker may use prompt injection to make the Agent write to settings.json and inject malicious SessionStart hooks, which 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 is also applied to Bash commands and file editing tools (Write, Edit, and MultiEdit), ensuring that the sandbox's denyWrite rule takes effect consistently across all tools.
Reducing the Attack Surface
The sandbox limits the following potential damage:
Malicious dependencies: NPM packages or other dependencies that contain harmful code
Compromised scripts: Build scripts or tools that contain security vulnerabilities
Social engineering: Attacks that trick users into running dangerous commands.
Prompt injection: Attacks that trick CodeBuddy into running dangerous commands
Transparent Operations
When CodeBuddy Code attempts to access network resources outside the sandbox:
1. The operation is blocked at the operating system level.
2. You are notified immediately.
3. You can choose from the following options:
Deny the request.
Allow once.
Update the sandbox configuration to permanently allow it.
Security Limitations
Network sandbox restrictions: The network filtering system operates by restricting the domains that processes are allowed to connect to. It does not inspect traffic that is routed through a proxy, and users are responsible for ensuring that they only allow trusted domains in their policies.
Note:
Users should be aware of the risks associated with allowing broad domains such as github.com, which may enable data exfiltration. Additionally, in some cases, network filtering may be bypassed through domain fronting. Privilege escalation via Unix sockets: The allowUnixSockets configuration may inadvertently grant access to powerful system services, which could lead to sandbox bypass. For example, if it is used to allow access to /var/run/docker.sock, this effectively grants access to the host system by exploiting 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 may enable privilege escalation attacks. Allowing writes to directories containing executables in $PATH, system configuration directories, or user shell configuration files (.bashrc, .zshrc) may lead to code execution in a different security context when other users or system processes access these files.
Linux sandbox strength: The Linux implementation provides strong file system and network isolation, but includes an enableWeakerNestedSandbox mode that allows it to work in Docker environments without privileged namespaces. This option significantly weakens security and should only be used when additional isolation is enforced by other means.
Advanced Usage
Custom Proxy Configuration
For organizations that require advanced network security, you can implement a custom proxy 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
}
}
}
Integrating with Existing Security Tools
The sandboxed Bash tool works in conjunction with the following tools:
Development containers: Use with devcontainers to achieve additional isolation.
Enterprise policy: Enforce sandbox configurations through admin settings. Tips
1. Start restrictive: Begin with least privilege and expand as needed.
2. Monitor logs: Review sandbox violation attempts to understand the requirements of CodeBuddy Code.
3. Use environment-specific configurations: Use different sandbox rules for development and production environments.
4. Combine with permissions: Use the sandbox together with IAM policies to achieve comprehensive security.
5. Test configuration: Verify that your sandbox settings do not block legitimate workflows.
6. Use automatic approval with caution: Enable autoAllowBashIfSandboxed only when you fully understand the 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 and more reliable autonomous systems. It can also be used to sandbox other programs you may want to run. For example, to sandbox an MCP server, you can run:
npx @anthropic-ai/sandbox-runtime <command-to-sandbox>
Limit
Performance overhead: Minimal, but some file system operations may be slightly slower.
Compatibility: Some tools that require specific system access patterns may need configuration adjustments or may even need to run outside the sandbox.
Platform support: Currently supports Linux and macOS, with Windows support planned.
References
Security - Comprehensive security features and practical tutorials. IAM - Permission configuration and access control. Settings - Complete configuration reference.