Docker Sandboxes

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

Docker Sandboxes 在 microVM 中运行 AI 智能体，让它们可以执行代码、安装软件包、 使用工具，同时不会接触到除你主动共享之外的宿主资源。多层隔离保护你的宿主系统。

信任边界 ​

主要的信任边界是 microVM。智能体在 VM 内部拥有完全控制权，包括 sudo 权限。 VM 边界阻止智能体访问宿主上的任何内容，只有显式共享的部分除外。

跨越边界进入 VM 的内容：

  • 宿主工作区目录： 当你传入工作区路径或使用 sbx run 时会共享，后者默认使用 当前目录。直接挂载是读写模式，因此智能体会就地修改你的工作树。使用 --clone 时，你的仓库以只读方式挂载，智能体在一个私有 克隆上工作。无挂载沙箱不共享宿主工作区。
  • 凭据： 宿主侧的代理会把认证头注入到出站 HTTP 请求中。原始凭据值从不进入 VM。
  • 网络访问： 到 network policy 允许的目标的出站 TCP 连接会通过宿主 代理转发。
  • 共享的智能体技能：为受支持的智能体创建的沙箱，默认会在智能体的技能目录以只读方式 挂载一个宿主侧的持久化存储。使用 --skills 或 skills.defaultMode 可以在创建时选择其他模式。已存在的沙箱会保留原有挂载，直到被重新创建。
  • MCP gateway 流量： 受支持的智能体会连接到宿主侧的 MCP gateway 端点。 Gateway 为已注册的 MCP 服务器代理访问。

跨越边界回到宿主的内容：

  • 工作区文件变更： 使用直接挂载时，变更会实时显示在你的宿主上。
  • 出站 TCP 连接： 通过宿主代理发送到允许的目标。
  • 共享技能变更：拥有 readwrite 访问权限的沙箱可以写入宿主侧的存储。 这些变更对共享该存储的其他沙箱可见。

除工作区和共享技能存储之外，智能体无法访问你的宿主文件系统。它也无法访问你的宿主 Docker daemon、直接访问宿主网络，或访问 network policy 未允许的任何目标。沙箱之间 不能直接通过网络通信。除非你开启 experimental UDP feature 并通过 network policy 放行，否则出站 UDP 会被阻止。ICMP 被阻止。

MCP 服务器是一个显式的集成点。远程 MCP 服务器运行在 Docker Sandboxes 之外， 本地 stdio MCP 服务器运行在宿主上，而不是沙箱 VM 内部。智能体可以通过 MCP gateway 调用这些服务器暴露的工具；当组织治理启用时，还要受 MCP 策略约束。请把本地 MCP 服务器视为受信任的宿主集成。

MicroVM 隔离 ​

下面的拓扑展示了哪些内容为 microVM 私有、哪些被显式挂载，以及哪些宿主资源仍在 智能体触及范围之外。

分类组件说明
microVM 内部AI 智能体在 microVM 内拥有完全控制权（sudo）。可以安装软件包、运行代码，并修改沙箱边界内的资源。
microVM 内部VM 文件系统该沙箱私有。智能体无法借助它浏览宿主上的其他文件。
microVM 内部Docker Engine与宿主没有连接。智能体创建的容器运行在 microVM 内的这个引擎上，无法访问宿主 daemon。
显式共享工作区从宿主机挂载。直接模式以读写方式挂载宿主工作树，克隆模式则只读挂载宿主仓库并给智能体一份私有克隆。
显式共享共享技能存储可选的共享挂载。受支持的智能体会以读写方式挂载宿主侧的技能存储，除非你显式关闭。
显式共享SSH agent socket默认转发。宿主设置了 SSH_AUTH_SOCK 时，Docker Sandboxes 会把 agent socket 转发进 microVM：沙箱进程可以请求签名，但私钥始终留在宿主上。
microVM 之外其他宿主资源没有直接访问路径。智能体无法直接访问宿主的其余文件系统、宿主进程或宿主 Docker daemon。

