Docker Sandboxes

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

AI 编程智能体需要代你执行代码、安装软件包和运行工具。Docker Sandboxes 让每个智能体 运行在自己的 microVM 中。五层隔离保护你的宿主：hypervisor、network、Docker Engine、 workspace 和凭据代理。

Hypervisor 隔离 ​

每个沙箱都运行在一个轻量级 microVM 中，拥有自己的 Linux 内核。与共享宿主内核的 容器不同，沙箱 VM 无法访问宿主进程、文件或定义边界之外的资源。

  • 进程隔离： 每个沙箱有独立的内核；VM 内的进程对宿主和其他沙箱都不可见
  • 文件系统隔离： 当你传入工作区路径或使用 sbx run 时会共享宿主工作区，后者 默认使用当前目录。对于尚未选择退出的受支持智能体，专用的 共享技能存储 也会与宿主共享。VM 文件系统的其余 部分在重启之间保留，但在你删除沙箱时被移除。指向工作区范围之外的符号链接不会被 跟随。
  • 彻底清理： 当你用 sbx rm 删除沙箱时，VM 及其内部的一切都会被删除

智能体在 VM 内以非 root 用户身份运行，并拥有 sudo 权限。Hypervisor 边界才是隔离 控制手段，而不是 VM 内部的权限分离。

本地沙箱中的进程可以向你的宿主剪贴板写入文本，但无法读取剪贴板中已有的文本。读取 宿主剪贴板图像是一个独立的、需要显式启用的功能。运行不受信任的代码之后，粘贴到 宿主之前先检查剪贴板内容。

Network 隔离 ​

每个沙箱都有自己的隔离网络。沙箱之间不能直接通信，也不能与你的宿主共享网络。如需 通过受策略控制的连接访问宿主上运行的服务，请参阅 Accessing host services from a sandbox。

所有出站 TCP 流量都经过宿主上的一个代理，该代理会强制执行 network policy。沙箱会 根据客户端配置选择正向代理或透明代理来转发流量。两者都会强制执行 network policy。 network policy 如何设置请参阅 Sandbox governance。只有正向代理会为 AI 服务注入凭据。

出站 UDP 默认关闭。开启 experimental UDP egress 后，其目标由 network policy 控制。ICMP 被阻止。DNS 查询使用沙箱的内部解析器，该解析 器会强制执行 network policy。只有当某条策略规则匹配到目标时，TCP 连接才会被允许。

允许域名的默认集合请参阅 Default security posture。如需通过企业代理或上游代理转发允许的流量， 请参阅 Configure an upstream proxy。

Docker Engine 隔离 ​

智能体经常需要构建镜像、运行容器和使用 Docker Compose。把宿主上的 Docker socket 挂载进容器，会让智能体完全掌控你的环境。

Docker Sandboxes 通过在沙箱环境内运行一个独立的 Docker Engine 来避免这一点，该引擎与你的宿主隔离。 当智能体运行 docker build 或 docker compose up 时，这些命令针对的是沙箱内的 那个引擎。智能体没有任何路径通向你的宿主 Docker daemon。

这个 Docker Engine 边界适用于运行在沙箱 VM 内的进程。它不适用于通过 MCP gateway 注册的本地 stdio MCP 服务器。这些服务器运行在宿主 上，位于沙箱 VM 之外。如果本地 MCP 服务器启动了 Docker 容器，它使用的是宿主上的 Docker。

每个沙箱 VM 运行自己的 Docker Engine。智能体运行在 VM 内，与该引擎并存，并驱动 它在 VM 内创建容器：

mermaid
flowchart TB
  subgraph host["宿主系统"]
    subgraph hostd["宿主 Docker daemon"]
      hc["你的容器和镜像"]
    end
    subgraph vm["沙箱（microVM）"]
      a["智能体"]
      subgraph e["沙箱 Docker engine"]
        c["智能体创建的容器"]
      end
      a -->|"docker build / compose up"| e
    end
  end
  style host fill:#3b82f622,stroke:#3b82f6

