Docker Sandboxes

本地网络规则在你的预设之上允许或阻止目标地址。你可以 为所有沙箱添加规则，或只为某个沙箱添加；可以把规则限定到 HTTP 方法和路径；也可以 移除不再需要的规则。有关规则接受的主机模式，请参阅 网络和 HTTP 规则语法。

允许或阻止一个目标地址 ​

用 sbx policy allow 和 sbx policy deny 在当前生效的预设之上添加或限制 访问。变更立即生效。规则默认适用于所有沙箱：

console
$ sbx policy allow network api.anthropic.com
$ sbx policy deny network ads.example.com

用逗号分隔的列表在一条命令中指定多个主机：

console
$ sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org"

为某个沙箱允许或阻止一个目标地址 ​

传入 --sandbox <name> 可以把规则限定到某个沙箱：

console
$ sbx policy allow network --sandbox my-sandbox api.example.com
$ sbx policy deny network --sandbox my-sandbox ads.example.com

你也可以在创建沙箱时为它添加拒绝规则，在 sbx create 或 sbx run 上使用 --deny-network：

console
$ sbx create --deny-network ads.example.com claude .
$ sbx run --deny-network ads.example.com claude

多次传入该标志可以拒绝多个主机。以这种方式添加的规则会出现在 sbx policy ls <name> 中，就像其他限定到该沙箱的规则一样。

要阻止某个 Kit 允许的目标地址，为使用该 Kit 的沙箱添加一条拒绝规则。拒绝规则优先于 该 Kit 的允许规则：

console
$ sbx policy deny network --sandbox my-sandbox openrouter.ai

删除沙箱时，限定到它的规则也会一并删除。

允许或阻止 HTTP 方法和路径 ​

前面各节中的规则匹配整个主机。而 HTTP 规则改为匹配主机上特定的 HTTP 方法和路径， 因此你可以允许或阻止特定的 API 请求。例如，你可以让智能体读取某个 API，却不允许它 写入。

在允许或拒绝规则上添加 --method 可以匹配特定的 HTTP 方法，添加 --path 可以把它 限定到主机 URL 空间的一部分。请给路径加上引号，以免 shell 展开通配符：

console
$ sbx policy allow network api.github.com --method GET --path '/repos/org/project/**'

写主机名时不要带 scheme，例如写 api.github.com 而不是 https://api.github.com。 它遵循与网络规则相同的模式，也可以包含端口，但必须是主机名。要匹配 IP 地址或 CIDR 范围，请使用不带 --method 或 --path 的网络规则。

路径以及查询参数的名称和值都会忽略 ASCII 字母的大小写。有关示例和通配符行为，请参阅 HTTP 规则。

选择方法 ​

用逗号分隔的列表传入多个方法，或者用 ANY 匹配所有方法。方法名称不区分大小写， ANY 不能与特定方法组合使用：

console
$ sbx policy allow network api.github.com --method GET,HEAD

可用的方法有 GET、HEAD、POST、PUT、PATCH、DELETE、OPTIONS、 CONNECT 和 TRACE。

选择路径 ​

不带 --path 的规则匹配主机上的每个路径。一条规则只接受一个路径，而路径需要搭配 方法。重复传入 --path 只会保留最后一个值，逗号会被当作路径的一部分读取，因此每个 路径都要添加一条单独的规则：

console
$ sbx policy allow network api.github.com --method GET --path '/repos/**'
$ sbx policy allow network api.github.com --method GET --path '/users/**'

路径必须以 / 开头，并且是规范形式。有关完整的路径规则，请参阅 HTTP 方法和路径。

匹配查询参数 ​

添加 --query 可以要求 URL 查询参数，它与路径分开计算。重复传入该标志可以要求多个 参数。与路径一样，查询限制也需要搭配方法，因此请保留 --method，或者使用 --method ANY：

console
$ sbx policy allow network api.example.com --method GET --path '/search' \
    --query 'team=platform' --query 'label=release*'

有关值的模式和匹配行为，请参阅 查询参数。

阻止已允许主机的部分内容 ​

要限制主机的部分内容，在一条更宽泛的允许规则之上添加一条使用相同标志的拒绝规则：

