OpenSandbox 接入

opensandbox 是 AgentCompass 对 OpenSandbox 生命周期服务的客户端适配器，不是一种具体的 sandbox runtime。AgentCompass 使用官方 Python SDK 请求创建 sandbox，并通过 OpenSandbox 的统一命令与文件接口操作它；真正的工作负载由服务端配置的 runtime 创建，部署位置和隔离强度也由服务端决定。选择 --env opensandbox 不会在 AgentCompass 侧选择底层 runtime。

​

理解接入关系

OpenSandbox 官方架构将客户端、生命周期服务和 runtime backend 分开。当前官方服务支持 Docker 和 Kubernetes runtime，具体选择与安全配置都发生在 OpenSandbox 服务端。详见 OpenSandbox 架构说明。

层级	负责的内容
AgentCompass 的 opensandbox 适配器	把 Environment 的创建、命令和文件操作转换为 OpenSandbox SDK 调用。
OpenSandbox 生命周期服务	处理 API 鉴权、sandbox 生命周期和请求转发。
服务端 runtime	实际创建工作负载、拉取镜像，并决定部署位置、隔离方式和可用资源。

因此，使用该适配器前，必须先准备 OpenSandbox 服务，并在服务端选择与评测要求匹配的 runtime。AgentCompass 不会部署该服务，也不会替你配置 Docker、Kubernetes、镜像仓库凭证或底层隔离机制。

​

接入前准备

1. 按 OpenSandbox 的快速入门和安装说明部署生命周期服务。
2. 在服务端配置 runtime 和鉴权。实际 runtime 必须能够拉取评测镜像，并提供 Benchmark 与 Harness 需要的命令、目录和资源。
3. 确认 AgentCompass host 能访问生命周期服务，而且服务端代理能够转发 sandbox 的命令和文件请求。
4. 如果服务启用了鉴权，准备有权创建和销毁 sandbox 的 API key。

连接信息默认从 OPEN_SANDBOX_DOMAIN 和 OPEN_SANDBOX_API_KEY 读取，也可以写入私有配置文件的 domain 和 api_key。生产部署应启用 API key；不要将真实密钥提交到仓库。

​

使用 run 验证配置

当前适配器只支持从镜像创建 sandbox，因此必须显式提供与服务端 runtime 和评测任务都兼容的镜像。下面通过 sample_ids 只运行一个任务：

agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env opensandbox \
  --env-params '{"image":"registry.example.com/eval-image:tag"}' \
  --benchmark-params '{"sample_ids":["<sample-id>"]}'

请将占位符替换为实际组件和样本 ID。上面是 agentcompass run 的最小验证示例；模型端点等通用参数见 agentcompass run。

opensandbox 同样支持 agentcompass launch。在编排文件的 defaults.environment 中设置所有请求共享的配置，或在 requests[].environment 中设置单个请求；id: opensandbox 与适配器参数写在同一层。详见 launch 的映射规则。

AgentCompass 目前没有面向 opensandbox 的内置专属 Recipe，不会自动选择镜像或 workspace。

​

参数参考

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

前面“使用 run 验证配置”的完整命令已经展示了最小参数：当前适配器必须显式提供 image。

​

连接与凭证

字段	默认值	说明
api_key	OPEN_SANDBOX_API_KEY	OpenSandbox 生命周期服务的 API 密钥，不是镜像仓库或底层 runtime 的凭证。仅当服务端未启用 API 鉴权时才可留空。
domain	OPEN_SANDBOX_DOMAIN；未设置时由 SDK 使用 localhost:8080	生命周期服务的根地址。可以写 host[:port]，也可以写带 http:// 或 https:// 的地址；不带 scheme 时使用 HTTP，连接 HTTPS 服务时必须显式写出 https://。不要包含 /v1，SDK 会自动追加。

​

镜像与启动

字段	默认值	说明
image	无，必填	请求服务端 runtime 拉取的容器镜像。当前 AgentCompass 适配器只支持从镜像创建；私有仓库凭证需要在 OpenSandbox 服务端或 runtime 侧配置。
entrypoint	[]	传给 OpenSandbox 的容器入口参数数组，例如 ["bash","-lc","python app.py"]，不能写成单个 shell 命令字符串。保持空列表时，SDK 使用 ["tail","-f","/dev/null"] 作为默认入口。

​

标识与元数据

当前 AgentCompass 适配器不提供 OpenSandbox sandbox 名称或元数据参数；--env-params 和 environments.opensandbox 中没有对应字段。

​

工作区与环境变量

