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

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.

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 \
  "$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:

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:

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 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
• Network Policy
• Sandbox Resource Limits
• Environments Overview
• Configuration Reference