跳转到主要内容
Docker 是本地容器 provider。它适合需要本地可复现执行，或 benchmark recipe 可以把任务元数据映射到本地 registry image 的场景。

​
官方设置入口

需求链接
安装 Docker DesktopDocker Desktop
macOS installerInstall Docker Desktop on Mac
Windows installerInstall Docker Desktop on Windows
Linux Desktop installerInstall Docker Desktop on Linux
Linux server / CI 安装Install Docker Engine
Ubuntu Engine 安装Install Docker Engine on Ubuntu
Linux post-installLinux post-installation steps
Registry 登录docker login

​
首次设置

  1. 在 macOS、Windows 或桌面 Linux 上安装 Docker Desktop；Linux server 和 CI 机器通常安装 Docker Engine。
  2. 启动 Docker Desktop 或 Docker daemon。
  3. 验证本地 Docker client 可以连接 daemon。
  4. 如果需要私有镜像，先用 Docker 登录对应 registry。
  5. 先用 AgentCompass 跑单任务，再提高并发。
docker version
docker info
docker run --rm hello-world
在 Linux 上，如果 Docker 只能通过 sudo 运行，可以参考 Docker post-install 步骤，把当前用户加入 docker group： 
sudo groupadd docker
sudo usermod -aG docker "$USER"
newgrp docker
docker run --rm hello-world
docker group 拥有很高的主机权限。只应在你接受该安全边界的机器上这样配置。

​
Registry 凭据

AgentCompass 不管理 Docker registry credentials。镜像由本地 Docker daemon 拉取，因此请先用 Docker 登录： 
docker login
私有 registry 需要传 registry host： 
docker login registry.example.com
Docker Hub 自动化场景建议使用 Docker personal access token，而不是账号密码。

​
AgentCompass Smoke Test

对于支持 recipe 的 benchmark，image 和 workspace 可以由 recipe 自动设置。建议先跑单个样本： 
agentcompass run \
  swebench_verified \
  mini_swe_agent \
  your-model \
  --env docker \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
这个命令会一起验证 Docker image pull、container 启动、文件操作、harness 执行和 benchmark evaluation。

​
基础运行

对于 custom container task，显式传入 image： 
agentcompass run \
  <benchmark> \
  <harness> \
  <model> \
  --env docker \
  --env-params '{"image":"python:3.13-slim","workspace":"/workspace"}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
只有 custom task 或调试时才建议显式传 image。公开 benchmark 的 recipe 通常应该从任务元数据自动推导 image 和 workspace。 
agentcompass run \
  <benchmark> \
  <harness> \
  your-model \
  --env docker \
  --env-params '{"image":"python:3.13-slim","workspace":"/workspace"}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"

​
Provider 参数

常见 Docker 覆盖项可以放在 environments.docker 或 --env-params：
Field作用
image没有 recipe 提供镜像时使用的 Docker image。
name可选容器名；空值表示 AgentCompass 自动生成。
platform强制平台，例如 linux/amd64。适合任务镜像有特定架构要求时使用。
workspace容器工作目录，默认 /workspace。
command保持 task container 存活的长运行命令。
default_workspace_rootbenchmark 未指定 workspace 时暴露给 harness 的 workspace root。
env注入容器的环境变量。
mountsprovider-specific mount 定义。
在 Apple silicon 或 ARM 主机上，部分公开 benchmark image 可能只有 linux/amd64。当 Docker 报架构不匹配时可以设置 platform，但 emulation 会更慢。

​
何时使用 Docker

使用 Docker更适合 remote
需要本地可复现。任务镜像很大或本地启动很慢。
正在调试 environment 行为。希望高并发且不占用本地资源。
可以本地拉取 benchmark image。provider recipe 已经管理任务镜像和 workspace。

​
Troubleshooting

现象检查项
Cannot connect to the Docker daemon启动 Docker Desktop，或在 Linux Engine host 上运行 sudo systemctl start docker。
/var/run/docker.sock permission denied使用 sudo docker ...，或配置 Linux docker group。
no basic auth credentials对镜像所在 registry 运行 docker login。
no matching manifest检查主机架构并设置 platform，例如 linux/amd64。
容器能启动但命令失败确认镜像里有 shell、Python 或所需工具，并且 workspace 可写。
本地机器变慢降低 --task-concurrency，或切换到 Modal、Daytona 或集群 provider。

​
相关页面