让 Sandbox 使用 Docker

当评估任务要求 Agent执行 docker build、docker run或 docker compose时，先按任务的信任边界选择 Docker access：

模式	什么时候用	启动成本	安全边界
Docker socket	可信 Agent、个人开发机、已有 daemon，优先启动速度	最低，共用已有 daemon	Agent拥有该 daemon的完整控制权。rootful socket通常等价宿主 root
Raw privileged DinD	一次性 VM或专用 runner，需要独立 image、network和 cache	每个 Sandbox启动 inner daemon	outer container是 raw privileged，不是安全隔离方案
Managed rootless DinD	不可信 Agent、共享宿主、并发评估、需要资源准入和强杀恢复	最高，需要宿主 profile	privileged限制在受管 rootless user namespace或专用 VM，并有 watchdog与容量契约

三种模式都要求镜像预装 Docker CLI。两种 DinD模式只接受从官方 docker:<version>-dind派生的兼容镜像。镜像需要 Docker daemon、Node和评估工具，但不需要自定义 NiceEval ENTRYPOINT。NiceEval负责启动与监督 inner daemon、 Sandbox保活、容器内 TTL和 docker info探活，不会向任意镜像动态安装 Docker。不能直接把未经派生的 docker:<version>-dind写成 source.image。该镜像没有 NiceEval supervisor 需要的 Node，也没有被测 Agent的工具。创建时会以 dind-image-incompatible: missing node失败。请使用下面的 Dockerfile，或先发布等价的派生镜像，再让 source引用它。

方案一：直接挂 Docker socket

先准备只有 CLI、Node和评估工具的镜像：

sandbox/Dockerfile

FROM docker:29-cli

RUN apk add --no-cache ca-certificates git nodejs npm python3 \
  && addgroup -g 1000 node \
  && adduser -D -u 1000 -G node node

在 Experiment里显式填写宿主 Unix socket。NiceEval不会从进程环境或 Docker context猜这个路径：

experiments/docker-socket.ts

import { defineExperiment } from "niceeval";
import { codexAgent } from "niceeval/adapter";
import { dockerSandbox } from "niceeval/sandbox";

export default defineExperiment({
  agent: codexAgent(),
  model: "gpt-5.4",
  sandbox: dockerSandbox({
    source: {
      type: "dockerfile",
      context: new URL("../sandbox/", import.meta.url),
    },
    user: "node",
    dockerAccess: {
      mode: "socket",
      socketPath: "/var/run/docker.sock",
    },
  }),
});

NiceEval会解析 symlink、确认最终目标是 Unix socket，把它挂到 Sandbox内固定的 /var/run/docker.sock，并按 socket的数值 GID给 node添加补充组。启动 Agent前，NiceEval会确认镜像没有预设 Docker endpoint或 context，而且默认 docker info与显式访问这个 Unix socket得到同一个 daemon。CLI缺失、用户无法访问 socket或镜像把默认 endpoint改到别处时，Sandbox创建失败。这项检查只固定 Agent启动时的默认用法，不是安全边界。Agent之后仍可显式传 docker --host访问另一个 endpoint。不可信任务需要依赖 managed模式的网络策略，而不是依赖 Docker CLI的默认值。

这不是隔离方案。Agent可以通过 socket创建 privileged容器、挂宿主目录，并操作同一 daemon上的其它容器、image、volume和 network。不要给不可信 Agent挂 rootful宿主 socket。

方案二：Docker-in-Docker

DinD让每个外层 Sandbox拥有自己的 inner daemon。先创建镜像：

sandbox/Dockerfile

FROM docker:29-dind

RUN apk add --no-cache ca-certificates git nodejs npm python3 \
  && addgroup -g 1000 node \
  && adduser -D -u 1000 -G node node \
  && addgroup node docker

生产评估应把 FROM钉到审核过的 digest，并把被测 Agent需要的固定 CLI烘焙进镜像。

NiceEval 如何启动 DinD

