跳轉到主要內容

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.

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

​
模式

輸入列中的沙箱模式選擇器讓您可以按專案切換兩種模式：
模式說明
沙箱指令僅限於存取專案目錄。網路請求需要核准。
完整存取不受限制的 shell 存取，無沙箱限制。
所選模式按專案持久保留。無論專案設定為何，explore 子代理始終在沙箱模式下執行。
沙箱模式支援 macOS 和 Linux。在 Windows 上，僅可使用完整存取模式。
在 Linux 上，沙箱模式需要安裝 Bubblewrap（bwrap）和 socat（sudo apt install bubblewrap socat）。Bubblewrap 提供沙箱容器，socat 處理網路代理橋接。

​
檔案系統限制

在沙箱模式下，指令的檔案系統存取受到限制： 可讀取的路徑：
  • 專案目錄（完整讀寫）
  • 暫存目錄（/tmp、/private/tmp）
  • 家目錄下 PATH 中的工具二進位檔
  • 全域技能目錄（~/.bricks-project-desktop/skills/）
  • sandbox.json 中 filesystem.allowRead 列出的路徑
可寫入的路徑：
  • 專案目錄
  • 暫存目錄
  • 全域技能目錄（~/.bricks-project-desktop/skills/）
  • sandbox.json 中 filesystem.allowWrite 列出的路徑
家目錄根目錄預設被拒絕。嘗試存取允許清單以外路徑的指令將收到許可權錯誤。 在沙箱模式下，聊天輸入中使用 @~/（家目錄瀏覽）的檔案提及也會被封鎖。請改用專案相對路徑。

​
網路限制

在沙箱模式下，對外網路存取預設被封鎖。當沙箱化指令請求網路存取時，會出現包含三個選項的核准對話方塊：
  • 僅允許一次 —僅在本工作階段中允許此請求
  • 允許並儲存 —允許此請求並將網域加入 sandbox.json 供未來工作階段使用
  • 拒絕 —封鎖此請求

​
沙箱設定

開啟設定 > 代理 > 沙箱設定 > 開啟以編輯 sandbox.json。此檔案讓您可以全域自訂沙箱許可權。 
{
  "network": {
    "allowedDomains": [],
    "deniedDomains": [],
    "allowUnixSockets": [],
    "allowAllUnixSockets": false,
    "allowLocalBinding": false
  },
  "filesystem": {
    "allowRead": [],
    "allowWrite": [],
    "denyRead": [],
    "denyWrite": [],
    "allowGitConfig": false
  }
}

​
網路選項

欄位類型說明
allowedDomainsstring[]沙箱無需核准即可存取的網域
deniedDomainsstring[]明確封鎖的網域
allowUnixSocketsstring[]允許的 Unix 通訊端路徑
allowAllUnixSocketsboolean允許所有 Unix 通訊端連線
allowLocalBindingboolean允許綁定至本機埠

​
檔案系統選項

欄位類型說明
allowReadstring[]額外可讀取的路徑（支援 ~ 展開）
allowWritestring[]額外可寫入的路徑（支援 ~ 展開）
denyReadstring[]明確封鎖的讀取路徑
denyWritestring[]明確封鎖的寫入路徑
allowGitConfigboolean允許存取 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