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

# 沙箱

> 限制代理的 shell 存取以保護您的系統

沙箱化的 bash 模式限制了 AI 代理執行 shell 指令的能力。啟用後，指令只能存取專案目錄和已核准的網路網域。所有專案預設為沙箱模式。

## 模式

輸入列中的沙箱模式選擇器讓您可以按專案切換兩種模式：

| 模式       | 說明                    |
| -------- | --------------------- |
| **沙箱**   | 指令僅限於存取專案目錄。網路請求需要核准。 |
| **完整存取** | 不受限制的 shell 存取，無沙箱限制。 |

所選模式按專案持久保留。無論專案設定為何，`explore` 子代理始終在沙箱模式下執行。

<Info>
  沙箱模式支援 macOS 和 Linux。在 Windows 上，僅可使用完整存取模式。
</Info>

<Note>
  在 Linux 上，沙箱模式需要安裝 [Bubblewrap](https://github.com/containers/bubblewrap)（`bwrap`）和 [socat](http://www.dest-unreach.org/socat/)（`sudo apt install bubblewrap socat`）。Bubblewrap 提供沙箱容器，socat 處理網路代理橋接。
</Note>

## 檔案系統限制

在沙箱模式下，指令的檔案系統存取受到限制：

**可讀取的路徑：**

* 專案目錄（完整讀寫）
* 暫存目錄（`/tmp`、`/private/tmp`）
* 家目錄下 `PATH` 中的工具二進位檔
* 全域技能目錄（`~/.bricks-project-desktop/skills/`）
* `sandbox.json` 中 `filesystem.allowRead` 列出的路徑

**可寫入的路徑：**

* 專案目錄
* 暫存目錄
* 全域技能目錄（`~/.bricks-project-desktop/skills/`）
* `sandbox.json` 中 `filesystem.allowWrite` 列出的路徑

家目錄根目錄預設被拒絕。嘗試存取允許清單以外路徑的指令將收到許可權錯誤。

在沙箱模式下，聊天輸入中使用 `@~/`（家目錄瀏覽）的檔案提及也會被封鎖。請改用專案相對路徑。

## 網路限制

在沙箱模式下，對外網路存取預設被封鎖。當沙箱化指令請求網路存取時，會出現包含三個選項的核准對話方塊：

* **僅允許一次** —僅在本工作階段中允許此請求
* **允許並儲存** —允許此請求並將網域加入 `sandbox.json` 供未來工作階段使用
* **拒絕** —封鎖此請求

## 沙箱設定

開啟**設定 > 代理 > 沙箱設定 > 開啟**以編輯 `sandbox.json`。此檔案讓您可以全域自訂沙箱許可權。

```json theme={null}
{
  "network": {
    "allowedDomains": [],
    "deniedDomains": [],
    "allowUnixSockets": [],
    "allowAllUnixSockets": false,
    "allowLocalBinding": false
  },
  "filesystem": {
    "allowRead": [],
    "allowWrite": [],
    "denyRead": [],
    "denyWrite": [],
    "allowGitConfig": false
  }
}
```

### 網路選項

| 欄位                    | 類型         | 說明              |
| --------------------- | ---------- | --------------- |
| `allowedDomains`      | `string[]` | 沙箱無需核准即可存取的網域   |
| `deniedDomains`       | `string[]` | 明確封鎖的網域         |
| `allowUnixSockets`    | `string[]` | 允許的 Unix 通訊端路徑  |
| `allowAllUnixSockets` | `boolean`  | 允許所有 Unix 通訊端連線 |
| `allowLocalBinding`   | `boolean`  | 允許綁定至本機埠        |

### 檔案系統選項

| 欄位               | 類型         | 說明                  |
| ---------------- | ---------- | ------------------- |
| `allowRead`      | `string[]` | 額外可讀取的路徑（支援 `~` 展開） |
| `allowWrite`     | `string[]` | 額外可寫入的路徑（支援 `~` 展開） |
| `denyRead`       | `string[]` | 明確封鎖的讀取路徑           |
| `denyWrite`      | `string[]` | 明確封鎖的寫入路徑           |
| `allowGitConfig` | `boolean`  | 允許存取 git 設定檔案       |

## 自動核准 bash 指令

**設定 > 代理**中的**自動核准 bash 指令**開關控制完整存取 bash 指令和受信任的 `bricks devtools` 指令是否無需確認即可執行。此設定與沙箱模式無關——無論是否啟用自動核准，沙箱化指令始終在沙箱內執行。

當自動核准開啟時，單純的 `bricks devtools` 呼叫會靜默執行，因為它們需要直接存取沙箱無法授予的 LAN。將 `bricks devtools` 與其他指令組合的 shell 鏈（例如 `cd /path && bricks devtools scan` 或 `bricks devtools scan | jq .`）也會逃出沙箱，但它們始終會顯示核准提示——即使啟用了自動核准——讓您每次都能確認完整的組合指令。

## 危險指令偵測

CTOR 會掃描每個 `bash` 呼叫是否符合高影響力模式。一旦偵測到，核准卡片會以紅色邊框、⚠ 圖示和**危險指令**標籤強調顯示，並一律出現提示——自動核准會被略過，沙箱模式也會回退為確認閘門。沙箱本身無法封鎖這些模式，因為專案目錄樹依設計可寫入（因此 `rm -rf <project>/...` 在沙箱內仍會成功）。

偵測器會標記下列類別的指令：

* 權限提升：`sudo`、`doas`、`su`
* 系統電源狀態：`shutdown`、`reboot`、`halt`、`poweroff`、`init`
* 磁碟格式化或分割：`mkfs.*`、`fdisk`、`sfdisk`、`parted`、`diskutil`
* 原始磁碟寫入：帶有 `of=` 目標的 `dd`
* 安全刪除：`shred`、`srm`、`wipe`
* 遞迴移除：`rm -r`、`rm -R`、`rm --recursive`
* 遞迴權限或擁有者變更：`chmod -R`、`chown -R`
* 終止 PID 1：`kill 1`、`pkill 1`、`killall 1`
* 改寫歷史的 git：`git push --force` / `-f`、`git reset --hard`、`git clean -f`、`git branch -D`、`git checkout .`、`git restore .`
* 遠端執行管道：`curl ... | sh`、`wget ... | bash`，包含 `| sudo sh`
* 任意 shell 字串：`bash -c`、`sh -c`、`zsh -c`，以及其他帶有 `-c` 的 shell 直譯器

偵測會逐段巡查 shell 鏈，因此即使危險片段不是開頭指令，`cd /tmp && rm -rf x` 或 `curl ... | sudo bash` 仍會被攔截。較安全的變體不會被標記：`git push --force-with-lease`、`git branch -d`（僅移除已合併的分支），以及對非 init PID 的 `kill` 都會正常執行。

## 資料儲存

| 資料    | 位置                                               |
| ----- | ------------------------------------------------ |
| 每專案模式 | `~/.bricks-project-desktop/project-sandbox.json` |
| 沙箱設定  | `~/.bricks-project-desktop/sandbox.json`         |