Docker Sandboxes

以下诊断和恢复步骤适用于本地沙箱。使用 sbx --cloud diagnose 检查云端连接和账户 访问权限。有关云端文件、过期机制和网络访问，请参阅云端沙箱。本地 守护进程重启和 sbx reset 不会修复云端沙箱状态。

运行诊断 ​

在深入排查具体问题之前，先运行 sbx diagnose 检查安装中的常见问题，例如缺少 CLI 二进制文件、守护进程无法访问、CLI 与守护进程版本不匹配、存储目录缺失或 身份验证失效。

console
$ sbx diagnose

该命令会打印一份检查结果摘要，标明哪些检查通过、发出警告或失败，并给出建议的 修复方法。使用 --json 或 --format yaml 可获得机器可读的输出，使用 --format github-issue 可生成适合粘贴到 GitHub issue 中的 Markdown 片段。

检查沙箱磁盘占用 ​

如果你的磁盘空间不足，请检查本地沙箱的镜像、容器和托管卷占用了多少存储空间：

console
$ sbx df

摘要会显示每种资源类型的大小和预计可回收的空间。要找出具体占用空间的镜像、 容器或卷，请运行：

console
$ sbx df --verbose

镜像总计只计算一次共享层，并包含你删除镜像标签后仍被容器保留的镜像数据。宿主机 绑定挂载、日志和缓存不在统计范围内，因此该报告并不涵盖你宿主机上使用的全部 磁盘空间。显示为 unknown 的测量值无法确定。

清理之前，请用 sbx prune --dry-run预览哪些已停止的沙箱会被删除。可回收空间估算值 涵盖的是各类型中未被使用的资源，因此它并不等于单靠 sbx prune 能释放的空间。 共享存储和仍在使用的资源会减少或延迟回收的空间。

在 eCryptfs 上镜像拉取失败 ​

在 Linux 上，如果沙箱状态目录位于 eCryptfs 上，镜像拉取可能会因 I/O 错误而失败。

如果 sbx diagnose 报告 state directory is on eCryptfs， 请为沙箱状态使用 eCryptfs 之外的文件系统。

沙箱没有响应 ​

如果 sbx ls 显示 running (not responding)，说明 Docker Sandboxes 检测到该 沙箱没有响应命令。停止并重新启动该沙箱，然后重试你的命令：

console
$ sbx stop <SANDBOX_NAME>
$ sbx start <SANDBOX_NAME>

停止并重新启动沙箱时，保存在其中的文件会被保留。

重启沙箱守护进程 ​

如果沙箱命令挂起、无法连接守护进程，或持续返回守护进程错误，请在重置沙箱状态 之前重启沙箱守护进程：

console
$ sbx daemon restart

然后重试失败的那条命令。重启守护进程不会删除沙箱数据。如果问题仍然存在或状态 已损坏，请使用 sbx reset。

重置沙箱 ​

如果遇到持续存在的问题或状态损坏，运行 sbx reset 停止所有 VM 并删除所有沙箱数据。之后 再创建全新的沙箱。

沙箱中没有我的项目文件 ​

从 sbx 0.42.0 版本开始，sbx create 的工作区路径是可选的。省略该路径时， 该命令会创建一个无挂载沙箱。例如，以下命令会创建并接入一个不挂载宿主机项目 文件的沙箱：

console
$ sbx create --name <sandbox-name> <agent>
$ sbx run --name <sandbox-name>

相比之下，不传工作区路径时 sbx run 会挂载当前目录：

console
$ sbx run <agent>

沙箱的工作区配置在创建时即已固定。如需复用某个已有无挂载沙箱的名称，请先 把想保留的文件复制出来，然后 删除它并带工作区路径重新创建：

console
$ sbx rm <sandbox-name>
$ sbx run --name <sandbox-name> <agent>

有关无挂载、直接和克隆模式的行为，请参阅选择工作区。

沙箱报告挂载状态错误 ​

如果沙箱报告 saved mount metadata does not match the container，请删除并重新 创建受影响的沙箱。如果该沙箱仍可访问，请在删除它之前 把想保留的文件复制出来。删除沙箱 会删除它的沙箱数据。

如果错误信息为 a recorded mount source now resolves to a different path， 请恢复原有的宿主机源路径，或者删除并重新创建该沙箱。当你把源目录或它的某个 父目录替换成指向其他位置的符号链接时，就可能出现这种情况。

