Configure an Environment

Selecting a provider and passing Environment parameters are separate operations: the provider chooses the Environment implementation that executes the task, while its parameters control how that Environment is created and run. Set only the fields you need to change, and let provider defaults or an applicable Recipe supply the rest. Environment parameters must belong to the public schema shown by agentcompass config docs env <provider-id>. Unknown fields, including misspellings and all provider-specific options, raise an unknown-parameter error. Configure outbound access through the shared network policies; adapters generate the corresponding native API options internally. All providers share one schema. The provider ID selects an implementation and its supported capabilities; it does not add public parameters. setup includes image, workdir, build_timeout_seconds, and os. evaluation_setup uses the same structure for a fresh verifier. Resource, network, and environment-variable fields are also shared. Host credentials are configured through the adapter’s existing environment variables or SDK configuration, outside task execution settings.

AgentCompass matches recipes automatically. A normal evaluation does not require setting or modifying a recipe; configure one manually only when a benchmark page names an alternative, troubleshooting requires restricted matching, or your team loads custom adaptation logic.

Choose a Provider and Input Method

All of the following methods can provide Environment parameters. Choose one based on whether the values apply only to the current evaluation or should be reused by other runs or programs:

Method	How to configure it	Use it for
`agentcompass run`	Select the provider with `--env <provider-id>` and pass parameters with `--env-params '<json>'`.	Temporary settings for the current evaluation.
Configuration file	Store a provider’s defaults under `environments.<provider-id>`. The provider is still selected by `run`, `launch`, or the SDK.	Defaults reused across evaluations.
Python SDK: single evaluation	In `run_evaluation()`, select the provider with `environment="<provider-id>"` and pass parameters through `environment_params={...}`.	Single-evaluation requests started from Python.
`agentcompass launch`	In an orchestration file’s `environment` mapping, use `id` to select the provider and place its parameters beside `id`.	One or more requests orchestrated through YAML or JSON.
Python SDK: multiple evaluations	Use the same orchestration structure in `OrchestrationSpec.defaults.environment` or `requests[].environment`.	Multiple-evaluation requests started from Python.

`agentcompass run`

Use --env <id> to select a provider. When it is omitted, AgentCompass uses host_process. Run agentcompass list env to see the provider IDs available in the current installation. --env-params accepts a JSON object for the Environment parameters of this evaluation. Matching fields override configuration-file values:

agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env docker \
  --env-params '{"setup":{"image":"python:3.13-slim"},"resources":{"cpu":2,"memory_mb":6144}}'

Configuration File

Write reusable provider parameters directly under environments.<id>. Do not add a params wrapper:

environments:
  docker:
    setup:
      image: python:3.13-slim
    resources:
      cpu: 2
      memory_mb: 6144

Select the same provider and load the file when running the evaluation:

agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env docker \
  --config config.yaml

Python SDK Single Evaluation

The SDK accepts a Python dictionary, so the parameters do not need to be encoded as a JSON string:

from agentcompass import run_evaluation

result = run_evaluation(
    benchmark="swebench_verified",
    harness="mini_swe_agent",
    model="your-model",
    environment="docker",
    environment_params={
        "resources": {
            "cpu": 2,
            "memory_mb": 6144,
        },
    },
)

`agentcompass launch` and SDK Multiple Evaluations

In a launch orchestration, id selects the provider and the remaining fields are written directly under environment:

defaults:
  environment:
    id: docker
    resources:
      cpu: 2
      memory_mb: 6144

Each evaluation request can override these defaults in its own environment section. The Python SDK’s OrchestrationSpec uses the same field structure. See the agentcompass launch mapping rules and Python SDK multiple-evaluation requests.

When an orchestration mixes providers, do not place provider-specific parameters in defaults.environment. A request that overrides environment.id still inherits and merges the other fields in defaults.environment. Put provider-specific values in each requests[].environment instead.

Write Nested Fields

Provider parameters can be strings, numbers, booleans, objects, or lists. In a parameter reference, resources.cpu means the cpu field inside the resources object; it is not a flat key named resources.cpu. The following four forms are equivalent. Each requests 2 vCPUs and 6 GiB of memory from Daytona. The CLI accepts a JSON object:

--env daytona \
  --env-params '{"resources":{"cpu":2,"memory_mb":6144}}'

A configuration file preserves the nested YAML structure:

environments:
  daytona:
    resources:
      cpu: 2
      memory_mb: 6144

The Python SDK accepts a nested dictionary:

from agentcompass import run_evaluation

result = run_evaluation(
    benchmark="<benchmark>",
    harness="<harness>",
    model="<model>",
    environment="daytona",
    environment_params={"resources": {"cpu": 2, "memory_mb": 6144}},
)

