Docker

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
macOS installer	Install Docker Desktop on Mac
Windows installer	Install Docker Desktop on Windows
Linux Desktop installer	Install Docker Desktop on Linux
Linux server / CI install	Install Docker Engine
Ubuntu Engine install	Install Docker Engine on Ubuntu
Linux post-install	Linux post-installation steps
Registry login	docker login

First-Time Setup

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

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:

sudo groupadd docker
sudo usermod -aG docker "$USER"
newgrp docker
docker run --rm hello-world

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

Registry Credentials

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

docker login

For a private registry, pass the registry host:

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:

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:

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.

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.

Get Started

Key Modules

Environments

Cookbooks

Official Setup Links

First-Time Setup

Registry Credentials

AgentCompass Smoke Test

Basic Run

Provider Params

When To Prefer Docker

Troubleshooting

​Official Setup Links

​First-Time Setup

​Registry Credentials

​AgentCompass Smoke Test

​Basic Run

​Provider Params

​When To Prefer Docker

​Troubleshooting

​Related Pages

Official Setup Links

First-Time Setup

Registry Credentials

AgentCompass Smoke Test

Basic Run

Provider Params

When To Prefer Docker

Troubleshooting

Related Pages