> ## 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.

# Sandbox

> Restrict agent shell access to protect your system

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.                              |

The selected mode persists per project. The `explore` sub-agent always runs in sandboxed mode regardless of the project setting.

<Info>
  Sandboxed mode is supported on macOS and Linux. On Windows, only full-access mode is available.
</Info>

<Note>
  On Linux, sandboxed mode requires [Bubblewrap](https://github.com/containers/bubblewrap) (`bwrap`) and [socat](http://www.dest-unreach.org/socat/) to be installed (`sudo apt install bubblewrap socat`). Bubblewrap provides the sandbox container and socat handles network proxy bridging.
</Note>

## 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.

```json theme={null}
{
  "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.

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

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