Docker Sandboxes

当某个 Kit 的 install 或 startup 命令失败时，sbx 会告诉你是哪条命令失败了、属于哪个 Kit，以及完整输出在哪里。本页讲解如何阅读这些输出、在沙箱内找到日志，以及修复常见原因。

阅读进度输出 ​

在 sbx create 和 sbx run 期间，配置智能体阶段会为每个 Kit 操作打印一行：install 命令、init 文件、文件复制、环境变量，以及它注册的 startup 命令。完成的行会显示 ✓ 和耗时，失败的行会显示 ✗ 和退出码。

如果 Kit 设置了 description，命令行就会显示它。否则显示命令的前 60 个字符。命令行还会显示拥有该命令的 Kit（kit=<name>）以及它以哪个用户运行（user=<uid>）。

为每条 install 和 startup 命令设置 description，这样这一行就能说明命令的用途。保持简短：一行最多只显示它的 60 个字符。

yaml
capabilities:
  - type: com.docker.sandbox/lifecycle@1
    config:
      install:
        - command: apt-get update && apt-get install -y ripgrep
          user: "0"
          description: Install ripgrep
      startup:
        - command: rg --version > /tmp/rg-version
          description: Record the ripgrep version

这个 Kit 的各行看起来是这样的：

text
AGENT
    running 1 install command
      ✓ Install ripgrep (kit=my-kit, user=0, 12.4s)
      view install logs: ls /var/log/sbx-kits
    registering 1 startup command, run on every container start
      ○ Record the ripgrep version (kit=my-kit, user=agent)
      view startup log: cat /var/log/sbx-kit-startup.log

查看失败的 install 命令 ​

失败的 install 命令会在该行下方打印其输出的最后 40 行，紧接着是一行 docker run 命令，它在 Kit 的基础镜像上运行同一条命令：

text
  ✗ Install ripgrep (kit=my-kit, user=0, exit 100)
    ── captured output ──
    E: Failed to fetch http://deb.debian.org/debian/dists/bookworm/InRelease  403  Forbidden
    E: Unable to locate package ripgrep
    ──────────────────────
  hint: reproduce locally with:
    docker run --rm -u 0 <base-image> sh -c 'apt-get update && apt-get install -y ripgrep'

复制这行 docker run 命令，就可以在每次都重新创建沙箱之外反复调试该命令。改动命令、再次运行，然后把可用的版本复制回 Kit。这个复现运行在普通 Docker 中，位于沙箱之外，因此沙箱的网络策略不适用。如果命令在那里能正常工作，却在沙箱中失败，请先检查该 Kit 的网络规则。

在沙箱内查找日志 ​

进度输出只显示失败命令的末尾部分。沙箱会保留完整的记录：

日志内容
/var/log/sbx-kits/<kit>/install-<n>.log一条 install 命令的完整输出。<n> 是该命令在该 Kit 的 install 列表中的位置，从 0 开始。
/var/log/sbx-kit-startup.log每次容器启动时所有 startup 命令的输出。

用 sbx exec 读取其中任一日志：

console
$ sbx exec my-sandbox cat /var/log/sbx-kits/my-kit/install-0.log
$ sbx exec my-sandbox cat /var/log/sbx-kit-startup.log

Startup 命令会在每次容器启动时运行。每条命令都会向 startup 日志写入以下几行：

text
> <script>
# <kit>: <description or command>
<the command's output>
ok <script>

失败的命令会以 fail <script> exit=<code> 结尾，而不是 ok。它还会阻止其后的 startup 命令继续执行，而启动该沙箱的命令（sbx create、sbx run、sbx stop 之后的 sbx exec，或 sbx kit add）会打印一条警告，指向 startup 日志并附带它的最后几行。沙箱仍然可用。

创建阶段结束后，智能体会接管终端。沙箱内的日志才是你可以回头查阅的记录。

用 -D 显示全部内容 ​

给 sbx create 或 sbx run 传入全局调试标志：

console
$ sbx -D create --name my-sandbox shell --kit ./my-kit

加上 -D 后，每条成功的 install 命令也会在它那一行下方流式输出完整内容，并且 sbx 会在沙箱启动后打印 startup 日志。

sbx 会屏蔽哪些内容 ​

Kit 命令打印的所有内容都会经过同一个过滤器到达你的终端。它会移除终端转义序列，并把已知形态的凭据（例如 GitHub、GitLab、OpenAI、Anthropic 和 AWS 令牌、JSON Web Token、私钥以及 Authorization 请求头）替换成 <GITHUB_TOKEN> 这样的占位符。这个过滤器可以防止命令意外回显你自己的机密信息，例如 env 输出中的令牌，或者配置转储中的密钥。它不是针对刻意构造的输出的防护手段，也不会改动你写进 Kit 自身命令文本中的机密信息。沙箱内的 install 日志保留原始输出。

常见原因 ​

install 命令无法访问它的软件包源 ​

日志中显示无法解析的域名，或者来自 apt、pip、npm 的 HTTP 403 响应。该 Kit 在 install 阶段的网络规则没有包含这个软件包镜像仓库。把它加到 com.docker.sandbox/network-policy@1 能力的 install.allow 中。例如，apt 的镜像仓库可能与命令中写的主机不是同一台。

两个 Kit 同时运行 apt ​

日志中显示 Could not get lock /var/lib/dpkg/lock-frontend。另一条 install 命令或基础镜像的设置占用了 dpkg 锁。在 Kit 中重试该软件包命令，例如给 apt-get 加上 -o DPkg::Lock::Timeout=120。

startup 命令需要某个没有安装成功的工具 ​

在针对该工具的 install 命令失败之后，startup 日志显示 exec: <tool>: not found。请先修复 install 命令。查看它的 install-<n>.log，然后重新运行沙箱。

命令需要 root 权限 ​

当命令写入系统路径或安装软件包时，日志显示 Permission denied，并且该行显示 user=1000。在 install 命令上设置 user: "0"，或者改为写入智能体用户拥有的位置。

后续步骤 ​