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.

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 '{"image":"python:3.13-slim","cpus":2,"memory":"6g"}'

Configuration File

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

environments:
  docker:
    image: python:3.13-slim
    cpus: 2
    memory: 6g

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={
        "cpus": 2,
        "memory": "6g",
    },
)

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
    cpus: 2
    memory: 6g

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":6}}'

A configuration file preserves the nested YAML structure:

environments:
  daytona:
    resources:
      cpu: 2
      memory: 6

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": 6}},
)

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

defaults:
  environment:
    id: daytona
    resources:
      cpu: 2
      memory: 6

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: 6, then a request that passes only {"resources":{"memory":8}} resolves to 2 vCPUs and 8 GiB 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 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	Image, workspace, credentials, resources, and lifecycle	Defined by the selected provider. Names, units, and defaults cannot be copied directly between providers.

With every input method, shared network fields and provider fields are written at the same level, without another params wrapper. In a configuration file, for example, both 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, 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.

Related Pages

• Network Policies
• Resource Limits
• Environment Provider List