> ## 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 cloud sandbox 中运行 benchmark 任务。

Modal 是用于云端 sandbox 的 remote environment provider。它适合 SWE-bench 和 Terminal-Bench 这类任务元数据中已经包含兼容 registry image 的 workload。

## 官方设置入口

| 需求          | 链接                                                                                |
| ----------- | --------------------------------------------------------------------------------- |
| 创建 Modal 账号 | [Modal signup](https://modal.com/signup)                                          |
| 用户账号设置文档    | [Modal user account setup](https://modal.com/docs/guide/modal-user-account-setup) |
| 创建自动化 token | [Modal service users](https://modal.com/docs/guide/service-users)                 |
| Token 配置参考  | [Modal token config](https://modal.com/docs/sdk/py/latest/modal.config)           |
| Token 设置页面  | [Workspace token settings](https://modal.com/settings/tokens/service-users)       |

## 首次设置

1. 从官方 signup 页面创建 Modal 账号。
2. 在运行 AgentCompass 的机器上配置 Modal credentials。
3. 导出 `MODAL_TOKEN_ID` 和 `MODAL_TOKEN_SECRET`，或者让 Modal CLI 把 credentials 写入 `~/.modal.toml`。
4. 先跑单个 AgentCompass task，再提高并发。

本地开发通常可以直接走 Modal CLI setup：

```bash theme={null}
modal setup
```

自动化 runner 或 shared workspace 推荐创建 service user token，然后放在 shell 或 CI secret store 中：

```bash theme={null}
export MODAL_TOKEN_ID="..."
export MODAL_TOKEN_SECRET="..."
```

AgentCompass 的 Modal 鉴权优先级是：

| 来源                                             | 适用场景                                                |
| ---------------------------------------------- | --------------------------------------------------- |
| `environments.modal.token_id` 和 `token_secret` | 明确把凭据放在私有 `--config` 文件中。                           |
| `MODAL_TOKEN_ID` 和 `MODAL_TOKEN_SECRET`        | 推荐用于 shell session、CI 和共享脚本。                        |
| `~/.modal.toml`                                | 本地开发中通过 `modal setup` 或 `modal token set` 配置后的默认路径。 |

<Note>
  不要把 Modal token 提交到 `config/defaults.yaml`。请使用环境变量，或通过 `--config` 传入私有配置文件。
</Note>

## 验证凭据

先用 Modal CLI 验证当前 credentials：

```bash theme={null}
modal token info
```

然后用 AgentCompass 跑一个 recipe-backed 单任务：

## SWE-bench Verified

```bash theme={null}
agentcompass run \
  swebench_verified \
  mini_swe_agent \
  your-model \
  --env modal \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
```

SWE-bench Modal recipe 会从任务元数据选择镜像，并把 workspace root 设置为 `/testbed`。通常不需要手动传 `image` 或 `memory`。

## 完整 benchmark 与并发

```bash theme={null}
agentcompass run \
  swebench_verified \
  mini_swe_agent \
  your-model \
  --env modal \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --task-concurrency 32
```

如果模型 endpoint、Modal 账号限制或镜像启动时间成为瓶颈，请降低并发。

## Provider 参数

常见 Modal 覆盖项可以放在 `environments.modal` 或 `--env-params`：

| Field                            | 作用                                                           |
| -------------------------------- | ------------------------------------------------------------ |
| `app_name`                       | 把 AgentCompass sandboxes 归到一个 Modal App 下。                   |
| `environment_name`               | workspace 使用 Modal Environments 时，指定 sandbox 所属 environment。 |
| `image`                          | 不希望 recipe 选 image 时，手动使用 registry image。                    |
| `named_image`                    | 使用已发布的 Modal named image。                                    |
| `timeout` / `idle_timeout`       | 控制 sandbox 最大生命周期和 idle shutdown。                            |
| `cpu`, `memory`, `gpu`, `region` | 为重型任务请求资源或 placement。                                        |
| `env_variables`                  | 向 sandbox 注入非 secret 环境变量。                                   |

## Image 覆盖

只有明确要覆盖 recipe 行为时才使用 `image` 或 `named_image`。

```bash theme={null}
agentcompass run <benchmark> <harness> <model> --env modal --env-params '{"image":"python:3.13-slim"}'
```

## 相关页面

* [Agentic Coding](/zh/cookbooks/use_cases/agentic_coding)
* [Terminal Agents](/zh/cookbooks/use_cases/terminal_agents)
* [SWE-bench with Modal](/zh/cookbooks/remote_benchmarks/run_swebench_modal)
* [配置参考](/zh/reference/configuration)