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

# Modal

The Modal provider creates one cloud sandbox for each task execution. Use it for Linux task images when you need elastic compute or do not want to consume local resources.

A matched [recipe](/en/user_guide/other_features/recipes) can supply defaults such as the image and workspace; compatible explicit settings are usually preserved. Modal requires a valid account and a token that can create sandboxes.

## Before You Start

For local development, follow [Modal user account setup](https://modal.com/docs/guide/modal-user-account-setup) and run `modal setup`. For CI or shared runners, create a [Modal service user](https://modal.com/docs/guide/service-users) and set `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET`.

You can instead place `token_id` and `token_secret` in a private configuration file, but both must be present. Do not commit tokens.

<a id="run-one-task" />

## 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 selects its Modal-compatible image and workspace:

```bash theme={"system"}
agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env modal \
  --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.

Modal also supports `agentcompass launch`. Put shared Modal settings under `defaults.environment` in the orchestration file, or request-specific settings under `requests[].environment`; write `id: modal` and the Modal parameters at the same level. See the [`launch` mapping rules](/en/user_guide/using_agentcompass/cli/launch#mapping-rules).

<a id="provider-params" />

## Parameter Reference

Pass parameters with `--env-params`, or place them under `environments.modal` in a configuration file.

The example above continues to use credentials from environment variables or the Modal SDK configuration, while the recipe supplies the task image. Add the following option to request 2 CPU cores and 6 GiB of memory for each sandbox:

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

### Connection and Credentials

| Field          | Default              | Meaning                                                                                                                                |
| -------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `token_id`     | `MODAL_TOKEN_ID`     | Modal token ID; it must be provided with `token_secret`. If neither is explicit, the Modal SDK can also read its local configuration.  |
| `token_secret` | `MODAL_TOKEN_SECRET` | Modal token secret; it must be provided with `token_id`. If neither field is explicit, the Modal SDK can read its local configuration. |

### Image and Startup

| Field         | Default | Meaning                                                                                                                                                                                                                                                                                                        |
| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image`       | Unset   | Registry image reference that can be pulled without credentials, such as `python:3.13-slim`. Mutually exclusive with `named_image`. The current adapter does not expose a Modal Secret parameter for private-registry credentials; publish such an image as a Modal named image and use `named_image` instead. |
| `named_image` | Unset   | Published Modal image in `{name}:{tag}` form; omitting the tag selects `latest`. Mutually exclusive with `image`.                                                                                                                                                                                              |
| `add_python`  | Unset   | Python version string, such as `3.11`, passed when loading a registry `image`. It applies only to `image`, not `named_image`; omit it when the image already contains a compatible Python installation.                                                                                                        |

If no recipe, `image`, or `named_image` supplies an image, the Modal provider falls back to `python:3.13-slim`. This basic image may not contain the dependencies or directory layout required by a benchmark.

### Identity and Metadata

| Field              | Default                  | Meaning                                                                                                                                                                                                                                                |
| ------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `app_name`         | `agentcompass-sandboxes` | Modal App that groups task sandboxes. It is created when missing.                                                                                                                                                                                      |
| `environment_name` | Unset                    | Modal Environment in which AgentCompass looks up or creates the App, looks up the named image, and creates the sandbox. When unset, Modal uses the Environment selected by the SDK configuration or calling context; new workspaces default to `main`. |
| `name`             | Unset                    | Optional sandbox name. When set, it must be unique within the App, contain only letters, digits, hyphens, periods, and underscores, and be fewer than 64 characters long. An unnamed sandbox still has a Modal-generated object ID.                    |
| `tags`             | `{}`                     | String key-value tags for ownership or evaluation-batch metadata.                                                                                                                                                                                      |

### Workspace and Environment Variables

| Field                    | Default       | Meaning                                                                                                                                                                                                   |
| ------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workdir`                | Image default | Working directory for sandbox commands. It must be an absolute path.                                                                                                                                      |
| `default_workspace_root` | `/workspace/` | Non-empty absolute path used by the Harness when the Benchmark does not specify a task working directory. AgentCompass creates this directory after the sandbox starts.                                   |
| `env_variables`          | `{}`          | Environment-variable mapping injected when the sandbox is created and commands are executed, for example `{"LANG":"C.UTF-8"}`. Keys must match `[A-Za-z_][A-Za-z0-9_]*`; values are converted to strings. |

### Resources

| Field              | Default                            | Meaning                                                                                                                                                                                                                                                                                 |
| ------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cpu`              | `0.125` (Modal platform default)   | Positive request in physical CPU cores, or a two-item `[request, limit]` list of positive values. The second value is a hard limit and cannot be smaller than the request. When unset, Modal uses its current platform default.                                                         |
| `memory`           | `128 MiB` (Modal platform default) | Positive memory request in MiB, a size string such as `6g`, or a two-item `[request, limit]` list of positive values. The second value is a hard limit and cannot be smaller than the request; AgentCompass converts sizes to MiB. When unset, Modal uses its current platform default. |
| `gpu`              | Unset                              | Modal GPU specification, such as `H100` or `H100:2` for two GPUs. Available models and counts depend on current Modal capacity.                                                                                                                                                         |
| `cloud`            | Unset (unrestricted)               | Restricts the sandbox to one cloud provider supported by Modal, such as `aws`, `gcp`, `oci`, or `auto`. Availability depends on workspace access, region, and current capacity.                                                                                                         |
| `region`           | Unset (unrestricted)               | One region or a list, such as `us`, `us-west`, or `["us-central","us-west"]`. Narrower placement usually reduces the available capacity pool.                                                                                                                                           |
| `resources`        | `{}`                               | Optional nested resource object. A child field is read only when its matching top-level field is unset.                                                                                                                                                                                 |
| `resources.cpu`    | Unset                              | Uses the same format as top-level `cpu`. Alias: `resources.cpus`.                                                                                                                                                                                                                       |
| `resources.memory` | Unset                              | Uses the same format as top-level `memory`. It also accepts `resources.memory_mb` and `resources.memory_gb`, where the latter is interpreted as GiB and accepts only a single number.                                                                                                   |
| `resources.gpu`    | Unset                              | Uses the same format as top-level `gpu`. Alias: `resources.gpus`.                                                                                                                                                                                                                       |

Choose either top-level fields or `resources` child fields for a given resource rather than defining both. The two-item request-and-limit form for CPU works in either location. For memory, use top-level `memory`, `resources.memory`, or `resources.memory_mb`; do not use `resources.memory_gb` for a pair.

### Network

| Field                       | Default | Meaning                                                                                                                                                                                               |
| --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `block_network`             | `false` | Blocks all outbound traffic when set to `true`. In that case, it cannot be combined with any of the three allowlist fields below.                                                                     |
| `outbound_cidr_allowlist`   | `[]`    | CIDR ranges that the sandbox may reach using any protocol, for example `["203.0.113.0/24"]`. Other outbound IP ranges are blocked unless a domain rule also permits the traffic.                      |
| `outbound_domain_allowlist` | `[]`    | Domain names that the sandbox may reach over TLS on port 443, for example `["api.example.com","*.example.org"]`. A wildcard also matches the parent domain; CIDR and domain rules combine additively. |
| `inbound_cidr_allowlist`    | `[]`    | Source CIDR ranges allowed to connect through Modal tunnels and Sandbox Connect Tokens, for example `["198.51.100.0/24"]`.                                                                            |

When all three phases use the same policy, set a [shared network policy](/en/user_guide/modules/environments/configuration/network) directly. For phase transitions, keep the base `network_policy` set to `public`, keep `block_network=false`, and create the sandbox with both `outbound_domain_allowlist: ["*"]` and `outbound_cidr_allowlist: ["0.0.0.0/0"]` before configuring the later phase policies. The current adapter sends both allowlist types on every dynamic update but does not infer their initial values from later phases. Modal may reject an update if either type was absent at creation. See [Modal sandbox networking](https://modal.com/docs/guide/sandbox-networking) for the upstream restrictions.

### Lifecycle and Timeouts

| Field                   | Default | Meaning                                                                                                                                                                                                                     |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timeout`               | `43200` | Maximum lifetime of one Modal sandbox, in seconds. It must be an integer from `1` through `86400`. Verification counts toward the same lifetime when it reuses that sandbox; a separate verifier sandbox has its own timer. |
| `idle_timeout`          | Unset   | Non-negative number of seconds Modal waits before terminating a sandbox with no active command, stdin writes, or open tunnel connection.                                                                                    |
| `sandbox_start_timeout` | `300`   | Positive number of seconds AgentCompass waits for sandbox creation.                                                                                                                                                         |
| `operation_timeout`     | `1800`  | Positive default timeout, in seconds, for one sandbox command when the Harness or caller does not provide a timeout for that execution.                                                                                     |

See [Run Controls](/en/user_guide/using_agentcompass/run_controls) for concurrency and retained environments, and [Resource Limits](/en/user_guide/modules/environments/configuration/resource_limits) for sizing guidance.

## Parameter Sources

* Run `agentcompass config docs env modal` to see the fields, types, and defaults supported by your installed AgentCompass version.
* See Modal's [Sandbox API reference](https://modal.com/docs/sdk/py/latest/Sandbox) and the official guides for [resources](https://modal.com/docs/guide/resources), [GPUs](https://modal.com/docs/guide/gpu), [region selection](https://modal.com/docs/guide/region-selection), [sandbox networking](https://modal.com/docs/guide/sandbox-networking), [registry images](https://modal.com/docs/guide/existing-images), [named images](https://modal.com/docs/guide/named-images), and [Modal Environments](https://modal.com/docs/guide/environments).

Use the `agentcompass config docs env modal` output for accepted fields, types, and defaults. Use Modal's documentation for provider-native values and platform behavior.

## Provider-Specific Behavior

* Set only one of `image` and `named_image`: the first loads from a registry; the second is looked up in the selected Modal Environment.
* Normal environment close terminates and detaches the sandbox. With `--keep-environment`, AgentCompass skips close.
* Phase network transitions require both an SDK that supports dynamic updates and both outbound allowlist types to be initialized as described above. A sandbox created with `block_network=true` cannot switch policies dynamically.

## Troubleshooting

| Symptom                                    | What to check                                                                                                   |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| Only one token field is provided           | Set both `token_id` and `token_secret`, or remove both and use Modal's local configuration.                     |
| A named image cannot be found              | Check `named_image`, `environment_name`, and the workspace associated with the token.                           |
| The fallback image lacks commands or files | Use a compatible recipe, or set an `image` / `named_image` that contains the task dependencies.                 |
| `workdir` is rejected                      | Use an absolute path inside the sandbox.                                                                        |
| Sandbox creation times out                 | Check the image and account quota first, then increase `sandbox_start_timeout` based on observed creation time. |

## Related Pages

* [Environments Overview](/en/user_guide/modules/environments/overview)
* [Configure an Environment](/en/user_guide/modules/environments/configuration/overview)
* [Network Policy](/en/user_guide/modules/environments/configuration/network)
* [CLI Configuration Files](/en/user_guide/using_agentcompass/cli/config)