把宿主机上的符号链接改指向别处，并不会移动已有的静态挂载。沙箱会保留原来的 源路径，重新使用该沙箱时的文件系统策略检查也包含这个源路径。

Kiro、Copilot 或 Droid 简写名称失败 ​

在 Docker Sandboxes v0.42 中，sbx run kiro、sbx run copilot 和 sbx run droid 会失败，因为这些智能体从内置智能体移到了公共 Kit，而本版本 无法解析它们的简写名称。

升级 Docker Sandboxes 到 v0.43.0 或更高版本，即可再次按名称 启动这些智能体。如果你需要停留在 v0.42，请为你的智能体使用完整的 Kit 引用：

console
$ sbx run docker.io/sbx/kiro-kit:latest
$ sbx run docker.io/sbx/copilot-kit:latest
$ sbx run docker.io/sbx/droid-kit:latest

网络访问与策略 ​

对于由网络规则、审批或组织治理引起的问题，例如请求被阻止、允许规则未生效或 缺少审计记录，请参阅治理故障排查。

Kit 安装失败：来源不在允许列表中 ​

如果加载 Kit 时出现类似"来源不在你的允许列表中"的提示：

console
$ sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=vale"

sbx 将 Kit 安装限制在一份来源允许列表内，默认仅包含 Docker Hub （docker.io/）。把该 Kit 的发布者添加到 kit.allowedSources 设置中， 同时保留你想继续保留的条目：

console
$ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]'

然后再次运行该命令。详情（包括如何允许本地 Kit 或任意远程来源）请参阅 限制 Kit 来源。

Kit 安装或启动命令失败 ​

如果 sbx create 或 sbx run 在某个 Kit 的安装命令上显示 ✗，或者提示启动命令 失败，完整输出位于沙箱内部。请用 sbx exec 读取：

console
$ sbx exec <sandbox-name> cat /var/log/sbx-kits/<kit>/install-<n>.log
$ sbx exec <sandbox-name> cat /var/log/sbx-kit-startup.log

<n> 是安装命令在该 Kit install 列表中的位置，从 0 开始。要在创建沙箱期间 实时输出每个安装命令的输出和启动日志，请运行 sbx -D create 或 sbx -D run。 如何阅读这些输出以及排查常见原因，请参阅 调试 Kit。

SSH 及其他非 HTTP 连接失败 ​

SSH 等非 HTTP 的 TCP 连接可以通过为目标地址添加策略规则来允许。主机名规则 对这些连接有效，因为当协议本身不包含主机名时，沙箱会从它的 DNS 解析器中 恢复主机名：

console
$ sbx policy allow network "myhost:22"

如果目标是通过 IP 地址访问而没有经过 DNS 查询，就无法恢复主机名。这种情况下 请使用基于地址的规则：

console
$ sbx policy allow network "10.1.2.3:22"

UDP 需要实验性的 UDP 出站流量 以及相应的 UDP 允许规则。ICMP 被阻止，无法通过策略规则解除阻止。

对于通过 SSH 进行的 Git 操作，你可以为 Git 服务器的主机名或 IP 地址添加允许 规则，也可以改用 HTTPS URL：

console
$ git clone https://github.com/owner/repo.git

无法访问运行在宿主机上的服务 ​

如果从沙箱内部访问 127.0.0.1 或某个本地网络 IP 时返回"connection refused"， 说明该地址在沙箱 VM 内不可达。请参阅 从沙箱访问宿主机服务。

Docker 身份验证失败 ​

如果你看到类似 You are not authenticated to Docker 的提示，说明你的登录会话 已过期。在交互式终端中，CLI 会提示你重新登录。在脚本或 CI 等非交互式环境中， 运行 sbx login 重新进行身份验证。

智能体身份验证失败 ​

如果智能体无法访问其模型提供商，或者你看到 API 密钥错误，那么该密钥很可能 无效、已过期或未配置。请确认它已在你的 shell 配置文件中设置，并且你已经加载 了该文件或打开了一个新终端。

对于使用凭据代理的智能体，请确保你没有在沙箱 内部把 API 密钥设置成无效的值 —— 代理会在出站请求时自动注入凭据。

如果凭据配置正确但 API 调用仍然失败，请检查 sbx policy log 并查看 PROXY 列。路由到 transparent 代理的请求不会获得凭据注入。当沙箱内的客户端（例如 Docker 容器中的进程）没有配置为使用正向代理时，就会出现这种情况。详情请参阅 查看网络活动。

