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

Modal provider 会为每次任务执行创建一个云端 sandbox，适合使用 Linux 任务镜像、需要弹性算力或不希望占用本地资源的评测。

匹配的 [Recipe](/zh/user_guide/other_features/recipes) 可以补充镜像和工作区等默认值；兼容的显式参数通常会保留。Modal 需要有效账号和能够创建 sandbox 的令牌。

## 使用前准备

本地开发可以按照 [Modal 用户账号设置](https://modal.com/docs/guide/modal-user-account-setup) 运行 `modal setup`。CI 或共享 runner 建议创建 [Modal service user](https://modal.com/docs/guide/service-users)，并设置 `MODAL_TOKEN_ID` 和 `MODAL_TOKEN_SECRET`。

也可以在私有配置文件中填写 `token_id` 和 `token_secret`，但必须同时提供。不要将令牌提交到仓库。

<a id="运行一个任务" />

## 使用 `run` 验证配置

下面以 SWE-bench Verified 和 mini-swe-agent 为例。示例通过 [`sample_ids`](/zh/user_guide/modules/benchmarks/overview#共享-benchmark-字段) 只运行一个任务；匹配的 Recipe 会根据该任务选择 Modal 可用的镜像和工作区：

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

上面是 `agentcompass run` 的最小验证示例。模型端点等通用参数见 [`agentcompass run`](/zh/user_guide/using_agentcompass/cli/run)。

Modal 同样支持 `agentcompass launch`。在编排文件的 `defaults.environment` 中设置所有请求共享的 Modal 配置，或在 `requests[].environment` 中设置单个请求；`id: modal` 与 Modal 参数写在同一层。详见 [`launch` 的映射规则](/zh/user_guide/using_agentcompass/cli/launch#映射规则)。

<a id="provider-参数" />

## 参数参考

参数可以通过 `--env-params` 传入，也可以写在配置文件的 `environments.modal` 中。

上面的示例继续使用环境变量或 Modal SDK 配置中的凭证，并由 Recipe 补充任务镜像。将以下选项添加到该命令，可以为每个 sandbox 申请 2 核 CPU 和 6 GiB 内存：

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

### 连接与凭证

| 字段             | 默认值                  | 说明                                                                      |
| -------------- | -------------------- | ----------------------------------------------------------------------- |
| `token_id`     | `MODAL_TOKEN_ID`     | Modal token ID，必须与 `token_secret` 同时提供。未显式设置时，Modal SDK 也可以读取本地配置。      |
| `token_secret` | `MODAL_TOKEN_SECRET` | Modal token secret，必须与 `token_id` 同时提供。未显式设置这两个字段时，Modal SDK 会尝试读取本地配置。 |

### 镜像与启动

| 字段            | 默认值 | 说明                                                                                                                                                 |
| ------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image`       | 未设置 | 无需凭证即可拉取的镜像引用，例如 `python:3.13-slim`。与 `named_image` 互斥。当前适配器不提供 Modal Secret 参数，不能在这里配置私有镜像仓库凭证；这类镜像需要先发布为 Modal named image，再通过 `named_image` 使用。 |
| `named_image` | 未设置 | 已发布的 Modal named image，格式为 `{name}:{tag}`；省略 tag 时使用 `latest`。与 `image` 互斥。                                                                        |
| `add_python`  | 未设置 | 为 `image` 指定的仓库镜像注入 Python 版本，例如 `3.11`。该字段不作用于 `named_image`；镜像已经包含兼容的 Python 时无需设置。                                                              |

如果 Recipe、`image` 和 `named_image` 都没有提供镜像，Modal provider 会使用 `python:3.13-slim`。这个回退镜像只包含基础运行环境，不一定满足 Benchmark 的依赖和目录约定。

### 标识与元数据

| 字段                 | 默认值                      | 说明                                                                                                                       |
| ------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `app_name`         | `agentcompass-sandboxes` | 用于归集任务 sandbox 的 Modal App；不存在时会自动创建。                                                                                    |
| `environment_name` | 未设置                      | 指定查找或创建 App、查找 named image 以及创建 sandbox 所在的 Modal Environment；未设置时使用 Modal SDK 当前配置的 Environment，新 workspace 默认为 `main`。 |
| `name`             | 未设置                      | 可选的 sandbox 名称；设置后必须在同一个 App 内唯一，只能包含字母、数字、连字符、句点和下划线，且必须少于 64 个字符。不设置时 sandbox 仍有 Modal 生成的对象 ID，但没有此名称。                |
| `tags`             | `{}`                     | 写入 sandbox 的字符串键值标签，可用于标记所有者或评测批次。                                                                                       |

### 工作区与环境变量

| 字段                       | 默认值           | 说明                                                                                                  |
| ------------------------ | ------------- | --------------------------------------------------------------------------------------------------- |
| `workdir`                | 镜像默认值         | sandbox 内的命令工作目录，必须是绝对路径。                                                                           |
| `default_workspace_root` | `/workspace/` | Benchmark 未指定任务工作目录时，Harness 使用的默认 workspace；必须是非空的绝对路径，AgentCompass 会在 sandbox 启动后创建该目录。           |
| `env_variables`          | `{}`          | 创建 sandbox 并执行命令时注入的环境变量映射，例如 `{"LANG":"C.UTF-8"}`。键必须符合环境变量名称格式 `[A-Za-z_][A-Za-z0-9_]*`，值会转换为字符串。 |

### 资源

| 字段                 | 默认值                   | 说明                                                                                                                    |
| ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `cpu`              | `0.125`（Modal 平台默认）   | 正数表示请求的物理 CPU 核数；也可以用 `[request, limit]` 分别设置保证量和硬上限，二者都必须为正数，且 `limit` 不能小于 `request`。未显式设置时，由 Modal 使用当前平台默认值。      |
| `memory`           | `128 MiB`（Modal 平台默认） | 正数按 MiB 解释，也接受 `6g` 等大小字符串；`[request, limit]` 分别设置保证量和硬上限，二者都必须为正数，且 `limit` 不能小于 `request`。未显式设置时，由 Modal 使用当前平台默认值。 |
| `gpu`              | 未设置                   | Modal GPU 规格字符串，例如 `H100` 或表示两张卡的 `H100:2`。可用型号和数量取决于 Modal 当前容量。                                                     |
| `cloud`            | 未设置（不限制）              | 将 sandbox 限定到一个 Modal 支持的云厂商，例如 `aws`、`gcp`、`oci` 或 `auto`；可用性取决于 workspace 权限、区域和当前容量。                               |
| `region`           | 未设置（不限制）              | 单个区域名称或区域列表，例如 `us`、`us-west` 或 `["us-central","us-west"]`；范围越窄，可用容量通常越少。                                             |
| `resources`        | `{}`                  | 可选的嵌套资源对象。只在对应的顶层字段未设置时，才会读取下面的子字段。                                                                                   |
| `resources.cpu`    | 未设置                   | 与顶层 `cpu` 使用相同格式；别名为 `resources.cpus`。                                                                                |
| `resources.memory` | 未设置                   | 与顶层 `memory` 使用相同格式；还接受 `resources.memory_mb` 和以 GiB 表示的 `resources.memory_gb`。`memory_gb` 只接受单个数值。                   |
| `resources.gpu`    | 未设置                   | 与顶层 `gpu` 使用相同格式；别名为 `resources.gpus`。                                                                                |

建议在顶层字段与 `resources` 子字段中选择一种写法，不要重复设置同一资源。需要同时表达 request 和 limit 时，`cpu` 的两种位置都可使用二元素列表；内存请使用顶层 `memory`、`resources.memory` 或 `resources.memory_mb`，不要使用 `resources.memory_gb`。

### 网络

| 字段                          | 默认值     | 说明                                                                                         |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------ |
| `block_network`             | `false` | 是否阻断 sandbox 的全部出站网络。设为 `true` 时，不能同时设置下面三种允许列表。                                           |
| `outbound_cidr_allowlist`   | `[]`    | 允许 sandbox 访问的出站 CIDR 列表，例如 `["203.0.113.0/24"]`。设置后，列表外的地址会被阻断，但仍可与域名允许列表组合使用。            |
| `outbound_domain_allowlist` | `[]`    | 允许 sandbox 通过 TLS（端口 443）访问的域名列表，例如 `["api.example.com","*.example.org"]`。通配形式同时匹配根域名和子域名。 |
| `inbound_cidr_allowlist`    | `[]`    | 允许通过 Modal tunnel 或 connect token 连接 sandbox 的来源 CIDR 列表，例如 `["198.51.100.0/24"]`。         |

三个阶段使用同一策略时，直接设置[通用网络策略](/zh/user_guide/modules/environments/configuration/network)即可。需要在阶段间切换时，请保持基础 `network_policy` 为 `public`、保持 `block_network=false`，并在创建 sandbox 时同时设置 `outbound_domain_allowlist: ["*"]` 和 `outbound_cidr_allowlist: ["0.0.0.0/0"]`，再配置后续阶段策略。当前适配器每次动态更新都会同时发送这两类允许列表，但不会根据后续阶段自动补上初始值；缺少任一预置时，Modal 都可能拒绝更新。具体限制见 [Modal sandbox 网络](https://modal.com/docs/guide/sandbox-networking)。

### 生命周期与超时

| 字段                      | 默认值     | 说明                                                                                                  |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `timeout`               | `43200` | 单个 Modal sandbox 的最长生命周期（秒），必须是 `1` 到 `86400` 之间的整数。复用该 sandbox 进行验证时，验证也计入这段时间；独立验证 sandbox 会分别计时。 |
| `idle_timeout`          | 未设置     | sandbox 没有正在运行的命令、stdin 写入或活动 tunnel 连接后，Modal 等待多少秒再自动终止；必须是非负整数。                                  |
| `sandbox_start_timeout` | `300`   | AgentCompass 等待 sandbox 创建完成的秒数，必须为正数。                                                              |
| `operation_timeout`     | `1800`  | Harness 或调用方没有为某次执行单独指定超时时，单次 sandbox 命令使用的默认超时（秒），必须为正整数。                                          |

并发与保留环境的行为见[运行控制](/zh/user_guide/using_agentcompass/run_controls)，资源配置建议见[资源限制](/zh/user_guide/modules/environments/configuration/resource_limits)。

## 参数参考来源

* 运行 `agentcompass config docs env modal`，可以查看当前安装版本实际支持的字段、类型和默认值。
* Modal 原生参数见 [Sandbox API](https://modal.com/docs/sdk/py/latest/Sandbox)、[CPU 与内存](https://modal.com/docs/guide/resources)、[GPU](https://modal.com/docs/guide/gpu)、[区域选择](https://modal.com/docs/guide/region-selection)、[sandbox 网络](https://modal.com/docs/guide/sandbox-networking)、[仓库镜像](https://modal.com/docs/guide/existing-images)、[named image](https://modal.com/docs/guide/named-images) 和 [Environment](https://modal.com/docs/guide/environments)。

支持的字段、类型和默认值以 `agentcompass config docs env modal` 的输出为准；Modal 原生字段的取值和平台行为，以上游文档为准。

## 特有行为

* `image` 和 `named_image` 只能设置一个；前者从镜像仓库加载，后者从指定 Modal Environment 查找。
* 正常关闭 Environment 时，AgentCompass 会终止 sandbox 并断开客户端连接。使用 `--keep-environment` 时会跳过关闭。
* 阶段网络切换不仅要求当前 Modal SDK 支持动态更新，还要求两种出站允许列表在创建 sandbox 时按上文预置；以 `block_network=true` 创建的 sandbox 不能动态切换策略。

## 故障排查

| 现象              | 检查内容                                                  |
| --------------- | ----------------------------------------------------- |
| 提示 token 只提供了一项 | 同时设置 `token_id` 与 `token_secret`，或同时移除并使用 Modal 本地配置。 |
| 找不到 named image | 检查 `named_image`、`environment_name` 以及令牌所属 workspace。 |
| 回退镜像中缺少命令或文件    | 使用兼容 Recipe，或显式设置包含任务依赖的 `image` / `named_image`。     |
| `workdir` 配置无效  | 使用 sandbox 内的绝对路径。                                    |
| sandbox 创建超时    | 先检查镜像和账号配额，再按实际创建时间增加 `sandbox_start_timeout`。        |

## 相关页面

* [Environment 概览](/zh/user_guide/modules/environments/overview)
* [配置 Environment](/zh/user_guide/modules/environments/configuration/overview)
* [网络策略](/zh/user_guide/modules/environments/configuration/network)
* [CLI 配置文件](/zh/user_guide/using_agentcompass/cli/config)