console
$ sbx policy allow network api.example.com
$ sbx policy deny network api.example.com --method POST --path '/admin/**'

移除规则 ​

按资源或按规则 ID 移除规则：

console
$ sbx policy rm network --resource ads.example.com
$ sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67

要移除限定到某个沙箱的规则，传入 --sandbox <name>：

console
$ sbx policy rm network --sandbox my-sandbox --resource api.example.com

要移除 HTTP 规则，请指定添加它时所用的相同方法、路径以及所有 --query 标志，或者 使用它的规则 ID：

console
$ sbx policy rm network --resource api.example.com --method GET --path '/search' \
    --query 'team=platform' --query 'label=release*'

要查找规则的 ID，运行 sbx policy ls --wide。有关更多细节，请参阅 检查策略状态和规则。

允许出站 UDP ​

出站 UDP 是实验性功能，默认关闭。在添加 UDP 允许规则之前，先开启实验特性和 UDP 出站。如果在 UDP 出站关闭时保存 UDP 规则，CLI 会给出警告：

console
$ sbx settings set platform.allowExperimentalFeatures true
$ sbx settings set feature.udp-egress true
$ sbx policy allow network --protocol udp api.example.com:443

本地允许规则默认适用于 TCP。UDP 使用 --protocol udp，两者都用则使用 --protocol tcp,udp。拒绝规则默认适用于两种协议，而 --protocol 可以把拒绝规则 限定为其中一种。UDP 规则遵循与 TCP 规则相同的组织和本地优先级。

有些 UDP 流量无论你的规则允许什么都会被阻止：

  • 发往需要 HTTP、SOCKS5、系统或 PAC 代理的目标地址的流量，因为这些代理无法承载 UDP。
  • 发往本地网络目标地址的流量，包括组播、链路本地和未指定地址、255.255.255.255， 以及宿主机各网络的广播地址。该阻止在评估任何策略之前就已生效，因此即使有一条 允许所有主机的规则也不会放行，沙箱中的 mDNS 和 SSDP 等发现协议也无法工作。发往 host.docker.internal 的 UDP 不受影响。网络日志会在规则 <udp local network boundary> 下记录这些连接。

要列出 UDP 规则或检查某个目标地址：

console
$ sbx policy ls --protocol udp
$ sbx policy check network --protocol udp api.example.com:443

当 UDP 出站被禁用时，每个沙箱网络会把前 20 个被拒绝的不同外部 UDP 目标地址分别 记录在各自的日志条目中。后续的目标地址共用 <further blocked attempts> 条目。对 前 20 个目标地址之一的重复尝试仍会更新该目标地址的计数。该限制在网络生命周期内有效， 每个网络都有自己的限制。所有这些 UDP 尝试仍然被阻止。

设置或重置预设 ​

如果尚未设置预设，CLI 会在你在交互式终端中运行沙箱时提示你选择一个。有关更多细节， 请参阅从预设开始。要在不通过提示的情况下设置预设， 或者用新预设重新开始，请使用 sbx policy init 或 sbx policy reset。

不通过提示设置预设 ​

在 CI 流水线或无头服务器等非交互式环境中，CLI 无法提示你，因此在设置预设之前， sbx run 等命令会返回错误。在运行沙箱之前，用 sbx policy init 设置预设：

console
$ sbx policy init balanced

可用值为 allow-all（Open）、balanced（Balanced）和 deny-all（Locked Down）。 sbx policy init 只在尚未设置预设时有效。要在此之后更改预设，请重置本地策略。

重置本地策略 ​

要移除所有自定义规则并用新预设重新开始，请使用 sbx policy reset：

console
$ sbx policy reset

它会删除本地策略存储、重启守护进程，并提示你选择新的预设。正在运行的沙箱会随着守护 进程关闭而停止。传入 --force 可以跳过确认提示：

console
$ sbx policy reset --force

WARNING

sbx policy reset 会删除所有本地配置的策略规则，包括你批准过的任何目标地址。 沙箱下次访问这些目标地址时会再次请求。若要在不删除本地规则的情况下应用组织策略 变更，请改用 sbx policy refresh。有关更多细节，请参阅 组织策略变更没有生效。