MCP 服务器流停滞 ​

如果远程 MCP 服务器的 HTTP/2 处理导致长连接流停滞，请用 --disable-http2 注册它以改用 HTTP/1.1：

console
$ sbx mcp add acme --url https://mcp.acme.com/mcp --disable-http2

请把示例 URL 换成你的 MCP 端点。该设置对该服务器后续的连接生效。这个标志 需要配合 --url 使用，不能与 --command 或 --local 一起使用。有关注册选项， 请参阅注册 MCP 服务器。

API 调用因证书错误而失败 ​

如果你的组织使用会检查 HTTPS 流量的代理，智能体请求可能会因证书错误而失败， 例如 SSL certificate problem: self-signed certificate in certificate chain。 请在沙箱内安装你所在组织的内部根 CA，这样智能体及其 SDK 才会信任由代理签发的 证书。证书错误可能在凭据代理注入凭据之前就让请求中断。

如需用内置智能体实现可复现的配置，请创建一个 Mixin Kit，在创建 沙箱时安装该 CA。把示例描述文件保存为 internal-ca/internal-ca.yaml，并把证书 放在它旁边。

请使用扩展名为 .crt 的 PEM 编码证书。如果流量可能由多个内部代理签发，请在 运行 update-ca-certificates 之前为每个代理分别安装其根 CA。

使用该 Kit 创建沙箱：

console
$ sbx run claude --kit ./internal-ca/

要更新已有沙箱，把证书复制进沙箱并更新信任存储：

console
$ sbx cp ./internal-ca.crt <sandbox-name>:/tmp/internal-ca.crt
$ sbx exec <sandbox-name> -- sudo install -m 0644 /tmp/internal-ca.crt /usr/local/share/ca-certificates/internal-ca.crt
$ sbx exec <sandbox-name> -- sudo update-ca-certificates

IMPORTANT

如上所示，用 update-ca-certificates 把 CA 安装到系统信任存储中。不要覆盖沙箱 的 TLS 信任变量（如 SSL_CERT_FILE）使其只指向你的内部 CA。这样做会替换掉 系统证书包，破坏凭据代理所依赖的信任关系，导致 forward 出站路径上的请求 失败。

如果安装 CA 后 API 调用仍然失败，运行 sbx policy log 并检查 PROXY 列中的 出站路径：

  • forward：凭据代理终止 TLS 并出示自己的证书，沙箱已经信任该证书。这条路径上 的请求不需要内部 CA，而覆盖沙箱的信任变量反而会让它们失败，如上文所述。
  • forward-bypass 和 transparent：代理把数据包转发给上游代理而不终止 TLS， 因此沙箱会直接看到你所在组织的证书。这两条路径才是安装内部 CA 起作用的地方。 两者唯一的区别在于客户端是否知道自己正在与代理通信。

Docker 构建期间的证书错误 ​

由沙箱的 Docker Engine 启动的容器拥有自己的信任存储，它们不继承沙箱中安装的 证书。如果 Dockerfile 中的 HTTPS 下载因 self signed certificate in certificate chain 而失败，请在下载之前把代理 CA 安装到构建镜像中。

在沙箱内的 shell 中，把它的代理 CA 写入你的构建上下文：

console
$ printf '%s' "$PROXY_CA_CERT_B64" | base64 -d > sbx-proxy-ca.crt

对于安装了 ca-certificates 的 Debian 系镜像，复制该证书，并在发起 HTTPS 请求的命令之前更新信任存储：

dockerfile
FROM python:3.13-slim
COPY sbx-proxy-ca.crt /usr/local/share/ca-certificates/sbx-proxy-ca.crt
RUN update-ca-certificates

在沙箱内构建，并把沙箱的代理设置传给构建过程：

console
$ docker build --build-arg HTTP_PROXY --build-arg HTTPS_PROXY --build-arg NO_PROXY -t my-app .

如果你的组织还会检查 TLS，请在 update-ca-certificates 之前把它自己的根 CA 作为独立的 .crt 文件安装到构建镜像中。保留完整的系统 CA 包，这样镜像就同时 信任这两个代理和公共证书颁发机构。前文的 证书故障排查 说明了哪些代理路径需要 哪个 CA。

请不要把生成的代理证书提交到版本控制中。如果沙箱代理 CA 发生变化，请重新生成 它并重新构建镜像。