选择 dockerAccess: { mode: "dind", ... } 就同时选择了 NiceEval 的 DinD 镜像协议。 provider 会覆盖派生镜像的原有 ENTRYPOINT 和 CMD，先检查 docker-init、 node、docker、dockerd-entrypoint.sh、timeout 和 tail，再启动自己的 supervisor。supervisor 同时监督官方 dockerd-entrypoint.sh dockerd与 Sandbox 保活进程。任一进程提前退出都会停止 outer container，而不会留下一台看似存活但无法使用 Docker 的 Sandbox。 inner daemon 只监听 /var/run/docker.sock，不开放 2375/2376 TCP endpoint。 Agent 仍以 user: "node" 运行。上面 Dockerfile 在构建期把 node 加入 docker 组，因此不需要 chown root:node 或 chmod 666 socket。如果镜像缺少工具、用户不在 docker 组、daemon 提前退出或 readiness 超时，NiceEval 会在删除创建失败的容器前收集有界日志尾部并报出可操作的原因。派生镜像不要设置 DOCKER_HOST 或 DOCKER_CONTEXT。NiceEval 会先确认默认 context，再核对不带 endpoint 选项的 docker info 与显式 /var/run/docker.sock 是否到达同一个 daemon。这项 compatibility check 通过后，才会执行作者声明的 readiness。这个协议不承诺保留任意 service image 的启动语义。如果你要评测一个必须依赖自己 ENTRYPOINT / CMD 的服务组，应该使用 Compose Sandbox，由 Compose 声明服务进程。

在 setup 中准备 Attempt 运行时

Dockerfile 只烘焙固定工具、只读归档和项目初始文件。需要 inner daemon 的操作放进 Sandbox 级 setup，不要放进镜像 ENTRYPOINT。下面的 setup 可以导入离线 image、把项目初始文件复制到可写 workspace，并运行项目自己的 smoke check：

lib/dind-sandbox.ts

import { dockerfileSandbox } from "niceeval/sandbox";

export const dindSandbox = dockerfileSandbox({
  context: new URL("../sandbox/", import.meta.url),
  user: "node",
  dockerAccess: {
    mode: "dind",
    isolation: "raw-privileged",
  },
  readiness: {
    command: ["docker", "info"],
    user: "node",
    timeoutMs: 30_000,
  },
}).setup(async (sandbox, ctx) => {
  ctx.progress({ message: "准备 inner Docker 运行时" });
  const result = await sandbox.runCommand("prepare-inner-runtime", [], {
    user: "root",
    stream: true,
  });
  if (result.exitCode !== 0) {
    throw new Error(result.stderr || "inner Docker 运行时准备失败");
  }
});

NiceEval 会先启动并验证 inner daemon，再执行这个 setup，最后运行 Agent。setup 非零退出时， Attempt 在 sandbox.create 阶段记为 errored，不会把半成品 Sandbox 交给 Agent。固定内容留在 image layer，每个 Attempt 只复制或导入必须写入 tmpfs 或 inner data-root 的状态，可以减少重复安装和网络漂移。

Raw privileged DinD

在一次性 VM或专用 runner上，可以显式选择 raw privileged：

experiments/dind-raw.ts

import { defineExperiment } from "niceeval";
import { codexAgent } from "niceeval/adapter";
import { dockerSandbox } from "niceeval/sandbox";

export default defineExperiment({
  agent: codexAgent(),
  model: "gpt-5.4",
  sandbox: dockerSandbox({
    source: {
      type: "dockerfile",
      context: new URL("../sandbox/", import.meta.url),
    },
    user: "node",
    dockerAccess: {
      mode: "dind",
      isolation: "raw-privileged",
    },
  }),
});

必填的 raw-privileged字面量是风险授权。NiceEval不会把 raw模式描述成 rootless，也不会在失败时自动改用 managed profile。

Managed rootless DinD

共享宿主或不可信 Agent使用 managed模式。它在 inner daemon之外增加 profile attestation、单容器资源限制、跨进程容量准入、独占外层网络和 watchdog恢复：

experiments/dind-managed.ts

import { defineExperiment } from "niceeval";
import { codexAgent } from "niceeval/adapter";
import { dockerSandbox } from "niceeval/sandbox";

const GiB = 1024 ** 3;
const MiB = 1024 ** 2;

export default defineExperiment({
  agent: codexAgent(),
  model: "gpt-5.4",
  maxConcurrency: 4,
  sandbox: dockerSandbox({
    source: {
      type: "dockerfile",
      context: new URL("../sandbox/", import.meta.url),
    },
    user: "node",
    dockerAccess: {
      mode: "dind",
      isolation: "managed-rootless",
      profile: "default",
    },
    resources: {
      cpus: 4,
      memoryBytes: 6 * GiB,
      pidsLimit: 2048,
      readOnlyRootfs: true,
      tmpfs: {
        "/var/lib/docker": { sizeBytes: 3 * GiB, mode: 0o711, executable: true },
        "/home/sandbox/workspace": {
          sizeBytes: 2 * GiB,
          mode: 0o755,
          uid: 1000,
          gid: 1000,
          executable: true,
        },
        "/home/node": { sizeBytes: 512 * MiB, mode: 0o700, uid: 1000, gid: 1000 },
        "/tmp": { sizeBytes: 1024 * MiB, mode: 0o1777 },
        "/run": { sizeBytes: 128 * MiB, mode: 0o755 },
      },
    },
  }),
});

