> ## 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 The Docker provider starts one local Linux container for each task execution. Use it when you want a reproducible filesystem and task-level isolation while keeping compute on the local host. AgentCompass supports this local Docker provider on Linux and WSL 2 only, not on native macOS or Windows. A matched [recipe](/en/user_guide/other_features/recipes) can supply defaults such as the image and workspace; compatible explicit settings are usually preserved. ## Before You Start 1. Install [Docker Engine](https://docs.docker.com/engine/install/) on Linux, or install Docker Engine / enable [Docker Desktop WSL integration](https://docs.docker.com/desktop/features/wsl/) in WSL 2. Do not connect the same workflow to two Docker daemons. 2. Make sure the current user can access Docker non-interactively. You can first run `docker version` and `docker run --rm hello-world`. 3. For private images, run `docker login ` before AgentCompass. AgentCompass does not store or manage registry credentials. The Docker daemon has broad host privileges. Do not add untrusted users to the `docker` group, and do not mount sensitive host directories without reviewing the access granted to the container. ## Validate the Configuration with `run` This example uses SWE-bench Verified with mini-swe-agent. It selects one task through [`sample_ids`](/en/user_guide/modules/benchmarks/overview#shared-benchmark-fields), and the matched recipe supplies its image and workspace: ```bash theme={"system"} agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \ --env docker \ --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' ``` The command above is a minimal `agentcompass run` check. See [`agentcompass run`](/en/user_guide/using_agentcompass/cli/run) for model endpoint and other shared options. Docker also supports `agentcompass launch`. Put shared Docker settings under `defaults.environment` in the orchestration file, or request-specific settings under `requests[].environment`; write `id: docker` and the Docker parameters at the same level. See the [`launch` mapping rules](/en/user_guide/using_agentcompass/cli/launch#mapping-rules). ## Parameter Reference Pass parameters with `--env-params`, or place them under `environments.docker` in a configuration file. The recipe in the example above supplies the task image. Add the following option to limit each task container to 2 CPU cores and 6 GiB of memory: ```bash theme={"system"} --env-params '{"cpus":2,"memory":"6g"}' ``` ### Connection and Credentials The Docker provider does not accept registry credentials. The Docker CLI reads credentials configured for the user that executes the command. Run [`docker login`](https://docs.docker.com/reference/cli/docker/login/) as that user first; when `use_sudo_docker` is enabled, also make sure the sudo execution identity can read the required credentials. | Field | Default | Meaning | | ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `use_sudo_docker` | `false` | Whether to connect to the Docker daemon through `sudo -n docker`. Enable it only when passwordless, non-interactive sudo is already configured. | ### Image and Startup | Field | Default | Meaning | | ---------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `image` | Unset (required before creation) | Container image used by the task, for example `python:3.12-slim`. A recipe or explicit configuration must provide a final value containing the commands, dependencies, and directories required by the Benchmark and Harness. | | `platform` | Docker default | Overrides the target platform, for example `linux/amd64`. Set it when the image platform does not match the Docker host's CPU architecture. | | `command` | `["tail","-f","/dev/null"]` | Startup command that keeps the container running. A string runs through `bash -lc`, so the image must contain `bash`; a list of strings is passed directly as argv. | ### Identity and Metadata | Field | Default | Meaning | | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Generated | Docker container name. Normally leave this empty; a fixed name conflicts during concurrent creation, when an Environment is kept, or after a previous cleanup failure. The Docker provider exposes no other tag or metadata parameters. | ### Workspace and Environment Variables
FieldDefaultMeaning
workspace/workspaceAbsolute path inside the container where task commands run, passed as Docker --workdir. Docker creates the directory when it is missing. It should match the project or task root in the image.
default\_workspace\_root/workspace/Fallback workspace root exposed to the Harness when the Benchmark does not specify a task working directory. It does not change the container working directory set by workspace.
env\{}Environment variables supplied as a mapping and injected into the task container as key=value; string values are recommended. Do not put long-lived secrets in a public configuration file.
mounts\[]Docker mount list. Each item can be a source:target\[:mode] string or an object with source, target, and optional mode. The source is a host path or Docker volume, the target is an absolute container path, and the mode can be ro or rw.
### Resources | Field | Default | Meaning | | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cpus` | Unset | Positive CPU-core limit for one task container; fractional values such as `1.5` are accepted. When unset, AgentCompass passes no CPU limit to Docker. | | `memory` | Unset | Container memory limit. It accepts only a positive integer with an optional case-insensitive `b`, `k`, `m`, or `g` suffix, such as `8g` or `8192m`. A value without a suffix is measured in bytes; `k`, `m`, and `g` use powers of 1024. | | `memory_swap` | Unset | Combined memory and swap limit; requires `memory`. It uses the same integer-and-optional-suffix format as `memory` and also accepts `-1`. Set it equal to `memory` to disable additional swap, or to `-1` for unlimited swap. | | `gpus` | Unset | Value passed to Docker `--gpus`, such as `all`. The host must have a working GPU container runtime. | | `storage_opt` | `{}` | Per-container storage options such as `{"size":"20g"}`. Keys must be non-empty and cannot contain `=`; values must be non-empty. Docker supports `size` only with selected storage drivers; `overlay2` additionally requires an XFS backing filesystem with `pquota`. | ### Network
FieldDefaultMeaning
networkUnset; Docker bridge for external accessDocker network used by a public task container and by the network-policy proxy for external access. Phase transitions require a bridge-style network.
allowlist\_proxy\_imagepython:3.12-alpineContainer image used by the network-policy proxy for allowlist or a policy transition between phases. The image must provide an executable python. Override it only for an internal registry or a pinned image source.
See [Network Policy](/en/user_guide/modules/environments/configuration/network) and [Resource Limits](/en/user_guide/modules/environments/configuration/resource_limits) for shared controls. ### Lifecycle and Timeouts | Field | Default | Meaning | | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `allowlist_proxy_start_timeout` | `60` | Positive number of seconds to wait for the network-policy proxy container to become ready when using `allowlist` or switching policies between phases. Increase it if image pull or Docker daemon startup is slow. | The Docker provider has no separate task-container lifecycle or command-timeout parameters. It removes the container when the Environment closes normally; use `--keep-environment` to retain it, and use [Run Controls](/en/user_guide/using_agentcompass/run_controls) for the overall evaluation timeout. ## Parameter Sources * Run `agentcompass config docs env docker` to see the fields, types, and defaults supported by your installed AgentCompass version. * See Docker's [`docker container run` reference](https://docs.docker.com/reference/cli/docker/container/run/) for native parameter behavior and [Resource constraints](https://docs.docker.com/engine/containers/resource_constraints/) for CPU, memory, swap, and GPU controls. Use the `agentcompass config docs env docker` output for accepted fields, types, and defaults. Use the documentation for the connected Docker daemon version for native image, mount, and resource semantics. ## Provider-Specific Behavior * The task fails before container creation if `image` is still empty after recipes and explicit configuration are merged. * A fixed `name` is reused for every task container created through this provider. Concurrent creation, `--keep-environment`, or a previous cleanup failure can leave the name occupied, so generated names are usually safer. * Normal environment close force-removes the task container. With `--keep-environment`, AgentCompass skips that close operation. * `command` must keep the container alive so that the harness can run later commands. ## Troubleshooting | Symptom | What to check | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `Cannot connect to the Docker daemon` | Make sure the daemon is running and AgentCompass connects to the same daemon as the `docker` command. | | Permission denied for `/var/run/docker.sock` | Follow Docker's Linux post-install instructions, or enable `use_sudo_docker` only when appropriate. | | `no basic auth credentials` | Run `docker login` for the registry that hosts the image. | | `no matching manifest` | Check the image architecture and set `platform` if needed. | | The container exits immediately | Make sure the image contains the program used by `command` and that the command is long-running. | | Container creation reports that the name exists | Remove the old container if it is no longer needed, or remove the fixed `name`. | ## Related Pages * [Environments Overview](/en/user_guide/modules/environments/overview) * [Configure an Environment](/en/user_guide/modules/environments/configuration/overview) * [Run Controls](/en/user_guide/using_agentcompass/run_controls) * [CLI Configuration Files](/en/user_guide/using_agentcompass/cli/config)