沙箱磁盘空间不足 ​

沙箱根文件系统（/）默认为 20 GB。要增大它，请在创建沙箱之前设置 DOCKER_SANDBOXES_ROOT_SIZE：

console
$ DOCKER_SANDBOXES_ROOT_SIZE=40g sbx run claude

DOCKER_SANDBOXES_ROOT_SIZE 控制根文件系统的大小。/var/lib/docker 处的 Docker 数据盘是独立的，默认为 10 GB。要更改某个沙箱的 Docker 数据盘大小，请在 创建时设置 DOCKER_SANDBOXES_DOCKER_SIZE：

console
$ DOCKER_SANDBOXES_DOCKER_SIZE=20g sbx run claude

Docker 数据盘至少要有 512 MiB。该环境变量不会调整已有卷的大小。

对于克隆模式的沙箱，请在创建沙箱之前设置 DOCKER_SANDBOXES_CLONED_WORKSPACE_SIZE 来配置克隆工作区卷的容量。该变量接受 100g 这类易读的容量字符串：

console
$ DOCKER_SANDBOXES_CLONED_WORKSPACE_SIZE=100g sbx run --clone claude .

大型仓库中文件系统操作缓慢 ​

当你传入工作区路径并使用直接模式时，git status、git log 或目录扫描之类的 文件系统操作可能明显缓慢。Virtiofs 缓存可以加速这类工作负载。克隆模式的沙箱 始终启用该缓存，因此这项调优只适用于直接模式。

Virtiofs 缓存在所有操作系统上默认启用。如果你遇到 Git 索引损坏或文件内容异常， 请用下面的开关禁用缓存并重新创建沙箱：

console
$ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run <agent>

在 WSL 上克隆模式报告 "not in a Git repository" ​

在 Windows 上，针对位于 WSL 文件系统上的仓库（\\wsl.localhost\... 路径）运行 sbx run --clone 可能失败，尽管该目录确实是一个有效的 Git 仓库：

console
> sbx run --clone claude \\wsl.localhost\Ubuntu\home\you\repo
error: --clone requires a Git repository, but \\wsl.localhost\Ubuntu\home\you\repo is not in a Git repository

原因在于 Git 的可疑所有权检查。当 Windows 上的 Git 访问跨 WSL 边界、归属于 另一个用户的仓库时，它会拒绝操作该仓库，导致底层的仓库检测失败：

console
> git -C \\wsl.localhost\Ubuntu\home\you\repo rev-parse --show-toplevel
fatal: detected dubious ownership in repository at '//wsl.localhost/Ubuntu/home/you/repo'

把该仓库加入 Git 的 safe.directory 列表以允许访问，然后再次运行该命令：

console
> git config --global --add safe.directory '%(prefix)///wsl.localhost/Ubuntu/home/you/repo'
> sbx run --clone claude \\wsl.localhost\Ubuntu\home\you\repo

SSH 智能体套接字缺失 ​

如果沙箱内设置了 SSH_AUTH_SOCK，但 ssh-add -L 报告 No such file or directory，请检查你的自定义模板是否包含 socat。Docker Sandboxes 用它来创建 转发请求到宿主机 SSH 智能体的套接字。仅安装 OpenSSH 客户端工具是不够的。

对于基于 Ubuntu 的自定义模板，请在 Dockerfile 中把 socat 加入以 root 安装的 软件包列表，然后重新构建模板并从它创建沙箱。Docker 提供的沙箱模板已经包含 socat。

如果套接字存在但转发仍然失败，请检查 SSH 智能体设置。

沙箱中的提交没有签名 ​

Docker Sandboxes 可以使用你宿主机智能体中的 SSH 密钥为 Git 提交签名。配置步骤 请参阅提交签名。

转发默认启用。检查 ssh.agentForwardingEnabled 和 ssh.agentSocketPath，确认 转发已启用并查看套接字的选择结果：

console
$ sbx settings get ssh.agentForwardingEnabled
$ sbx settings get ssh.agentSocketPath

如果你使用各客户端当前的 SSH_AUTH_SOCK，请从一个指向预期智能体的 shell 重新连接。如果 ssh.agentSocketPath 返回了一个路径，请确认它指向一个活动的 宿主机智能体。更改转发设置或套接字选择后，运行 sbx daemon restart。

如果 ssh-add -L 输出 The agent has no identities.，说明沙箱能够访问转发 过来的智能体，但宿主机智能体没有加载任何密钥。请把签名密钥加载到你的宿主机 SSH 智能体中：

