> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuneplane.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 沙箱池

> 通过租约和明确的清理确认，在多个作业之间共享沙箱执行容量。

**Agent 环境**定义交互协议和部署方式，**沙箱池**管理共享执行容量，**任务集**定义要做的工作。它们的生命周期不同，因此分别管理。

每个沙箱池包含 Docker 或 E2B 后端、总并发执行位、单作业上限、租约超时和允许使用的用户。一个租约占用一个 **trial 执行位**，并非物理容器、CPU 或服务商计费数量。一个 trial 可能使用额外验证服务，配置实际后端容量时需计入这些资源。

## 配置与登记

先部署运行侧 Docker 能力或配置服务商账户，再由管理员在 **资产 → 沙箱池** 创建容量资源。同一批作业共享的容量应使用同一个池；重复创建指向同一服务商的池，不会共享配额。允许用户字段使用逗号分隔的用户名，`*` 表示所有平台用户。

创建沙箱池不会自动部署机器、授予 Docker 访问权限、保存服务商凭据或预热容器。普通用户可查看有权限的池及自己的租约；管理员可调整容量、排空、查看全部租约和确认回收。页面显示可用、占用和待清理数量，未释放租约优先显示，并支持分页。

## 在 Agent 评估中使用

在 **Agent 评估** 选择后端一致、处于可分配状态的池，导出配置后通过示例项目的 `harbor-eval` 实验运行。运行侧在每个 trial 开始前申请租约，容量不足时等待，执行期间续租，在明确确认服务商清理成功后归还。评估的单作业并发数不得超过池的单作业上限。

只有接入租约 API 的作业受此共享容量约束。未选择池的作业仍只受本地并发上限约束。已有 OpenEnv runner 登记不会自动获得池租约；其他训练框架需要在用户项目或环境插件中接入同一套申请、续租和释放流程。控制面不执行 Agent，也不调用服务商 SDK。

## 排空、撤销与回收

* **开始排空**：停止新的分配，已有租约可续租并正常完成。
* **撤销租约**：标记待清理。配合租约协议的 worker 在下一次续租被拒绝后停止执行，并尝试清理。
* **租约超时**：标记 worker 失联后的待清理占用。超时不能证明远程沙箱已经删除，因此不会自动恢复容量。
* **确认服务商已清理并释放**：管理员先在服务商侧删除或核实资源不存在，再在页面填写清理凭据。这项操作释放容量记录，不会调用服务商删除接口。

运行侧清理失败时会立即上报。进程被强制杀死后，仍需服务商 TTL 或人工巡检回收。清理状态不明确时保留占用；总容量不得调低到当前占用以下。旧尝试的资源在清理前也计入该作业上限。

## 运行侧 API

使用绑定作业尝试的 ingest token，不使用控制台用户令牌：

| 操作   | 接口                                                     | 请求正文                                        |
| ---- | ------------------------------------------------------ | ------------------------------------------- |
| 申请   | `POST /api/ingest/sandbox-pools/{pool}/leases`         | `request_key`、`provider`                    |
| 续租   | `POST /api/ingest/sandbox-pools/{pool}/leases/{lease}` | `action: renew`                             |
| 释放   | 同一租约接口                                                 | `action: release`、`cleanup_confirmed: true` |
| 清理失败 | 同一租约接口                                                 | `action: abandon`                           |

申请键标识某次作业尝试下的一个 trial。有效租约内重复申请是幂等的，完成或超时后不得复用该键。容量不足返回 429，应退避重试；排空、过期或尝试已被替换返回 409。重试／恢复后的令牌不能续租旧尝试；旧尝试在作业记录仍存在时，可以确认清理自己的租约。

示例适配器明确等待 `agent_environment.stop(delete=True)` 成功完成后才释放，因此需要运行镜像支持对应 Harbor API 和幂等清理。本地测试通过替身验证生命周期，尚未验证真实 Docker／E2B 部署。服务商凭据、真实清理和大规模吞吐仍需要在部署环境验证。