Docker Sandboxes

本页介绍的是本地沙箱。有关云端行为及其限制，请参阅对比本地沙箱与云沙箱。

本页介绍 Docker Sandboxes 的内部工作原理。有关该架构的安全特性，请参阅 沙箱隔离。

工作区存储 ​

从 sbx 0.42.0 版本开始，sbx create 的工作区路径是可选的。省略该路径时， 沙箱将没有宿主机工作区绑定挂载。沙箱会使用模板镜像中配置的 WORKDIR 作为 默认工作目录。Docker 提供的智能体模板将 WORKDIR 设置为 /home/agent/workspace。 自定义模板可以设置其他绝对路径。如果守护进程无法从镜像配置中解析出可用的绝对 WORKDIR，则回退到 /home/agent/workspace。在该目录中创建的文件会保留在沙箱内， 并在停止和重启后依然存在。

当你向 sbx create 或 sbx run 传入工作区路径时，该目录会通过文件系统透传 挂载到沙箱中。未传入路径时，sbx run 会使用当前目录。沙箱看到的就是你在宿主机 上的真实文件，因此任何一方向的改动都是即时生效的，不涉及任何同步过程。

默认情况下，直接挂载的工作区在沙箱中呈现的绝对路径与宿主机上相同。保留绝对路径 意味着错误信息、配置文件和构建产物引用的都是你在宿主机上能找到的路径。智能体看到的 目录结构保持一致，这能减少调试或审查改动时的困惑。你可以为 额外的工作区选择不同的沙箱内路径。

克隆模式使用第三种存储布局。宿主机上的仓库会以只读方式挂载到 /run/sandbox/source， 智能体则在沙箱内的一份私有克隆中工作。参见克隆模式。

WARNING

不要把网络挂载的存储或远程存储（网络驱动器、SMB/NFS 共享或云同步文件夹）作为 工作区挂载。沙箱通过文件系统透传访问工作区，因此每一次文件读写都要经过网络。 这会增加延迟并降低智能体性能。

存储与持久化 ​

创建沙箱后，其中的所有内容都会一直保留，直到你将其删除：智能体构建或拉取的 Docker 镜像和容器、已安装的软件包、智能体状态与历史记录，以及无挂载工作区或 克隆工作区中的文件。直接挂载工作区中的文件则存放在宿主机上。

每个沙箱维护自己的 Docker 守护进程状态、镜像缓存和已安装的软件包。多个沙箱之间 不共享镜像或层。共享的智能体技能存储是一个例外： 为受支持的智能体创建的沙箱默认会以只读方式挂载同一个宿主机侧的存储。使用 --skills 或 skills.defaultMode 可以在创建时选择其他模式。已有沙箱会保留其挂载，直到被重新创建。

每个沙箱都会占用磁盘空间，用于存放其 VM 镜像、Docker 镜像、容器层和卷， 并且随着你构建镜像和安装软件包而不断增长。

在所有操作系统上，直接挂载的工作区默认启用 Virtiofs 缓存。来自沙箱 VM 的文件 读取会在宿主机一侧缓存，从而减少通过文件系统透传往返的次数，并提升读密集型 工作负载（如 git status 或目录扫描）的性能。如需关闭该缓存，创建沙箱时设置 DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0：

console
$ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run <agent>

网络 ​

沙箱发出的所有出站 TCP 流量都会经由宿主机上的一个代理进行路由。智能体使用 正向代理处理 HTTP 和 HTTPS；其他 TCP 流量则被透明转发。两条路径都会强制执行网络 策略，即决定沙箱可以访问哪些目标的规则。这些规则如何设置，请参阅 沙箱治理。正向代理还负责处理 凭据注入。其工作方式参见 网络隔离，开箱即用的允许范围参见 默认安全基线。

跟踪一次已认证的请求 ​

