Docker Sandboxes

这些工作区模式适用于本地沙箱。在云沙箱中，请参阅 transfer files or clone a remote repository。 要在不同环境之间复制沙箱文件系统，请参阅 Move a sandbox。宿主挂载和 clone 模式的卷不包含在该快照中。

根据你希望如何审查和运行智能体的变更，选择 checkout 的存放位置：

  • 用直接模式共享宿主 checkout，让编辑实时出现在你的本地编辑器中。 宿主 worktree为任务提供独立的分支和目录，同时让编辑在宿主上可见。
  • 用 clone 模式给智能体一个基于你本地仓库的独立 checkout。通过获取或 推送已提交的工作把它带回来。
  • 用无挂载沙箱在沙箱内克隆仓库，不挂载宿主工作区。把分支推送到 Git remote 以共享结果。
Checkout宿主 checkout 中可见的变更智能体可以使用 Git
直接挂载立即是
挂载的宿主 worktree立即，位于 worktree 中否
Clone 模式（--clone）检出或合并获取到的分支之后是
无挂载沙箱从 Git remote 拉取已提交的工作之后是

当你把更多管理工作交给智能体时，可以考虑无挂载沙箱。智能体可以管理分支、创建 worktree，并推送结果供审查，而无需在宿主 checkout 中协调变更。你通过 Git 审查并带回 已提交的工作，通过发布的沙箱端口运行预览。

对于同时进行的多个任务，让智能体在沙箱内为每个任务创建独立的 worktree 或克隆。这在 无挂载沙箱和 clone 模式中都适用，并且能让智能体继续使用 Git。仅靠分支无法在共享的 工作目录中隔离编辑。同一个沙箱内的 worktree 共享它的工具和服务。当任务还需要各自 独立的环境时，请使用不同的沙箱。

直接模式 ​

沙箱直接挂载你的宿主工作树。智能体就地编辑文件，变更立即出现。你和智能体都可以使用 Git，因此要约定由谁管理分支和提交。任一方切换分支都会改变双方看到的文件。

要从宿主管理 Git 操作：

  1. 检出你想工作的分支：

    console
    $ git checkout -b feat/my-feature

  2. 启动沙箱。不需要特殊标志：

    console
    $ sbx run claude

  3. 智能体在你的工作树中编辑文件。像平常一样审查 diff、暂存并提交：

    console
    $ git diff
$ git add -p
$ git commit
$ git push -u origin feat/my-feature

直接模式适合聚焦的单分支工作，即你与智能体逐轮协作的场景。

Clone 模式 ​

在 clone 模式下，sbx 会在沙箱内创建一个独立的 Git 克隆。智能体编辑这个克隆，而不是 你的宿主工作树。它的变更留在沙箱内，直到你获取某个分支，或智能体把某个分支推送到 remote。你的宿主仓库在 /run/sandbox/source 处同样可用，但只有读权限。沙箱克隆不是 与你宿主 checkout 关联的 Git worktree。

单个 clone 模式的沙箱可以容纳多个分支和 worktree，用于并行任务。--clone 标志创建 克隆，但不会把一个任务与另一个任务隔开。要让并行任务保持隔离，请指示你的智能体工具 为每个任务创建独立的 worktree 或克隆。

NOTE

--clone 是创建时的标志，无法在已有沙箱上更改。要把沙箱从 clone 模式改为直接模式， 请删除并重新创建它。要对同一个仓库同时使用两种模式，请创建名称不同的沙箱。

沙箱 remote 行为 ​

CLI 会把宿主仓库中的 Git remote（例如 origin 和 upstream）复制到沙箱内的克隆中。 本地路径的 remote（例如 file:// URL 和文件系统路径）不会被复制，因为它们在沙箱内 无法访问。

暴露沙箱内克隆的 Git daemon 作为沙箱的一部分运行。它只在沙箱运行期间可访问：

  • sbx stop 会关闭 daemon。在沙箱再次启动前，git fetch sandbox-<name> 会失败。
  • 重启沙箱会给 daemon 分配另一个临时端口。CLI 会更新你宿主仓库 Git 配置中的 sandbox-<name> remote URL，因此获取操作可以继续，无需手动重新配置。
  • sbx rm 会移除沙箱、daemon、已发布的端口，以及宿主仓库中的 sandbox-<name> remote 条目。

单个任务 ​

  1. 启动 clone 模式的沙箱：

    console
    $ sbx run --clone claude .

  2. 让智能体在开始编辑前创建一个分支：

    创建一个 feat/my-feature 分支并做出相应改动。

  3. 智能体完成后获取它的分支：

    console
    $ git fetch sandbox-<name>
$ git log sandbox-<name>/feat/my-feature
$ git diff main..sandbox-<name>/feat/my-feature

  4. 把分支拉取到宿主再推送，或者让智能体直接推送：

    console
    # 先拉取到宿主，再推送
$ git checkout -b feat/my-feature sandbox-<name>/feat/my-feature
$ git push -u origin feat/my-feature
$ gh pr create

