Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt

Use this file to discover all available pages before exploring further.

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:
ModeDescription
SandboxedCommands are restricted to the project directory. Network requests require approval.
Full-AccessUnrestricted shell access with no sandbox restrictions.
The selected mode persists per project. The 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

FieldTypeDescription
allowedDomainsstring[]Domains the sandbox can access without approval
deniedDomainsstring[]Explicitly blocked domains
allowUnixSocketsstring[]Allowed Unix socket paths
allowAllUnixSocketsbooleanAllow all Unix socket connections
allowLocalBindingbooleanAllow binding to local ports

​
Filesystem options

FieldTypeDescription
allowReadstring[]Additional readable paths (supports ~ expansion)
allowWritestring[]Additional writable paths (supports ~ expansion)
denyReadstring[]Explicitly blocked read paths
denyWritestring[]Explicitly blocked write paths
allowGitConfigbooleanAllow 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. Bare bricks devtools invocations run silently when auto-approve is on, because they need direct LAN access the sandbox can’t grant. Shell chains that combine bricks devtools with other commands (for example, cd /path && bricks devtools scan or bricks devtools scan | jq .) also escape the sandbox, but they always surface an approval prompt — even when auto-approve is enabled — so you confirm the full composition each time.

​
Dangerous command detection

CTOR scans every bash invocation for high-impact patterns. When one is detected, the approval card is highlighted with a red border, a ⚠ icon, and a Dangerous label, and the prompt always appears — auto-approve is bypassed, and sandboxed mode falls back to a confirmation gate too. The sandbox cannot block these patterns on its own because the project tree is writable by design (so rm -rf <project>/... would still succeed inside the sandbox). The detector flags commands in the following categories:
  • Privilege escalation: sudo, doas, su
  • System power state: shutdown, reboot, halt, poweroff, init
  • Disk formatting or partitioning: mkfs.*, fdisk, sfdisk, parted, diskutil
  • Raw disk writes: dd with an of= target
  • Secure deletion: shred, srm, wipe
  • Recursive remove: rm -r, rm -R, rm --recursive
  • Recursive permission or ownership changes: chmod -R, chown -R
  • Killing PID 1: kill 1, pkill 1, killall 1
  • History-rewriting git: git push --force / -f, git reset --hard, git clean -f, git branch -D, git checkout ., git restore .
  • Remote execution pipes: curl ... | sh, wget ... | bash, including | sudo sh
  • Arbitrary shell strings: bash -c, sh -c, zsh -c, and other shell interpreters with -c
Detection walks each segment of a shell chain, so cd /tmp && rm -rf x or curl ... | sudo bash are caught even when the dangerous segment is not the leading command. Safer variants stay unflagged: git push --force-with-lease, git branch -d (only removes merged branches), and kill of any non-init PID run normally.

​
Data storage

DataLocation
Per-project mode~/.bricks-project-desktop/project-sandbox.json
Sandbox config~/.bricks-project-desktop/sandbox.json