按照下面的图示逐步查看 Docker Sandboxes 在何处检查网络策略，以及在何处将哨兵凭据 替换为真实值。在整个请求过程中，真实凭据始终留在沙箱之外。

以下步骤说明一次已认证请求在沙箱中的完整流转：

  1. 智能体准备请求 —— 智能体看到的是一个哨兵值，而不是真实的 API 凭据。
  2. 请求离开 microVM —— 出站的 HTTP 和 HTTPS 流量通过宿主机网络路径穿越沙箱边界。
  3. 网络策略检查目标地址 —— 只有在活动策略允许该提供商域名时，请求才会继续。
  4. 代理解析凭据 —— 宿主机侧的代理解析匹配的凭据，而不会把它复制进沙箱。
  5. 代理重写请求头 —— 请求离开 microVM 之后，代理用真实凭据替换掉哨兵值。
  6. 响应返回 —— 提供商响应经由宿主机代理返回给智能体，凭据始终留在宿主机上。

上游代理 ​

宿主机侧的代理使用你宿主机的网络配置和路由来建立出站连接。当目标地址可以通过 直连路由到达时，流量就走该路由。当访问某个目标必须经过上游代理时，宿主机侧的 代理会将请求转发给它。链接到上游代理意味着沙箱流量与其他宿主机上的应用一样， 遵守相同的出站流量控制。

默认情况下，沙箱流量和守护进程自身的流量都遵循你的操作系统系统代理，因此通常 无需任何配置即可正常工作。如需显式设置代理 —— 例如代理 URL、PAC 文件、SOCKS5 代理，或者分别为沙箱流量和守护进程流量设置 —— 请参阅 配置上游代理。上游代理支持目前仍属实验性功能， 随时可能变更。

只有 HTTP 和 HTTPS 流量可以被转发到上游代理。其他 TCP 流量无法重定向到代理。

MCP gateway ​

受支持的智能体会为该沙箱连接到同一个 MCP gateway 端点。该 gateway 运行在沙箱 边界的宿主机一侧，负责代理对已注册 MCP 服务器的访问。

已注册的 MCP 服务器可以是远程端点，也可以是在宿主机上启动的本地 stdio 服务器。 本地 stdio 服务器不会在沙箱 VM 内运行。如果本地 stdio 服务器以 OCI 镜像的形式 打包，或者你显式注册了一个 docker 命令，它会使用宿主机上的 Docker。

在 MCP 策略生效时，强制执行发生在 MCP gateway 路径上，与 HTTP/HTTPS 网络代理 相互独立。服务器注册会在存储之前被检查，受管控的 MCP 请求则由 gateway 在工具调用、 资源读取、提示词获取或 gateway 元工具执行之前进行检查。

生命周期 ​

sbx run 会为指定智能体初始化一个 VM 并启动该智能体。你可以在不重建 VM 的情况下 停止并重启，已安装的软件包、Docker 镜像和沙箱内的文件都会保留。

沙箱会一直保留，直到被显式删除。停止智能体不会删除 VM；环境设置会在多次运行之间 延续。使用 sbx rm 可删除该沙箱、它的 VM 以及其中的全部内容。如果该沙箱使用了 --clone，你宿主机仓库上的 sandbox-<name> Git 远程也会 一并被删除。

与其他方案的对比 ​

方案隔离程度Docker 访问权限适用场景
沙箱（microVM）完全隔离（hypervisor）独立守护进程自主智能体
挂载 socket 的容器部分隔离（命名空间）共享宿主机守护进程可信工具
Docker-in-Docker部分隔离（特权模式）嵌套守护进程CI/CD 流水线
宿主机直接执行无隔离宿主机守护进程手动开发

沙箱以更高的资源开销（一个 VM 加上它自己的守护进程）换取完全隔离。当你需要 轻量打包且不需要 Docker 访问权限时，使用容器。当你需要把完整的 Docker 能力 交给某个自主运行的组件，同时又不信任它接触你的宿主机环境时，使用沙箱。