A launch orchestration places provider parameters beside id while retaining their nested shape:

defaults:
  environment:
    id: daytona
    resources:
      cpu: 2
      memory_mb: 6144

Objects merge recursively by field, while a later scalar or list replaces the earlier value in full. For example, if a configuration file sets resources.cpu: 2 and resources.memory_mb: 6144, then a request that passes only {"resources":{"memory_mb":8192}} resolves to 2 vCPUs and 8192 MiB of memory. Do not add a params wrapper, and do not write a field path as {"resources.cpu":2}. See the selected provider’s parameter reference for its nested fields, units, and accepted values.

Understand Field Ownership

Environment parameters contain two kinds of fields:

Field kind	Fields or examples	Meaning
Shared setup fields	`setup.image`, `setup.workdir`, `setup.build_timeout_seconds`, `setup.os`	Describe provider-neutral startup requirements. The provider maps supported fields to its adapter without treating workdir as the Benchmark workspace.
Shared network fields	`network_policy`, `run_network_policy`, `verifier_network_policy`	Set the baseline, agent-run, and verification policies. The latter two inherit the baseline when omitted. The provider must support the selected modes; see Network Policies.
Provider fields	Credentials, resources, placement, and lifecycle settings	Defined by the selected provider. Names, units, and defaults cannot be copied directly between providers.

With every input method, shared setup and network fields and provider fields are written at the same level, without another params wrapper. In a configuration file, for example, all are written directly under environments.docker.

Inspect Fields and Resolved Configuration

Show the provider-specific fields, types, and defaults declared by one provider in the current installation:

agentcompass config docs env docker

Show the result of merging built-in defaults with a configuration file:

agentcompass config show \
  --env docker \
  --config config.yaml

config show includes only built-in values and configuration-file layers. It does not include extra CLI, SDK, or orchestration fields for a particular run, or the final Environment settings that a Recipe adds before a task starts. See agentcompass config for the complete command behavior.

How Environment Parameters Take Effect

Environment parameters are not read once from a single source. They are built in these stages:

Stage	Effect
Provider defaults and configuration files	Form the reusable base configuration. Configuration-file values override matching built-in defaults. `config show` displays the result through this stage.
Explicit parameters for this request	Fields passed explicitly through the `run` CLI, Python SDK, or an orchestration request override matching configuration-file values.
Recipe	After the concrete task is known, a matching Recipe can add or adjust the image, Environment workdir, Benchmark workspace, resources, network, and required execution settings for the Benchmark, Harness, and provider combination. These task-specific changes do not appear in `config show`.

The following command does not set a Docker image. The matching SWE-bench Verified Recipe derives the image and task workspace from the sample, so selecting the provider is usually enough:

agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env docker

Without a matching Recipe, you must still provide the provider’s required fields, such as the task image for Docker. A Recipe is also not a universal “explicit parameters always win” rule: built-in Recipes usually preserve compatible explicit image and resource settings, but they may still adjust workspace, network, or execution settings required by the Benchmark or Harness. Pass Environment parameters only when you intend to change the default behavior. Valid values still depend on the provider and are documented on its provider page and by config docs.

The overall evaluation timeout, concurrency, and Environment startup rate are run controls. Fields such as Modal’s timeout and OpenSandbox’s lifecycle_seconds limit the lifetime of one sandbox and are not evaluation timeouts.

Native adapters may require particular variable values to launch their runner or translate canonical model/execution settings. If a declared environment variable conflicts with one of these requirements, the command fails before launch and reports only the variable name. Change the corresponding Model, Harness, or execution setting instead of overriding its generated variable. Matching values are accepted. This adds no new CLI field. Internal Python runners preserve your PYTHONPATH where they can bootstrap their imports; the mini-SWE-agent CLI still requires its generated module directory and rejects a conflicting PYTHONPATH.

Using AgentCompass

Modules

Other Features

Choose a Provider and Input Method

`agentcompass run`

Configuration File

Python SDK Single Evaluation

`agentcompass launch` and SDK Multiple Evaluations

Write Nested Fields

Understand Field Ownership

Inspect Fields and Resolved Configuration

How Environment Parameters Take Effect

​Choose a Provider and Input Method

​agentcompass run

​Configuration File

​Python SDK Single Evaluation

​agentcompass launch and SDK Multiple Evaluations

​Write Nested Fields

​Understand Field Ownership

​Inspect Fields and Resolved Configuration

​How Environment Parameters Take Effect

​Related Pages

Choose a Provider and Input Method

`agentcompass run`

Configuration File

Python SDK Single Evaluation

`agentcompass launch` and SDK Multiple Evaluations

Write Nested Fields

Understand Field Ownership

Inspect Fields and Resolved Configuration

How Environment Parameters Take Effect

Related Pages