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

# Environment Resource Limits

Environment resource parameters limit what a local instance can use or specify the CPU, memory, storage, and GPU requested for a remote instance.

Use them to keep one task from consuming excessive resources or to request a remote instance that matches Benchmark requirements. They do not limit the AgentCompass host process, model service, or other external services.

<Warning>
  `host_process` runs commands directly on the host and cannot enforce Environment-level CPU, memory, storage, or GPU limits. Choose another provider when you need resource isolation.
</Warning>

<a id="understand-the-scope" />

## Separate Resources from Scheduling

These four settings solve different problems:

| Setting                               | What it controls                                                                                                                      |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Environment resource parameters       | Resources available to or requested for one Environment instance. Set them as Environment parameters; on the CLI, use `--env-params`. |
| `--task-concurrency`                  | The maximum number of Benchmark tasks processed at the same time in one evaluation.                                                   |
| `--provider-limit <provider>=<count>` | The maximum concurrent task attempts handled by one provider in the current AgentCompass process.                                     |
| `--env-open-qps <provider>=<qps>`     | How many Environment creations can begin per second for one provider. It limits creation rate, not the number of running instances.   |

For example, Docker `cpus: 2` limits each container to two cores, while `--task-concurrency 8` permits up to eight tasks to be processed concurrently. Neither setting replaces the other.

Task and verifier Environments are also separate resource allocations. When a Benchmark requires a fresh verifier Environment, AgentCompass normally closes the task Environment before creating it. They overlap only when `--keep-environment` retains the task Environment.

See [Run Controls](/en/user_guide/using_agentcompass/run_controls) for the full behavior of concurrency, open rate, and `--keep-environment`.

## Provider Capabilities and Units

Provider APIs use different resource models and units, so these fields cannot use one common format.

| Provider                                                                     | CPU                                 | Memory                                                    | Storage                                                               | GPU                                         |
| ---------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------- |
| [`host_process`](/en/user_guide/modules/environments/providers/host_process) | No enforced limit                   | No enforced limit                                         | No enforced limit                                                     | No enforced limit                           |
| [`docker`](/en/user_guide/modules/environments/providers/docker)             | `cpus`: core count                  | `memory`, `memory_swap`: Docker size strings such as `6g` | `storage_opt`: format and support depend on the Docker storage driver | `gpus`: a value accepted by Docker `--gpus` |
| [`daytona`](/en/user_guide/modules/environments/providers/daytona)           | `resources.cpu`: integer cores      | `resources.memory`: GiB                                   | `resources.disk`: GiB                                                 | `resources.gpu`: GPU count                  |
| [`modal`](/en/user_guide/modules/environments/providers/modal)               | `cpu`: number or request/limit pair | `memory`: MiB, size string, or request/limit pair         | Determined by Modal and image storage configuration                   | `gpu`: a Modal GPU request string           |

Use the following command to inspect the exact fields and defaults accepted by the installed revision:

```bash theme={"system"}
agentcompass config docs env <provider>
```

Each provider page explains its field formats, account quotas, and operating requirements in more detail.

## Configure Resources

The following examples use the same task to compare the Docker, Daytona, and Modal resource shapes. Each one selects a single task through [`sample_ids`](/en/user_guide/modules/benchmarks/overview#shared-benchmark-fields) and assigns 2 CPU cores and 6 GiB of memory to each Environment. These values demonstrate the syntax; they are not a recommended Benchmark configuration.

The examples use `agentcompass run`. See [Configure an Environment](/en/user_guide/modules/environments/configuration/overview) for configuration-file, Python SDK, and `launch` orchestration-file forms.

### Docker

```bash theme={"system"}
agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env docker \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --env-params '{"cpus":2,"memory":"6g","memory_swap":"6g"}'
```

Setting `memory_swap` equal to `memory` provides no additional swap allowance. See [Docker resource parameters](/en/user_guide/modules/environments/providers/docker#resources) for the field formats.

### Daytona

```bash theme={"system"}
agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env daytona \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --env-params '{"resources":{"cpu":2,"memory":6}}'
```

Daytona interprets `resources.memory` in GiB. The recipe for this combination selects the task image, so the request applies to an image-based sandbox. Daytona does not apply `resources` if you explicitly switch to a `snapshot`. See [Daytona resource parameters](/en/user_guide/modules/environments/providers/daytona#resources) for the field formats.

### Modal

```bash theme={"system"}
agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env modal \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --env-params '{"cpu":2,"memory":"6g"}'
```

Modal accepts top-level resource fields as well as a `resources` object; the example uses the more direct top-level form. See [Modal resource parameters](/en/user_guide/modules/environments/providers/modal#resources) for the field formats.

<Info>
  A Docker storage limit works only when the storage driver supports per-container size limits. A remote provider may also reject a request because of account quota, regional capacity, or an unavailable instance shape.
</Info>

## Recipe Resources and Explicit Overrides

Some recipes read task resource requirements from a Benchmark and translate them into the selected provider's fields and units. For example, the same memory requirement may be expressed in GiB for Daytona and converted to another accepted format for Modal.

Built-in recipes usually preserve compatible explicit resource values, but the exact adaptation still depends on the recipe and Benchmark. As a result:

* to reproduce the Benchmark resource conditions, start with the defaults supplied by its recipe; and
* to compare another resource profile, override it explicitly and record the change with the results.

Resource changes can affect task completion and scores. Do not combine runs made under different resource limits as though they used the same evaluation conditions.

## Estimate Aggregate Capacity

Estimate capacity in this order:

1. Start with the resource requirements supplied by the Benchmark or recipe.
2. Run one representative task and observe peak memory, CPU use, disk growth, and verifier needs.
3. Leave headroom for dependency installation, compilation, and caches.
4. Estimate aggregate use from per-instance resources and actual concurrency, then adjust task and provider limits.
5. Increase concurrency gradually, reducing it when OOM failures, creation errors, or sustained queueing appear.

Capacity planning should focus on how many Environment instances can exist at the same time. `--env-open-qps` changes only how quickly new instances begin creation; it does not limit the number of running instances.

## Troubleshoot Resource Problems

| Symptom                                                                | Common cause                                                                                 | What to do                                                                                      |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Docker reports exit code `137`, `OOMKilled`, or an abrupt process exit | The container exceeded its memory limit.                                                     | Inspect container state and peak memory, then compare the limit with the Benchmark requirement. |
| The host becomes unresponsive with several tasks running               | Aggregate Environment demand exceeds host capacity.                                          | Lower `--task-concurrency` or the relevant `--provider-limit`.                                  |
| Daytona or Modal rejects instance creation                             | The field format, requested shape, regional capacity, or account quota is invalid.           | Check the provider page and account console, then validate the configuration with one instance. |
| CPU use is low but the task still times out                            | Time is spent waiting for the model, network, or Harness rather than for CPU.                | Inspect phase logs before increasing CPU.                                                       |
| The Docker writable layer fills                                        | Task output exceeds its capacity, or the storage driver cannot enforce the configured limit. | Check the storage driver and use a supported storage option or a more suitable image layout.    |
| A GPU is not visible inside the Environment                            | The host runtime, image, driver, or provider GPU request is incompatible.                    | Validate the provider's GPU configuration independently before running the evaluation.          |

For other failures, see [Troubleshooting Runs](/en/user_guide/other_features/troubleshooting).

## Related Pages

* [Choose an Environment](/en/user_guide/modules/environments/overview)
* [Network Policy](/en/user_guide/modules/environments/configuration/network)
* [Run Controls](/en/user_guide/using_agentcompass/run_controls)