> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker

> 运行本地可复现容器环境。

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

## 官方设置入口

| 需求                      | 链接                                                                                                  |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| 安装 Docker Desktop       | [Docker Desktop](https://docs.docker.com/desktop/)                                                  |
| macOS installer         | [Install Docker Desktop on Mac](https://docs.docker.com/desktop/setup/install/mac-install/)         |
| Windows installer       | [Install Docker Desktop on Windows](https://docs.docker.com/desktop/setup/install/windows-install/) |
| Linux Desktop installer | [Install Docker Desktop on Linux](https://docs.docker.com/desktop/setup/install/linux/)             |
| Linux server / CI 安装    | [Install Docker Engine](https://docs.docker.com/engine/install/)                                    |
| Ubuntu Engine 安装        | [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)                   |
| Linux post-install      | [Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/)          |
| Registry 登录             | [docker login](https://docs.docker.com/reference/cli/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 跑单任务，再提高并发。

```bash theme={null}
docker version
docker info
docker run --rm hello-world
```

在 Linux 上，如果 Docker 只能通过 `sudo` 运行，可以参考 Docker post-install 步骤，把当前用户加入 `docker` group：

```bash theme={null}
sudo groupadd docker
sudo usermod -aG docker "$USER"
newgrp docker
docker run --rm hello-world
```

<Note>
  `docker` group 拥有很高的主机权限。只应在你接受该安全边界的机器上这样配置。
</Note>

## Registry 凭据

AgentCompass 不管理 Docker registry credentials。镜像由本地 Docker daemon 拉取，因此请先用 Docker 登录：

```bash theme={null}
docker login
```

私有 registry 需要传 registry host：

```bash theme={null}
docker login registry.example.com
```

Docker Hub 自动化场景建议使用 Docker personal access token，而不是账号密码。

## AgentCompass Smoke Test

对于支持 recipe 的 benchmark，image 和 workspace 可以由 recipe 自动设置。建议先跑单个样本：

```bash theme={null}
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：

```bash theme={null}
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。

```bash theme={null}
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_root` | benchmark 未指定 workspace 时暴露给 harness 的 workspace root。 |
| `env`                    | 注入容器的环境变量。                                             |
| `mounts`                 | provider-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。                  |

## 相关页面

* [Recipes](/zh/key_modules/recipes)
* [执行环境概览](/zh/environments/overview)
* [Environment selection cookbook](/zh/cookbooks/first_runs/environment_selection)
* [配置参考](/zh/reference/configuration)