> ## 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

> Run reproducible local container environments.

Docker is the local container provider. Use it when you want reproducible execution without a cloud sandbox, or when a benchmark recipe can map task metadata to a local registry image.

## Official Setup Links

| Need                      | Link                                                                                                |
| ------------------------- | --------------------------------------------------------------------------------------------------- |
| Install 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 | [Install Docker Engine](https://docs.docker.com/engine/install/)                                    |
| Ubuntu Engine install     | [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 login            | [docker login](https://docs.docker.com/reference/cli/docker/login/)                                 |

## First-Time Setup

1. Install Docker Desktop on macOS, Windows, or desktop Linux. For Linux servers and CI machines, install Docker Engine.
2. Start Docker Desktop or the Docker daemon.
3. Verify that the local Docker client can talk to the daemon.
4. If you need private images, authenticate with the registry before running AgentCompass.
5. Run one AgentCompass task before scaling concurrency.

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

On Linux, if Docker works only with `sudo`, follow Docker's post-install steps to add your user to the `docker` group:

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

<Note>
  Membership in the `docker` group grants broad host privileges. Use it only on machines where that security tradeoff is acceptable.
</Note>

## Registry Credentials

AgentCompass does not manage Docker registry credentials. The local Docker daemon pulls images, so authenticate with Docker first:

```bash theme={"system"}
docker login
```

For a private registry, pass the registry host:

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

For Docker Hub automation, prefer a Docker personal access token instead of an account password.

## AgentCompass Smoke Test

For supported benchmarks, recipes may set the image and workspace for you. Start with one sample:

```bash theme={"system"}
agentcompass run \
  swebench_verified \
  mini_swe_agent \
  "$MODEL_NAME" \
  --env docker \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
```

This validates Docker image pull, container startup, file operations, harness execution, and benchmark evaluation together.

## Basic Run

For custom container tasks, pass an image explicitly:

```bash theme={"system"}
export MODEL_NAME=""

agentcompass run \
  <benchmark> \
  <harness> \
  "$MODEL_NAME" \
  --env docker \
  --env-params '{"image":"python:3.13-slim","workspace":"/workspace"}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
```

Use explicit `image` only for custom tasks or debugging. Public benchmark recipes should normally infer the image and workspace from task metadata.

## Provider Params

Docker overrides live under `environments.docker` or `--env-params`:

| Field                           | Default                     | How to use it                                                                                                                               |
| ------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `image`                         | Recipe value or required    | Let a benchmark recipe set it. Pass a registry image only for custom tasks or intentional debugging.                                        |
| `name`                          | Generated                   | Set a stable name only when an external debugging workflow needs it; names must be unique across concurrent tasks.                          |
| `platform`                      | Docker default              | Use `linux/amd64` only when the image has no native manifest for the host architecture.                                                     |
| `workspace`                     | `/workspace`                | Match the repository or task root inside the image. Prefer the recipe-provided path for public benchmarks.                                  |
| `command`                       | `["tail","-f","/dev/null"]` | Keep the default unless the image needs another long-running entry command.                                                                 |
| `default_workspace_root`        | `/workspace/`               | Fallback exposed to harnesses when the benchmark does not provide a workspace.                                                              |
| `env`                           | `{}`                        | Inject task-container variables. Do not put reusable secrets in a committed config file.                                                    |
| `mounts`                        | `[]`                        | Add Docker volume strings or objects with `source`, `target`, and optional `mode`; use read-only mounts where possible.                     |
| `gpus`                          | Unset                       | Pass the value accepted by Docker `--gpus`, such as `all`; requires a configured GPU container runtime.                                     |
| `cpus`                          | Unset                       | Set a positive core limit. For concurrency `n`, confirm the host can sustain roughly `n × cpus` plus Docker overhead.                       |
| `memory`                        | Unset                       | Set a Docker size such as `8g`. Start from benchmark metadata or observed peak usage rather than an arbitrary low cap.                      |
| `memory_swap`                   | Unset                       | Requires `memory`; set equal to `memory` to disable swap or `-1` for unlimited swap.                                                        |
| `storage_opt`                   | `{}`                        | Set per-container storage options such as `{"size":"20g"}` only when the Docker storage driver supports them.                               |
| `use_sudo_docker`               | `false`                     | Use only when passwordless non-interactive `sudo docker` is intentionally configured. Normal Linux setup should grant direct daemon access. |
| `network`                       | Docker default bridge       | Select the public-phase network. Dynamic phase policies require a bridge-style network.                                                     |
| `allowlist_proxy_image`         | `python:3.12-alpine`        | Override only for an internal registry or pinned mirror of the egress proxy runtime.                                                        |
| `allowlist_proxy_start_timeout` | `60`                        | Increase only when the egress proxy image or daemon starts slowly.                                                                          |

For example, limit a custom container to two CPUs and 8 GiB of memory with no swap:

```bash theme={"system"}
agentcompass run \
  <benchmark> \
  <harness> \
  "$MODEL_NAME" \
  --env docker \
  --env-params '{"image":"python:3.13-slim","cpus":2,"memory":"8g","memory_swap":"8g"}'
```

Recipes may infer resource defaults from benchmark task metadata. Explicit `--env-params` values take precedence. `storage_opt.size` is not inferred automatically because per-container filesystem quotas are unavailable on some Docker storage drivers.

On Apple silicon or ARM hosts, some public benchmark images may be `linux/amd64` only. Set `platform` when Docker reports an architecture mismatch, but expect emulation to be slower.

Use the provider-neutral phase fields documented in [Network Policy](/en/user_guide/modules/environments/network) instead of
setting `network` to `none` when setup, rollout, and verification need different policies.

## When To Prefer Docker

| Use Docker when                           | Prefer remote when                                           |
| ----------------------------------------- | ------------------------------------------------------------ |
| You need local reproducibility.           | Task images are large or slow to start locally.              |
| You are debugging environment behavior.   | You want high concurrency without local resource contention. |
| You can pull the benchmark image locally. | Provider recipes already manage task images and workspaces.  |

## Troubleshooting

| Symptom                                        | What to check                                                                           |
| ---------------------------------------------- | --------------------------------------------------------------------------------------- |
| `Cannot connect to the Docker daemon`          | Start Docker Desktop or run `sudo systemctl start docker` on Linux Engine hosts.        |
| `permission denied` for `/var/run/docker.sock` | Use `sudo docker ...` or configure the Linux `docker` group.                            |
| `no basic auth credentials`                    | Run `docker login` for the registry that hosts the image.                               |
| `no matching manifest`                         | Check host architecture and set `platform`, for example `linux/amd64`.                  |
| Container starts but commands fail             | Confirm the image has a shell, Python or required tools, and a writable workspace.      |
| Local machine becomes slow                     | Reduce `--task-concurrency` or switch the run to Modal, Daytona, or a cluster provider. |

## Related Pages

* [Recipes](/en/user_guide/recipes)
* [Network Policy](/en/user_guide/modules/environments/network)
* [Sandbox Resource Limits](/en/user_guide/modules/environments/resource_limits)
* [Environments Overview](/en/user_guide/modules/environments/overview)
* [Configuration Reference](/en/user_guide/overview#configuration-files-and-precedence)