profile缺失、拼错、attestation失败或容量不足时，NiceEval会在模型调用前失败，绝不降级成 raw privileged。宿主部署完成后先检查 profile：

npx niceeval docker profile list
npx niceeval docker profile doctor default --smoke
npx niceeval exp dind-managed

doctor --smoke会在该 profile上启动一次 DinD容器，并实际运行内层 docker run --rm alpine:3.20 true。它证明 profile支持 nested Docker，但不会检查项目自己的 Dockerfile。项目镜像仍由默认 docker info readiness验证。

为 DinD 设置运行并发

resources.memoryBytes 限制一台 Sandbox，不会自动设置 Run 的并发数。DinD 还会占用 inner image、BuildKit、tmpfs 和 page cache，默认并发对本机可能过高。先用较小并发完成 smoke run：

pnpm exec niceeval exp dind-managed --max-concurrency 2

再根据宿主的可用内存、CPU 和磁盘吞吐逐步增加。可以先用 可用内存 ÷ memoryBytes 估算保守上限，同时为宿主 Docker、NiceEval 和其它进程留余量。 Experiment 只服务这类重型 Sandbox 时，也可以直接设置 maxConcurrency。

定位 DinD 创建失败

创建失败后使用终端给出的 Attempt 定位符，不要直接翻运行产物：

pnpm exec niceeval show @1ABC234DEF

常见错误与处理方式：

公开错误	处理方式
`DOCKER_HOST must be unset` 或 `DOCKER_CONTEXT must be unset`	删除镜像里的 endpoint/context 环境变量，让默认 endpoint 指向 `/var/run/docker.sock`
`dind-image-incompatible: missing ...`	从固定版本 `docker:<version>-dind` 派生，并补齐错误列出的工具
`permission denied`	在构建期把 `user` 对应的 Agent 用户加入镜像内 `docker` 组
Docker access compatibility timeout	从 `niceeval show` 给出的有界 `dockerd.log` 尾部检查 daemon 启动、socket 与 storage driver
启动前提示 orphan Sandbox	先用 `niceeval sandbox list --orphans` 只读核对，再显式运行 `niceeval sandbox prune`

在 Eval里验证 Docker任务

三种模式对 Eval暴露相同的 Docker CLI用法：

evals/docker-compose.eval.ts

import { defineEval } from "niceeval";
import { commandSucceeded } from "niceeval/expect";

export default defineEval({
  description: "Agent can repair and start a Docker Compose project",
  async test(t) {
    await t.send("修复 Compose 项目，然后启动服务并确认健康检查通过。");

    t.check(
      await t.sandbox.runCommand("docker", ["run", "--rm", "alpine:3.20", "true"]),
      commandSucceeded(),
    );
  },
});

socket模式的命令操作显式选择的外层 daemon。两种 DinD模式操作 Sandbox内的 inner daemon。 sandbox也可以直接写在 defineEval({ sandbox: ... })里。多条 Eval共用配置时写在 Experiment上。

开始使用

连接 Agent

编写评估

运行、观察与发布

问题排查

让 Sandbox 使用 Docker

方案一：直接挂 Docker socket

方案二：Docker-in-Docker

NiceEval 如何启动 DinD

在 setup 中准备 Attempt 运行时

Raw privileged DinD

Managed rootless DinD

为 DinD 设置运行并发

定位 DinD 创建失败

在 Eval里验证 Docker任务

​方案一：直接挂 Docker socket

​方案二：Docker-in-Docker

​NiceEval 如何启动 DinD

​在 setup 中准备 Attempt 运行时

​Raw privileged DinD

​Managed rootless DinD

​为 DinD 设置运行并发

​定位 DinD 创建失败

​在 Eval里验证 Docker任务

方案一：直接挂 Docker socket

方案二：Docker-in-Docker

NiceEval 如何启动 DinD

在 setup 中准备 Attempt 运行时

Raw privileged DinD

Managed rootless DinD

为 DinD 设置运行并发

定位 DinD 创建失败

在 Eval里验证 Docker任务