Sandbox

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.

This sandbox governs CTOR’s own built-in agent only. A chat backed by a CLI agent (Claude Code, Codex, Pi, Cursor Agent) runs outside it, with the same file and shell access it would have in your terminal.

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.

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, Linux, and Windows. Windows support is experimental — see Windows.

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.

Windows

Windows support is experimental. Sandboxed mode works, with a few platform differences:

The agent’s commands run in PowerShell, not a POSIX shell. Which one follows your Terminal shell profile: a WSL profile runs full-access commands inside the distro with bash, PowerShell 7 uses pwsh.exe, and everything else uses Windows PowerShell 5.1. The agent is told which shell is active so it writes syntax that shell accepts.
Sandboxed commands always use Windows PowerShell 5.1, even under a WSL profile — the sandbox can’t fence a WSL distro. Switch the project to full-access if a command has to run inside WSL.
Filesystem grants apply per session, not per command. They are stamped as NTFS permissions when the sandbox starts, and CTOR restarts the sandbox session when the granted set changes.
The home directory is denied structurally rather than through an explicit deny rule. Entries in sandbox.json under denyRead / denyWrite still apply where they sit inside a granted directory.

If the sandbox can’t start, Settings > Agent > Sandbox settings reports what is missing.

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-program commands run without a confirmation prompt. This setting is independent of sandbox mode — sandboxed commands always run within the sandbox regardless of auto-approve.

Trusted programs

A few programs need direct access the sandbox can’t grant, so CTOR lets them escape it:

bricks devtools — needs direct LAN access to reach devices.
agent-browser — needs the local browser-tab CDP bridge to drive your open browser tabs. The bunx agent-browser and bun x agent-browser forms are trusted too.

A bare invocation of a trusted program — or a read-only chain such as agent-browser snapshot | jq . — runs with the access it needs, and runs silently when auto-approve is on. Shell chains that combine a trusted program with other commands (for example, cd /path && bricks devtools scan) 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

Data	Location
Per-project mode	`~/.bricks-project-desktop/project-sandbox.json`
Sandbox config	`~/.bricks-project-desktop/sandbox.json`

Getting started

Working with projects

Ship your app

Reference

Changelog

Modes

Windows

Filesystem restrictions

Network restrictions

Sandbox settings

Network options

Filesystem options

Auto-approve bash commands

Trusted programs

Dangerous command detection

Data storage

​Modes

​Windows

​Filesystem restrictions

​Network restrictions

​Sandbox settings

​Network options

​Filesystem options

​Auto-approve bash commands

​Trusted programs

​Dangerous command detection

​Data storage

Modes

Windows

Filesystem restrictions

Network restrictions

Sandbox settings

Network options

Filesystem options

Auto-approve bash commands

Trusted programs

Dangerous command detection

Data storage