Docker

Docker provider 会为每次任务执行启动一个本地 Linux 容器，适合需要可复现文件系统和任务级隔离、又希望使用本地算力的评测。

AgentCompass 的本地 Docker provider 仅支持 Linux 和 WSL 2，不支持原生 macOS 或 Windows。匹配的 Recipe 可以补充镜像和工作区等默认值；兼容的显式参数通常会保留。

​

使用前准备

1. 在 Linux 安装 Docker Engine，或在 WSL 2 中安装 Docker Engine / 启用 Docker Desktop WSL 集成；不要同时连接两个 Docker 守护进程。
2. 确认当前用户可以非交互地访问 Docker。可以先运行 docker version 和 docker run --rm hello-world。
3. 私有镜像需要提前执行 docker login <registry>。AgentCompass 不保存或代管镜像仓库凭证。

Docker 守护进程具有较高的 host 权限。不要把不可信用户加入 docker 组，也不要随意挂载 host 上的敏感目录。

​

使用 run 验证配置

下面以 SWE-bench Verified 和 mini-swe-agent 为例。示例通过 sample_ids 只运行一个任务；匹配的 Recipe 会根据该任务补充镜像和工作区：

agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env docker \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}'

上面是 agentcompass run 的最小验证示例。模型端点等通用参数见 agentcompass run。

Docker 同样支持 agentcompass launch。在编排文件的 defaults.environment 中设置所有请求共享的 Docker 配置，或在 requests[].environment 中设置单个请求；id: docker 与 Docker 参数写在同一层。详见 launch 的映射规则。

​

参数参考

参数可以通过 --env-params 传入，也可以写在配置文件的 environments.docker 中。

上面的示例由 Recipe 补充任务镜像。将以下选项添加到该命令，可以把每个任务容器限制为 2 核 CPU 和 6 GiB 内存：

--env-params '{"cpus":2,"memory":"6g"}'

​

连接与凭证

Docker provider 不接收镜像仓库凭证；Docker CLI 会读取执行该命令的用户所配置的凭据。请先以同一用户运行 docker login；启用 use_sudo_docker 后，还要确认 sudo 执行身份能够读取相应凭据。

字段	默认值	说明
use_sudo_docker	false	是否使用 sudo -n docker 连接 Docker daemon。只有已经配置免密、非交互式 sudo 时才能启用。

​

镜像与启动

字段	默认值	说明
image	未设置（创建前必填）	任务使用的容器镜像，例如 python:3.12-slim。最终必须由 Recipe 或显式配置提供，并包含 Benchmark 与 Harness 需要的命令、依赖和目录。
platform	Docker 默认值	覆盖镜像目标平台，例如 linux/amd64。当所需镜像变体与 Docker daemon 所在 host 的架构不同时设置。
command	["tail","-f","/dev/null"]	用于保持容器运行的启动命令。字符串会通过 bash -lc 执行，因此镜像必须包含 bash；字符串列表会直接作为命令及其参数执行。

​

标识与元数据

字段	默认值	说明
name	自动生成	Docker 容器名。通常应留空；并发创建容器、保留 Environment 或前次清理失败时，固定名称会发生冲突。Docker provider 不提供其他标签或元数据参数。

​

工作区与环境变量

字段	默认值	说明
workspace	/workspace	容器内执行任务命令的绝对路径，对应 Docker 的 —workdir；目录不存在时由 Docker 创建。该路径应与镜像中的项目或任务根目录一致。
default_workspace_root	/workspace/	Benchmark 未指定任务工作目录时，提供给 Harness 的默认 workspace root；不会改变 workspace 设置的容器工作目录。
env	{}	以对象形式提供的环境变量，按 key=value 注入任务容器；建议值使用字符串。不要把长期凭证写进公开配置文件。
mounts	[]	Docker 挂载列表。每项可以是 source:target[:mode] 字符串，也可以是含 source、target 和可选 mode 的对象；source 是 host 路径或 Docker volume，target 是容器内绝对路径，mode 例如 ro 或 rw。

