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
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
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:
For a private registry, pass the registry host:
docker login registry.example.com
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"
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"
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. |
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