console
$ ssh-add ~/.ssh/id_ed25519

如果提交签名在宿主机上正常但在沙箱中失败，请检查 Git 是否被配置为使用某个 宿主机文件路径（如 /Users/me/.ssh/id_ed25519.pub）来签名。沙箱使用的是转发的 SSH 智能体，而不是宿主机上的密钥文件路径。请改用内联公钥形式：

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

如果 Git 报告缺少 ssh-keygen，请使用包含 OpenSSH 客户端工具的沙箱模板。

如果 git log --show-signature 报告需要配置 gpg.ssh.allowedSignersFile，说明 Git 无法在本地验证 SSH 签名。该验证配置并不是创建已签名提交的必要条件。 GitHub 会使用你 GitHub 账户中配置的 SSH 签名密钥来验证提交。

沙箱内无法使用 GPG 和 S/MIME 签名密钥。如果你的仓库或组织要求使用 GPG 或 S/MIME 签名，或者尚未配置 SSH 签名，请使用以下任一替代方案：

  • 在沙箱之外提交。让智能体完成改动但不提交，然后在你宿主机终端中提交并签名。

  • 事后签名。让智能体在沙箱内提交，然后在你宿主机上对这些提交重新签名：

    console
    $ git rebase --exec 'git commit --amend --no-edit -S' origin/main

    这会在分支上重放每个提交，并用你本地的签名密钥重新签名。

降级后守护进程无法启动 ​

如果你把 sbx 降级到比最后管理你本地状态的版本更旧的版本，守护进程可能会因 数据库版本不匹配而启动失败：

text
error: failed to start backend in-process: start backend: creating containerd
server: ... database is at major version 6, but this binary only supports up
to major version 1

较新版本的 sbx 把本地数据库升级到了旧版二进制无法理解的 schema。要恢复， 请重置所有沙箱状态：

console
$ sbx reset --preserve-secrets

这会停止所有 VM 并删除所有沙箱数据。之后你需要创建新的沙箱。 --preserve-secrets 标志会保留你已设置的任何密钥，这样就不必重新配置它们。

删除全部状态 ​

作为最后手段，如果 sbx reset 无法解决你的问题，可以彻底删除 sbx 状态目录。 这会删除所有沙箱数据、配置和缓存镜像。请先用 sbx reset 停止所有正在运行的 沙箱。

::: tabs ::: tab macOS

console
$ rm -rf ~/Library/Application\ Support/com.docker.sandboxes/

::: ::: tab Windows

powershell
> Remove-Item -Recurse -Force "$env:LOCALAPPDATA\DockerSandboxes"

::: ::: tab Linux

Linux 上的沙箱状态遵循 XDG 基础目录规范，分布在三个目录中：

console
$ rm -rf ~/.local/state/sandboxes/
$ rm -rf ~/.cache/sandboxes/
$ rm -rf ~/.config/sandboxes/

如果你自定义过 XDG_STATE_HOME、XDG_CACHE_HOME 或 XDG_CONFIG_HOME 环境 变量，请把 ~/.local/state、~/.cache 和 ~/.config 替换为对应的值。

::: :::

启用自动上传诊断信息 ​

如需在某些守护进程错误后自动上传诊断信息，请把 diagnostics.autoUpload 设置为 yes：

console
$ sbx settings set diagnostics.autoUpload yes

自动生成的包包含基本系统信息以及客户端、守护进程、崩溃和 MCP 日志。Docker Sandboxes 会遮蔽已识别的身份信息和凭据模式，但收集到的日志仍可能包含用户 内容。上传失败的包会保留在本地队列中，等待稍后重试。

报告问题 ​

如果你已经尝试了上述所有步骤而问题依然存在，请在 github.com/docker/sbx-releases/issues 提交 GitHub issue。

为帮助 Docker 排查问题，请生成诊断包并在报告问题时附上：

console
$ sbx diagnose --upload

该包包含守护进程日志、诊断检查结果和基本系统信息。确认 --upload 后，该包会 上传到 Docker 支持团队，命令会打印一个诊断 ID。请在 issue 中附上这个 ID，以便 团队把它与已上传的包关联起来。

在没有终端输入的情况下，sbx diagnose --upload 会把该包保存在本地并跳过上传。 请检查是否输出了诊断 ID，以确认上传成功。