《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 缓存。