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

# 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](/en/user_guide/other_features/recipes) supply the rest.

<Note>
  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.
</Note>

## 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`](/en/user_guide/using_agentcompass/cli/run)                                               | Select the provider with `--env <provider-id>` and pass parameters with `--env-params '<json>'`.                                      | Temporary settings for the current evaluation.          |
| [Configuration file](/en/user_guide/using_agentcompass/cli/config#configuration-file-structure)               | 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](/en/user_guide/using_agentcompass/python_api#single-evaluation-request)       | In `run_evaluation()`, select the provider with `environment="<provider-id>"` and pass parameters through `environment_params={...}`. | Single-evaluation requests started from Python.         |
| [`agentcompass launch`](/en/user_guide/using_agentcompass/cli/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](/en/user_guide/using_agentcompass/python_api#multiple-evaluation-requests) | 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:

```bash theme={"system"}
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:

```yaml theme={"system"}
environments:
  docker:
    image: python:3.13-slim
    cpus: 2
    memory: 6g
```

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

```bash theme={"system"}
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:

```python theme={"system"}
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`:

```yaml theme={"system"}
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](/en/user_guide/using_agentcompass/cli/launch#mapping-rules) and [Python SDK multiple-evaluation requests](/en/user_guide/using_agentcompass/python_api#multiple-evaluation-requests).

<Warning>
  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.
</Warning>

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

```bash theme={"system"}
--env daytona \
  --env-params '{"resources":{"cpu":2,"memory":6}}'
```

A configuration file preserves the nested YAML structure:

```yaml theme={"system"}
environments:
  daytona:
    resources:
      cpu: 2
      memory: 6
```

The Python SDK accepts a nested dictionary:

```python theme={"system"}
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:

```yaml theme={"system"}
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](/en/user_guide/modules/environments/overview#choose-a-provider) 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](/en/user_guide/modules/environments/configuration/network). |
| 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:

```bash theme={"system"}
agentcompass config docs env docker
```

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

```bash theme={"system"}
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`](/en/user_guide/using_agentcompass/cli/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](/en/user_guide/other_features/recipes) | 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:

```bash theme={"system"}
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`.

<Note>
  The overall evaluation timeout, concurrency, and Environment startup rate are [run controls](/en/user_guide/using_agentcompass/run_controls). Fields such as [Modal's `timeout`](/en/user_guide/modules/environments/providers/modal) and [OpenSandbox's `lifecycle_seconds`](/en/user_guide/modules/environments/providers/opensandbox) limit the lifetime of one sandbox and are not evaluation timeouts.
</Note>

## Related Pages

* [Network Policies](/en/user_guide/modules/environments/configuration/network)
* [Resource Limits](/en/user_guide/modules/environments/configuration/resource_limits)
* [Environment Provider List](/en/user_guide/modules/environments/overview#choose-a-provider)