> ## 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={null}
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={null}
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={null}
docker login
```

For a private registry, pass the registry host:

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

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={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"
```

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

```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 Params

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

| Field                    | Use                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| `image`                  | Docker image to run when no recipe supplies one.                                           |
| `name`                   | Optional container name. Empty means AgentCompass auto-generates one.                      |
| `platform`               | Force a platform such as `linux/amd64`. Useful when task images are architecture-specific. |
| `workspace`              | Container working directory. Defaults to `/workspace`.                                     |
| `command`                | Long-running command used to keep the task container alive.                                |
| `default_workspace_root` | Workspace root exposed to harnesses when the benchmark did not set one.                    |
| `env`                    | Environment variables injected into the container.                                         |
| `mounts`                 | Provider-specific mount definitions.                                                       |

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.

## 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](/key_modules/recipes)
* [Environments Overview](/environments/overview)
* [Environment selection cookbook](/cookbooks/first_runs/environment_selection)
* [Configuration Reference](/reference/configuration)