# 或者让智能体执行
# "把 feat/my-feature 推送到 origin 并创建一个 PR。"

并行任务 ​

  1. 启动 clone 模式的沙箱并打开 agents view：

    console
    $ sbx run --clone claude .

  2. 把每个独立任务分派给各自的后台会话。你的智能体工具决定如何分隔它们的工作目录。 若要要求每个任务都使用独立的 worktree，请添加这样的项目指令：

    markdown
    对于每个同时进行的任务，创建一个带独立分支的 Git worktree，并在该 worktree 中
完成该任务的全部改动。

  3. 智能体完成后获取所有分支：

    console
    $ git fetch sandbox-<name>
$ git log sandbox-<name>/feat/task-a
$ git log sandbox-<name>/feat/task-b

  4. 检出你想保留的分支，并照常创建 PR。

宿主 worktree ​

你可以在宿主上创建一个 Git worktree，并让沙箱指向它。智能体会直接在该 worktree 中 编辑文件 —— 但由于沙箱只挂载 worktree 目录（而不是父仓库），它无法解析 .git 指针 文件，因此没有 Git 访问权限。智能体可以读写文件，但不能提交、建分支或查看状态。

当你希望编辑出现在一个独立的宿主目录中，并且更愿意自己处理 Git 操作时，使用这种 方式。若要让智能体在每个工作目录中都能使用 Git，请在无挂载沙箱或 clone 模式沙箱内 使用 worktree。

  1. 在宿主上创建 worktree：

    console
    $ git worktree add -b feat/my-feature ../my-feature-work

  2. 以该 worktree 作为工作区启动沙箱：

    console
    $ sbx run claude ../my-feature-work

  3. 智能体编辑文件。完成后在宿主上提交并推送：

    console
    $ cd ../my-feature-work
$ git diff
$ git add -p && git commit
$ git push -u origin feat/my-feature
$ gh pr create

无挂载沙箱 ​

无挂载沙箱没有挂载宿主工作区。在其中克隆仓库，让 checkout、依赖和开发工具都留在 沙箱内。文件在停止和重启之间保留，但删除沙箱会把它们一并删除。

你可以为每个项目保留一个沙箱并在任务之间复用。智能体可以按需准备工具并创建 worktree，因此开始新任务不需要另一个宿主 checkout 或沙箱。

  1. 创建一个不带工作区路径的具名沙箱，然后连接：

    console
    $ sbx create --name my-project claude
$ sbx run --name my-project

    在 sbx create 中省略路径会创建无挂载沙箱。而在 sbx run claude 中省略路径则 会改为挂载你当前的宿主目录。请参阅 Choose a workspace。

  2. 让智能体在沙箱内克隆你的仓库，并在编辑前创建一个分支。对于同时进行的多个任务， 让它为每个任务创建独立的 worktree。

  3. 在沙箱内审查并提交改动，然后把分支推送到你的 Git remote。你可以在宿主 checkout 中获取该分支，或在 pull request 中审查它。删除沙箱之前，先推送所有你想保留的工作。

你也可以用 sbxenv.yaml 环境文件创建无挂载沙箱。省略 workspace 以及任何 additionalWorkspaces 挂载，然后运行 sbx env run。配置选项请参阅 Sandbox environment files。

关于运行应用并从宿主浏览器打开预览，请参阅 Develop and test locally。 若要在同一个沙箱中处理多个宿主仓库，请参阅 Multiple workspaces。

Git 忽略规则 ​

本地沙箱中的 Git 会为创建沙箱时已存在的路径保留与宿主相关的忽略决策。这适用于主 工作区位于 Git 仓库根目录的情况。

沙箱收到的是被忽略路径的快照，而不是与宿主相关的模式。这些模式不适用于之后创建 的文件，但被忽略的目录仍然覆盖其中新增的文件。额外的仓库以及位于仓库根目录之下的 主工作区不会收到该快照。仓库的 .gitignore 文件照常工作。

Git 忽略规则不限制智能体对工作区中文件的访问。

提交签名 ​

SSH agent 转发默认启用。设置了 SSH_AUTH_SOCK 时，沙箱会把你的宿主 SSH agent 转发 进沙箱，因此智能体可以用你的 SSH key 签署提交，而私钥绝不会离开你的宿主。如果你 关闭了转发或使用固定的 SSH agent socket，请参阅 SSH agent configuration。

  1. 确保签名密钥已加载到宿主的 SSH agent 中：

    console
    $ ssh-add ~/.ssh/id_ed25519
$ ssh-add -L  # 确认密钥已出现

  2. 在沙箱内配置 Git 使用 SSH 签名。直接使用被转发的密钥而不是文件路径，因为宿主 路径在沙箱内并不存在：

    console
    $ git config --global gpg.format ssh
$ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)"

  3. 像平常一样签署提交：

    console
    $ git commit -S -m "feat: my change"

要把这套配置自动应用到内置智能体，请把它打包成一个 mixin。请参阅 Build a tool mixin 和 Add mixins。

排查问题请参阅 Sandbox commits aren't signed。