​

资源

字段	默认值	说明
cpus	未设置	单个任务容器可使用的 CPU 核数，必须为正数，可以使用 1.5 等小数。未设置时不向 Docker 传入 CPU 上限。
memory	未设置	容器内存上限。只接受正整数，可选 b、k、m 或 g 后缀且不区分大小写，例如 8g 或 8192m。不写后缀时单位为字节；k、m、g 分别按 1024 的幂换算。
memory_swap	未设置	内存与 swap 的总上限；必须同时设置 memory。使用与 memory 相同的整数及可选后缀格式，另接受 -1；与 memory 相同表示禁用额外 swap，-1 表示不限制 swap。
gpus	未设置	传给 Docker --gpus 的值，例如 all；host 必须已经配置 GPU 容器运行时。
storage_opt	{}	传给 Docker 的每容器存储选项，例如 {"size":"20g"}。键不能为空且不能包含 =，值不能为空；Docker 仅在部分存储驱动上支持 size，overlay2 还要求 XFS backing filesystem 启用 pquota。

​

网络

字段	默认值	说明
network	未设置；外部连接使用 Docker bridge	public 任务容器以及网络策略代理连接外部网络时使用的 Docker 网络。阶段间需要切换策略时，必须使用 bridge 类型网络。
allowlist_proxy_image	python:3.12-alpine	使用 allowlist 或在阶段间切换网络策略时，网络策略代理使用的容器镜像；镜像必须包含可执行的 python。仅在需要固定镜像源或内部镜像仓库时覆盖。

通用网络阶段和资源配置方法分别见网络策略和资源限制。

​

生命周期与超时

字段	默认值	说明
allowlist_proxy_start_timeout	60	使用 allowlist 或在阶段间切换网络策略时，等待网络策略代理容器就绪的秒数，必须为正数。镜像拉取或 Docker daemon 较慢时可以增加。

Docker provider 不提供独立的任务容器生命周期或命令超时参数。Environment 正常关闭时会自动删除容器；使用 --keep-environment 可以保留容器，评测总超时由运行控制设置。

​

参数参考来源

• 运行 agentcompass config docs env docker，可以查看当前安装版本实际支持的字段、类型和默认值。
• Docker 原生参数的行为与限制见 docker container run 和 Resource constraints。

支持的字段、类型和默认值以 agentcompass config docs env docker 的输出为准；Docker 对镜像、挂载和资源选项的解释，以所连接 Docker daemon 的版本与官方文档为准。

​

特有行为

• image 在 Recipe 和显式配置合并后仍为空时，任务会在创建容器前报错。
• 固定 name 会被该 provider 创建的所有任务容器复用。并发创建、使用 --keep-environment，或上一次清理失败后再次创建时会发生名称冲突，因此通常应使用自动名称。
• 正常关闭 Environment 时会强制删除任务容器；使用 --keep-environment 时，AgentCompass 不执行这一步。
• command 必须让容器保持运行，否则后续 Harness 命令无法执行。

​

故障排查

现象	检查内容
Cannot connect to the Docker daemon	确认 Docker 守护进程已启动，并确认 AgentCompass 与 docker 命令连接的是同一个守护进程。
/var/run/docker.sock 权限不足	按 Docker 的 Linux 安装后说明配置权限，或在确有需要时启用 use_sudo_docker。
no basic auth credentials	对镜像所在仓库重新执行 docker login。
no matching manifest	检查镜像架构；必要时设置 platform。
容器刚启动就退出	检查镜像是否包含 command 使用的程序，并确保该命令是长运行命令。
创建容器时提示名称已存在	删除不再需要的旧容器，或移除固定 name。

​

相关页面

• Environment 概览
• 配置 Environment
• 运行控制
• CLI 配置文件