Sandboxed bash mode restricts what the AI agent can do with shell commands. When enabled, commands can only access the project directory and approved network domains. All projects default to sandboxed mode.
Modes
The sandbox mode selector in the input bar lets you switch between two modes per project:
| Mode | Description |
|---|
| Sandboxed | Commands are restricted to the project directory. Network requests require approval. |
| Full-Access | Unrestricted shell access with no sandbox restrictions. |
explore sub-agent always runs in sandboxed mode regardless of the project setting.
Sandboxed mode is supported on macOS and Linux. On Windows, only full-access mode is available.
On Linux, sandboxed mode requires Bubblewrap (bwrap) and socat to be installed (sudo apt install bubblewrap socat). Bubblewrap provides the sandbox container and socat handles network proxy bridging. Filesystem restrictions
In sandboxed mode, commands have limited filesystem access:
Readable paths:
- Project directory (full read/write)
- Temp directories (
/tmp, /private/tmp)
- Tool binaries in your
PATH under the home directory
- Global skills directory (
~/.bricks-project-desktop/skills/)
- Paths listed in
sandbox.json under filesystem.allowRead
Writable paths:
- Project directory
- Temp directories
- Global skills directory (
~/.bricks-project-desktop/skills/)
- Paths listed in
sandbox.json under filesystem.allowWrite
The home directory root is denied by default. Commands that attempt to access paths outside the allowed list receive a permission error.
File mentions using @~/ (home directory browsing) are also blocked in the chat input when sandboxed. Use project-relative paths instead.
Network restrictions
In sandboxed mode, outbound network access is blocked by default. When a sandboxed command requests network access, an approval dialog appears with three options:
- Allow once — permits the request for this session only
- Allow & save — permits the request and adds the domain to
sandbox.json for future sessions
- Deny — blocks the request
Sandbox settings
Open Settings > Agent > Sandbox settings > Open to edit sandbox.json. This file lets you customize sandbox permissions globally.
{
"network": {
"allowedDomains": [],
"deniedDomains": [],
"allowUnixSockets": [],
"allowAllUnixSockets": false,
"allowLocalBinding": false
},
"filesystem": {
"allowRead": [],
"allowWrite": [],
"denyRead": [],
"denyWrite": [],
"allowGitConfig": false
}
}
Network options
| Field | Type | Description |
|---|
allowedDomains | string[] | Domains the sandbox can access without approval |
deniedDomains | string[] | Explicitly blocked domains |
allowUnixSockets | string[] | Allowed Unix socket paths |
allowAllUnixSockets | boolean | Allow all Unix socket connections |
allowLocalBinding | boolean | Allow binding to local ports |
Filesystem options
| Field | Type | Description |
|---|
allowRead | string[] | Additional readable paths (supports ~ expansion) |
allowWrite | string[] | Additional writable paths (supports ~ expansion) |
denyRead | string[] | Explicitly blocked read paths |
denyWrite | string[] | Explicitly blocked write paths |
allowGitConfig | boolean | Allow access to git configuration files |
Auto-approve bash commands
The Auto-approve bash commands toggle in Settings > Agent controls whether full-access bash commands and trusted bricks devtools commands run without a confirmation prompt. This setting is independent of sandbox mode — sandboxed commands always run within the sandbox regardless of auto-approve.
Data storage
| Data | Location |
|---|
| Per-project mode | ~/.bricks-project-desktop/project-sandbox.json |
| Sandbox config | ~/.bricks-project-desktop/sandbox.json |