工作区隔离 ​

创建沙箱时，选择智能体如何获得工作区：

  • 无挂载（sbx create 不带路径）：沙箱不会获得宿主工作区。智能体在沙箱自己的 文件系统中工作。
  • 直接挂载（路径例如 .）：智能体对你的工作树拥有读写权限。智能体的修改与你的 宿主文件系统之间没有任何边界。
  • Clone 模式（--clone 加一个 Git 路径）：你的仓库以只读方式挂载进 VM，智能体 在 VM 内的私有克隆上工作。在你获取这些改动之前，智能体的修改不会到达你的宿主。

直接挂载和 clone 模式的工作流请参阅 Git workflows。

无挂载 ​

在 sbx create 中省略工作区路径即可创建无挂载沙箱，然后按名称连接：

console
$ sbx create --name scratch claude
$ sbx run --name scratch

智能体使用沙箱模板的默认工作目录。Docker 提供的智能体模板使用 /home/agent/workspace。如果模板没有定义可用的绝对工作目录，daemon 会使用该路径。 那里的文件保留在沙箱内部，在停止和重启之间保留，并在你删除沙箱时被删除。无挂载 沙箱不会暴露宿主项目目录，但单独配置的宿主资源（例如共享技能存储）仍然可以被挂载。

直接挂载 ​

传入工作区路径，把它以读写挂载的方式共享进 VM。智能体和宿主看到的是同一批文件， 智能体做出的变更一写入就会出现在你的宿主上。不传路径时，sbx run 会挂载当前目录：

console
$ sbx run claude

直接挂载按路径执行访问控制。如果工作区中的某个文件是指向工作区之外文件的硬链接， 智能体可以通过工作区路径读取和修改底层文件。变更会影响指向该文件的每一个硬链接， 包括授权工作区之外的链接。文件系统访问策略无法阻止这种访问，因为它们评估的是工作区 路径，而不是指向同一文件的其他路径。Clone 模式 通过把宿主仓库以只读 方式挂载，防止通过主工作区写入。

直接挂载给了智能体对你工作区的广泛写权限。智能体可以创建、修改或删除工作区文件， 包括：

  • 源代码和配置文件
  • 构建文件（Makefile、package.json、Cargo.toml）
  • Git hooks（.git/hooks/）
  • CI 配置（.github/workflows/、.gitlab-ci.yml）
  • IDE 配置（.vscode/tasks.json、.idea/ 运行配置）
  • AI 项目配置与设置（.claude/、.codex/）
  • 隐藏文件、shell 脚本和可执行文件

其中一些文件会在你触发日常开发操作时执行代码 —— 提交、推送、构建，或在 IDE 中打开 项目。任何智能体会话结束后，在执行这些操作之前先审查它们：

  • Git hooks（.git/hooks/）会在提交、推送和其他 Git 操作时运行。它们位于 .git/ 目录内，不会出现在 git diff 输出中 —— 用 ls -la .git/hooks/ 单独检查。
  • CI 配置（.github/workflows/、.gitlab-ci.yml）会在推送时运行。
  • 构建文件（Makefile、package.json scripts、Cargo.toml）会在构建或安装步骤中 运行。
  • IDE 配置（.vscode/tasks.json、.idea/）会在你打开项目时运行任务。
  • AI 项目配置与设置（.claude/settings.json、.codex/config.toml）可以定义自动 执行的 hooks 和启动命令。

沙箱环境文件 ​

沙箱环境文件可以声明生命周期命令和凭据命令，这些命令会以你的权限在宿主上运行。 在运行这些命令之前，sbx 会在一份环境计划中展示它们并请求批准。批准宿主命令之前 先审查这份计划。

文件位置和只读保护请参阅 Sandbox environment files。

WARNING