要跟踪一个出站请求经过 network policy 和凭据注入的完整流程，请参阅 Architecture。

隔离层 ​

沙箱安全模型包含五层。各层的技术细节请参阅 Isolation layers。

  • Hypervisor 隔离： 每个沙箱有独立的内核。与宿主不共享内存，也不共享进程。
  • 网络隔离： 出站 TCP 流量通过宿主代理转发，并受 deny-by-default 策略 约束。实验性的 UDP 出站同样遵循 network policy。ICMP 被阻止。
  • Docker Engine 隔离： 每个沙箱拥有自己的 Docker Engine，没有任何路径通向宿主 daemon。
  • 工作区隔离： 无挂载沙箱没有宿主工作区挂载。Clone 模式给智能体一个 VM 内的私有 克隆，并把你的仓库以只读方式挂载。直接模式则以读写方式共享你的工作树。
  • 凭据隔离： API key 由宿主侧代理注入到 HTTP 头中。凭据值从不进入 VM。

智能体在沙箱内可以做什么 ​

在 VM 内部，智能体拥有完整权限：sudo 权限、软件包安装能力、一个私有的 Docker Engine，以及对其沙箱内文件系统和所配置工作区的读写访问。已安装的软件包、Docker 镜像和其他 VM 状态在重启后依然保留。允许和阻止的内容的完整拆解，请参阅 Default security posture。

安全考量 ​

沙箱把智能体与你的宿主系统隔离开，但智能体的行为仍可能通过显式共享的资源 和允许的网络通道影响到你。

在直接模式下，工作区变更会实时出现在你的宿主上。智能体修改的就是你在宿主上 看到的同一批文件。这其中包括在日常开发中会被隐式执行的文件：Git hooks、CI 配置、 IDE 任务配置、AI 项目配置与设置、Makefile、package.json scripts 以及类似的 构建文件。在运行任何被修改过的代码之前先审查这些变更。注意 Git hooks 位于 .git/ 目录内，不会出现在 git diff 输出中，需要单独检查。完整清单以及 clone 模式这一 替代边界，请参阅 Workspace isolation。

默认允许的域名包含范围较宽的通配符。有些默认值（例如 *.googleapis.com）覆盖的 服务远超 AI API 范围。运行 sbx policy ls 查看生效规则的完整列表，并删除你不需要 的条目。请参阅 Default security posture。

Kit 会在沙箱内以 root 权限运行安装命令。为了限制供应链风险，sbx 将 kit 安装 限制在一份来源允许列表内，默认仅包含 Docker Hub。请参阅 Restrict kit sources。

共享的智能体技能为跨沙箱隔离打开了一个狭窄的例外。存储可以以 readwrite 访问 权限挂载，因此一个沙箱可以修改另一个沙箱中的智能体随后会使用的指令或脚本， 包括以 readonly 访问权限挂载的沙箱。这不会暴露宿主文件系统的其余部分，也不会 在沙箱之间建立直接的网络路径，但确实把参与的沙箱放进了同一个信任边界。细节以及 按沙箱退出的方式，请参阅 Share agent skills。

本地 stdio MCP 服务器运行在沙箱 VM 之外。如果你注册的本地 MCP 服务器会启动宿主 进程或宿主上的 Docker 容器，那么该进程或容器使用的是宿主权限和宿主隔离，而不是 沙箱隔离。请参阅 MCP gateway。

组织级管控 ​

在单个开发者的机器上，安全和策略在本地配置 —— 例如用 sbx policy 设置的 network 和 filesystem 规则。管理员可以把这些管控项移到组织层级，让安全、策略和访问控制在 每位开发者的沙箱中保持一致，而不是依赖各自的本地配置。

组织管理员可用的管控项请参阅 Organization governance。

了解更多 ​