字段	默认值	说明
default_workspace_root	/workspace/	Benchmark 未指定任务工作目录时，提供给 Harness 的非空默认路径。该字段不会创建目录或配置存储；镜像或任务准备步骤必须确保该路径可用。
env_variables	{}	创建 sandbox 和执行命令时注入的环境变量映射，例如 {“LANG”:“C.UTF-8”}。键必须符合 [A-Za-z_][A-Za-z0-9_]*，值会转换为字符串。
shared_storage	[]	按顺序匹配的已有共享挂载路径映射，不会创建或挂载存储。每项包含 AgentCompass host 上的 host_path 和同一内容在 sandbox 中的 env_path。上传源路径命中映射时，AgentCompass 从对应的 env_path 在 sandbox 内复制；未命中时通过 API 上传。

下面的对象可以直接作为 --env-params 的一部分，或写入 environments.opensandbox：

{
  "shared_storage": [
    {
      "host_path": "/mnt/shared",
      "env_path": "/mnt/shared"
    }
  ]
}

shared_storage.host_path 和 shared_storage.env_path 都必须是绝对路径，不能包含 ..，也不能是文件系统根目录。host_path 必须是 host 上已存在的目录；env_path 必须已由 OpenSandbox 部署或 runtime 暴露到每个 sandbox，并且具备读取和访问权限。同一上传源路径匹配多个 host_path 时，列表中靠前的映射生效。

​

资源

字段	默认值	说明
resources	{}	传给 OpenSandbox resourceLimits 的字符串映射，例如 {"cpu":"2","memory":"4Gi"}；键、单位和可用规格由服务端 runtime 解释。未提供时，当前 SDK 使用 {"cpu":"1","memory":"2Gi"}。

​

网络

当前 AgentCompass 适配器不提供 OpenSandbox 专属网络参数，也尚未接入共享网络策略；network_policy、run_network_policy 和 verifier_network_policy 只能使用 public。OpenSandbox 服务端或 runtime 配置的网络限制仍然生效。

​

生命周期与超时

字段	默认值	说明
lifecycle_seconds	43200	请求服务端设置的自动过期时间（秒），必须为正数。即使 AgentCompass 保留 Environment，服务端仍可按该时间清理 sandbox。
request_timeout_seconds	120	OpenSandbox SDK HTTP 请求的超时（秒），必须为正数；不替代 sandbox 内命令的执行超时。
ready_timeout_seconds	120	创建请求发出后，等待 sandbox 内 execd（命令与文件服务）通过健康检查的最长时间（秒），必须为正数；它不表示 entrypoint 启动的应用已经就绪。

​

参数参考来源

• 运行 agentcompass config docs env opensandbox，可以查看当前安装版本实际支持的字段、类型和默认值。
• OpenSandbox SDK 的连接、创建参数和默认行为见官方 Python SDK 文档。

支持的字段、类型和默认值以 agentcompass config docs env opensandbox 的输出为准；其中 default_workspace_root 和 shared_storage 是 AgentCompass 适配器字段。生命周期服务和 server-side runtime 如何解释请求，以上游 SDK、服务端配置和具体 runtime 为准。

​

AgentCompass 适配范围

• 当前适配器只支持从 image 创建 sandbox，不支持 OpenSandbox API 提供的其他启动来源。
• 当前适配器尚未把 AgentCompass 的共享网络策略转换为 OpenSandbox networkPolicy，因此这里只接受 public，也不能按阶段切换。OpenSandbox 平台本身支持出站网络策略，服务端或 runtime 的限制仍可能影响实际网络访问。
• AgentCompass host 通过 OpenSandbox 生命周期服务代理命令与文件请求，因此服务端代理必须可用。
• 正常关闭 Environment 时会请求销毁 sandbox；当前没有 delete_on_close 一类的参数。--keep-environment 只跳过 AgentCompass 的主动销毁，不会覆盖服务端的 lifecycle_seconds。
• 命令自身的执行超时由 Harness 或调用方传入，不由 request_timeout_seconds 控制。

​

故障排查

现象	检查内容
提示 image 必填	在 —env-params 或 environments.opensandbox.image 中提供可拉取的容器镜像。
生命周期请求或鉴权失败	检查 domain、api_key 和 OpenSandbox 服务日志；api_key 不负责底层 runtime 或镜像仓库鉴权。
创建失败或镜像无法拉取	检查 OpenSandbox 服务端 runtime、镜像仓库凭证及 Docker / Kubernetes 日志。
sandbox 一直没有就绪	检查 sandbox 中的执行服务健康状态和服务端代理，再根据实际启动时间调整 ready_timeout_seconds。
资源请求被拒绝	确认 resources 的键、单位和规格能被所连接的服务端 runtime 接受。
共享存储校验失败	确认两个路径已指向同一份预先挂载的内容，并且 sandbox 侧路径可读、可访问。
提示网络模式不支持	当前 AgentCompass 适配器没有接入共享网络策略，请保持三个阶段均为 public。

​

相关页面

• OpenSandbox 官方架构
• OpenSandbox 服务端配置
• OpenSandbox Python SDK
• OpenSandbox API
• Environment 概览
• 配置 Environment
• 运行控制
• CLI 配置文件