Modal

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

官方设置入口

需求	链接
创建 Modal 账号	Modal signup
用户账号设置文档	Modal user account setup
创建自动化 token	Modal service users
Token 配置参考	Modal token config
Token 设置页面	Workspace token settings

首次设置

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

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

modal setup

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

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` 配置后的默认路径。

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

验证凭据

先用 Modal CLI 验证当前 credentials：

modal token info

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

SWE-bench Verified

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 与并发

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。

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

快速开始

核心模块

执行环境

实战指南

官方设置入口

首次设置

验证凭据

SWE-bench Verified

完整 benchmark 与并发

Provider 参数

Image 覆盖

相关页面

​官方设置入口

​首次设置

​验证凭据

​SWE-bench Verified

​完整 benchmark 与并发

​Provider 参数

​Image 覆盖

​相关页面

官方设置入口

首次设置

验证凭据

SWE-bench Verified

完整 benchmark 与并发

Provider 参数

Image 覆盖

相关页面