开始使用
sandbox.json 参考
通过 sandbox.json 文件配置 sandbox 的行为，以控制网络访问、文件系统路径等。
文件位置
将 sandbox.json 放在以下一个或两个位置：
| 位置 | 适用范围 | 优先级 |
|---|---|---|
~/.cursor/sandbox.json | 所有工作区 (per-user) | 较低 |
<workspace>/.cursor/sandbox.json | 单个工作区 (per-repo) | 较高 |
两个文件均可选。两者同时存在时会合并，并以 per-repo 设置为准。企业版团队 团队管理员 策略和 Cherri Code 硬编码的安全规则优先于这些设置，且无法通过任一文件削弱。
顶层字段
所有字段均为可选。未指定的字段将使用下方所示的默认值。
| 字段 | 类型 | 默认值 | 描述 |
|---|---|---|---|
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 | 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 始终可读取。
环境变量
除上述配置外，Cherri Code 还会向沙盒中的子进程注入环境变量，包括 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 缓存。