沙箱修改过的工作区文件，要按对待来自不受信任贡献者的 pull request 的方式来对待： 在你于宿主上信任它们之前先审查。

Clone 模式 ​

当你用 --clone 启动沙箱时，智能体绝不会直接针对你的宿主 仓库工作。即使在 VM 内拥有完整的 root 权限，它也无法修改你的 .git 目录、工作树 或宿主上任何被跟踪的文件。

IMPORTANT

Clone 模式保护的是你的宿主仓库不被修改，而不是不被查看。你的仓库仍会以 只读方式挂载进沙箱，包括未跟踪的文件和被 .gitignore 排除的文件。.env 之类的 文件对智能体依然可读。请把机密信息存放在工作目录之外，或者改用 credential isolation。

mermaid
flowchart LR
  subgraph host["宿主仓库（未被改动）"]
    direction TB
    repo[".git/ + 工作树"]
    remote["remote sandbox-<name>"]
  end
  subgraph vm["沙箱 VM"]
    direction TB
    mount["/run/sandbox/source<br/>(只读绑定挂载)"]
    clone["私有克隆（读写）<br/>智能体在此编辑"]
    daemon["git-daemon"]
  end
  repo -->|"只读绑定挂载"| mount
  mount -->|"git clone"| clone
  clone --> daemon
  daemon -->|"git fetch"| remote

边界是如何被强制执行的：

  • 你的仓库的 Git 根目录以只读方式挂载在 /run/sandbox/source。该挂载覆盖你整个 工作目录，包括未跟踪的文件和被 .gitignore 排除的文件。智能体在 VM 内做的任何 事情都无法通过该挂载写回，但 Git 根目录下的所有文件在沙箱内都可读。这包括未被 Git 跟踪的凭据文件，例如 .env。
  • 智能体在沙箱内的私有克隆上工作。该克隆有自己的 index、自己的 refs 和自己的工作 树。对克隆的写入永远到不了你的宿主。
  • 沙箱通过绑定到宿主 localhost 的 Git daemon 发布该克隆。CLI 会把它配置成你宿主 仓库上的一个 sandbox-<sandbox-name> Git remote。从该 remote 获取内容，采用与从 任何第三方 remote 获取内容相同的信任模型 —— 在你显式合并或检出获取到的 refs 之前，什么都不会被合入。

实际保证：

  • 智能体无法修改宿主上任何被跟踪的文件，也无法修改 .git/ 下的任何字节。被入侵或 有缺陷的智能体无法植入 .git/hooks/pre-commit、无法改动 .github/workflows/， 也无法把改动偷偷带入你的工作树。
  • 宿主上和沙箱内并发执行的 git 命令不会在共享的 .git/index 或共享的 refs 上 竞争 —— 不存在共享的可写 Git 状态。
  • 凭据、签名密钥以及你仓库 .git/config 中的任何设置都留在宿主上。智能体的克隆 有自己独立的配置。

当你需要在智能体的 Git 操作与宿主仓库之间建立强边界时，使用 clone 模式 —— 例如运行 一个不熟悉的智能体、同时在同一个仓库上运行多个智能体，或者在智能体工作期间保持 你的工作树干净。

凭据隔离 ​

大多数智能体需要其模型提供方的 API key。你不必把密钥传进沙箱，宿主侧代理会拦截 出站 API 请求，在转发每个请求之前注入认证头。

凭据值从不保存在 VM 内部。除非你显式设置，否则它们在沙箱内既不可作为环境变量 获取，也不可作为文件获取。这意味着被入侵的沙箱无法从本地环境中读取 API key。

SSH agent 转发默认启用。私钥留在宿主上，但沙箱内的任何进程都可以请求被转发的 agent 执行认证或对数据签名。Docker Sandboxes 只会转发它识别为 SSH agent 的 socket。当 转发被禁用、配置不可用，或所选 socket 无法使用时，沙箱不会收到任何 SSH agent。

关于如何存储和管理凭据，请参阅 Credentials。