《Cursor文檔》-sandbox.json 參考

通過 sandbox.json 文件配置 sandbox 的行爲，以控制網絡訪問、文件系統路徑等。

文件位置¶

將 sandbox.json 放在以下一個或兩個位置：

位置	適用範圍	優先級
`~/.cursor/sandbox.json`	所有工作區 (per-user)	較低
`<workspace>/.cursor/sandbox.json`	單個工作區 (per-repo)	較高

兩個文件均可選。兩者同時存在時會合並，並以 per-repo 設置爲準。企業版團隊團隊管理員策略和 Cursor 硬編碼的安全規則優先於這些設置，且無法通過任一文件削弱。

頂層字段¶

所有字段均爲可選。未指定的字段將使用下方所示的默認值。

字段	類型	默認值	描述
`type`	string	`"workspace_readwrite"`	沙盒模式。`"workspace_readwrite"` 允許讀寫工作區。`"workspace_readonly"` 限制爲只讀。`"insecure_none"` 會完全禁用沙盒。
`additionalReadwritePaths`	`string[]`	`[]`	智能體可讀寫的額外路徑。僅當 `type` 爲 `"workspace_readwrite"` 時生效。
`additionalReadonlyPaths`	`string[]`	`[]`	智能體可讀取的額外路徑。
`disableTmpWrite`	`boolean`	`false`	設爲 `true` 時，移除對 `/tmp` 和系統臨時目錄的默認寫入權限。
`enableSharedBuildCache`	`boolean`	`false`	將構建工具緩存 (npm、cargo、pip 等) 重定向到共享臨時目錄，使沙盒內外的命令共享同一緩存。

`networkPolicy` 對象¶

字段	類型	默認值	描述
`default`	`"allow"`	`"deny"`	`"deny"`	未匹配任何 allow/deny 規則時執行的操作。
`allow`	`string[]`	`[]`	要允許的模式。支持精確域名、通配符和 CIDR 表示法。
`deny`	`string[]`	`[]`	要拒絕的模式。優先級最高；始終阻止，即使某個模式也出現在 `allow` 中。

網絡匹配模式語法¶

allow 和 deny 數組支持三種模式格式：

格式	示例	匹配對象
精確域名	`"registry.npmjs.org"`	該精確主機
通配符	`"*.example.com"`	`example.com` 的任意子域名，包括 `example.com` 本身
CIDR	`"10.0.0.0/8"`	該範圍內的任意 IP 地址

關鍵規則：

拒絕規則始終優先於允許規則。如果主機同時匹配兩個列表，將被阻止。
私有/RFC 1918 地址 (10.x、172.16.x、192.168.x、127.x) 和雲元數據端點 (169.254.169.254) 默認會被阻止，以防止 SSRF。
IPv6 私有地址 (::1、fe80::/10、fc00::/7) 也會被阻止。
URL 路徑會被忽略；僅匹配域名或 IP 地址。

策略的合併方式¶

當存在多個策略來源時，將按優先級順序合併：

per-user  <  per-repo  <  team-admin  <  硬編碼
（最低）                                 （最高）

合併規則：

路徑 (additionalReadwritePaths, additionalReadonlyPaths)：合併所有來源中的路徑。
網絡允許列表：合併所有來源中的列表；若存在團隊管理員允許列表，則以其爲準。
網絡拒絕列表：始終合併所有來源中的列表。
networkPolicy.default："deny" 優先於 "allow"。
限制性布爾值 (disableTmpWrite, networkPolicyStrict)：true 優先。

受保護的路徑¶

無論 sandbox.json 如何配置，某些路徑始終禁止寫入：

.cursor/*.json, .cursor/**/*.json, .cursor/.workspace-trusted
.claude/*.json, .claude/**/*.json
.vscode/**
.code-workspace
.git/hooks/**, .git/config, .git/info/attributes
.cursorignore

以下 .cursor 子目錄可以寫入：rules/、commands/、worktrees/、skills/、agents/。

SSL 證書路徑和 ~/.ssh 始終可讀取。

環境變量¶

除上述配置外，Cursor 還會向沙盒中的子進程注入環境變量，包括 CURSOR_SANDBOX、CURSOR_ORIG_UID 和 CURSOR_ORIG_GID。完整列表及使用說明請參閱運行模式：環境變量。

示例¶

允許特定域名¶

{
  "networkPolicy": {
    "default": "deny",
    "allow": [
      "registry.npmjs.org",
      "pypi.org",
      "*.githubusercontent.com"
    ]
  }
}

默認禁止網絡訪問。僅可訪問列出的域名。

允許所有網絡訪問¶

{
  "networkPolicy": {
    "default": "allow"
  }
}

沙盒內允許所有出站網絡通信。

全棧 Web 項目¶

智能體需要安裝軟件包、拉取容器鏡像、訪問本地網絡中的數據庫，並讀取共享的 design-tokens 倉庫：

{
  "networkPolicy": {
    "default": "deny",
    "allow": [
      "registry.npmjs.org",
      "registry.yarnpkg.com",
      "pypi.org",
      "files.pythonhosted.org",
      "*.docker.io",
      "ghcr.io",
      "*.googleapis.com"
    ],
    "deny": [
      "*.internal.corp.example.com"
    ]
  },
  "additionalReadwritePaths": [
    "/home/me/.docker"
  ],
  "additionalReadonlyPaths": [
    "/opt/shared/design-tokens"
  ],
  "enableSharedBuildCache": true
}

此配置允許智能體：

安裝 npm/pip 軟件包並拉取 Docker 鏡像。
調用 Google Cloud API。
禁止訪問公司內部服務。
爲容器操作寫入 ~/.docker。
讀取 (但不能修改) 共享的 design-tokens 目錄。
在沙盒運行和非沙盒運行之間共享 npm/pip/cargo 緩存。