沙箱部署为 Core 管理的 openai_hosted 执行选择沙箱提供商和每个沙箱的资源。PostgreSQL 为每个安装维护一个当前有效选择;Web 和 Core API 写入同一配置。节点文件保存其已安装副本和特定于主机的路径,且不能覆盖其资源。Runtime 不属于该选择:每个节点运行其所属安装验证过的 Runtime。该选择独立于 Harness。部署可以保持未配置状态,没有节点;此时它拒绝托管准入。
本契约负责下列 Core API 路由及其语义。节点指南负责操作员工作流,机器连接 API负责节点调用的路由,沙箱节点协议负责节点连接。
路由
每个路由都需要 Core 密钥。Web 的控制台服务器会在服务器端为已登录请求添加该密钥。
| 路由 | 效果 |
|---|---|
GET /core/v1/sandbox/deployment | 读取安全的当前配置、推出、重置和资源计数 |
PATCH /core/v1/sandbox/deployment | 更新整个部署的空闲超时,不改变配置代次 |
POST /core/v1/sandbox/deployment | 选择初始提供商和资源 |
PUT /core/v1/sandbox/deployment | 在线更改同一提供商的目标 |
POST /core/v1/sandbox/deployment/reset | 启动托管资源的持久清除或将其升级为持久清除 |
DELETE /core/v1/sandbox/deployment/reset?expected_generation=N | 取消剩余清除 |
POST /core/v1/sandbox/providers/{provider}/discovery | 使用临时凭据查询提供商配置目录 |
POST /core/v1/sandbox/enrollment-tokens | 签发带可选节点限制的一次性节点注册令牌 |
GET /core/v1/sandbox/nodes | 列出已注册节点 |
GET /core/v1/sandbox/nodes/{node_id} | 读取一个节点及其主机观测和历史 |
PATCH /core/v1/sandbox/nodes/{node_id} | 更改节点的名称和容量 |
DELETE /core/v1/sandbox/nodes/{node_id} | 移除节点 |
GET /core/v1/sandbox/nodes/{node_id}/allocations | 列出节点尚未释放的分配 |
GET /core/v1/sandbox/runtime-observations | 当前 Runtime 观测;请参阅 Runtime 遥测 API |
选择请求
POST 和 PUT 接受相同的完整选择,并要求提供先前 GET 返回的 expected_generation。对于初始未配置部署,零是有效值;省略或 null 无效。检查过期代次早于检查重置、提供商、资源和选择项相同这一条件,即使请求体与先前请求完全相同也是如此。
| 字段 | 含义 |
|---|---|
expected_generation | 必填的非负整数,来自 GET;绝不会自动刷新并重放 |
provider | 必须是 microsandbox、e2b、opensandbox 中恰好一个 |
resources | 每个沙箱的限制,见下文;microsandbox 和 OpenSandbox 必填,E2B 可选 |
network | 出站上限,见下文。POST 中省略表示默认值;PUT 中省略表示保持当前上限 |
configuration | 提供商的公开选择器。E2B:不可变的 template 构建以及可选且配套的 api_url 和 domain。OpenSandbox:api_url 和 image。microsandbox 仅接受 {} 或省略 |
credential | 提供商的只写凭据。E2B 和 OpenSandbox:{api_key},首次设置时必填,在 PUT 中省略以保留当前密钥;null 或空密钥无效。microsandbox 拒绝该字段 |
请求中没有 Core 地址。Core 根据安装公开 URL OAC_PUBLIC_URL派生部署的 core_url:这是节点和沙箱客户机访问 Core 时使用的源地址。包含 core_url 的请求会像包含任何其他未知成员一样被拒绝,并返回 400 invalid_request。E2B 客户机从 E2B 云访问 Core,OpenSandbox 客户机从 OpenSandbox 服务器所在的主机访问 Core,因此当公开 URL 为回环地址时,E2B 或 OpenSandbox 选择会被拒绝,并返回 409 sandbox_configuration_error。microsandbox 选择接受回环公开 URL,但这仅适用于本地开发,因为客户机的回环地址无法访问其主机。更改公开 URL 属于安装变更;参见更改公开 URL。
资源
| 字段 | 可接受值 |
|---|---|
cpus | 整数,1 到 255 |
memory_mib | 整数,512 到 1048576 MiB |
root_disk_mib | microsandbox:至少 1024 MiB;E2B 和 OpenSandbox:省略或为零 |
environment_disk_mib | microsandbox:工作区存储上每个新工作区的获准容量,零(默认值)表示不请求配额,正值必须至少为 1024 MiB 且要求强制执行配额;E2B 和 OpenSandbox:省略或为零 |
这些限制描述每个沙箱。节点的 max_active 和 max_retained 是独立的预留限制,设置方式见节点与分配;限制一经设置,任何主机测量值都不允许超过其中任何一个。即使数值满足这些边界,原生提供商仍可能拒绝这些值。
E2B 的 CPU 和内存必须与精确的就绪模板构建一致,Core 会在保存前通过固定版本 SDK 进行验证;磁盘容量仍属于模板的一部分。E2B 不接受其无法强制执行的磁盘配额。E2B 选择可以省略 resources:此时 Core 将构建的 CPU 数量和内存存储为 cpus 和 memory_mib,并通过 specification.resources 返回,不带磁盘字段。重启时,Core 会加载已提交的 E2B 选择,而不会再次验证模板构建,因此 E2B 中断绝不会阻碍检查或清理;新选择仍需验证。
OpenSandbox 将 cpus 和 memory_mib 应用为沙箱的 cpu 和 memory 资源限制;磁盘由其 runtime 设置。
microsandbox 会配置 CPU、内存和托管根磁盘,并在挂载于 /environment 的工作区存储上运行每个 Environment。microsandbox 辅助工具说明了 restore 如何处理这些限制。
响应中可选的 specification.workspace 是从所选工作区文件系统派生的不可变能力回执,不是可独立写入的设置。它仅包含 attachment、user_xattr 和 capacity_quota;文件系统配置、路径和凭据不进入 Sandbox specification。Core 保存前校验组合声明,保留代次校验与节点构造均使用此回执。microsandbox 始终具备该回执,尚未选择工作区存储时保存部署会返回 workspace_storage_required。E2B 和 OpenSandbox 没有回执,继续使用自有磁盘。Create 和 Resume 必须且仅当固定代次具备该回执时提供绑定。
先选择文件系统配置,再配置 microsandbox 部署。选择文件系统不会改变现有代次或 allocation;下一次 Sandbox 更新派生该回执。文件系统选择必须支持提供商声明的要求。现有部署要求相同的 attachment 和 user_xattr;选择可以更改 capacity_quota,此后在 Sandbox 更新设置相匹配的 environment_disk_mib 之前拒绝新工作区。既有工作区保持其获准时的容量。
网络
当 Environment 的 network.access 为 enabled 或省略时,network 限定该部署的每个沙箱最多能访问什么。到 Core 的连接和 Session 的模型提供商在公开地址上的端口始终可达,因为 Harness 运行在沙箱内。要访问私有地址上的模型提供商,请把其主机名或覆盖它的 *. 条目列入 domains。Environment 中的 MCP 连接与其他流量一样遵循该上限。
| 字段 | 可接受的值 |
|---|---|
public | 布尔值。true 允许公开地址;false 只允许 Core、模型提供商和 domains |
domains | 最多 100 个条目,每个不超过 253 个字符,为精确主机名或 *. 加至少两个标签的主机名,由小写字母、数字、连字符和点组成,且最后一个标签以字母开头。*.example.com 覆盖 example.com 任意层级的子域名,但不含 example.com 本身,后者需要单独条目;其他通配符、IP 字面量、端口和 URL 会被拒绝。Core 以小写、去重并排序的形式存储。名称解析出的每个地址都被允许,包括私有地址 |
默认值为 {"public": true, "domains": []}。无论哪种上限,回环、链路本地、云元数据地址以及其他所有私有地址始终被阻止,但 E2B 无法阻止元数据地址 169.254.169.254,且 E2B 沙箱根本无法访问私有网络。沙箱保留创建它的代次的上限。
每个 Provider 声明自己能强制执行什么(Sandbox Provider 协议):microsandbox 支持两个字段,E2B 支持 public: false 但不支持 domains,因为 E2B 沙箱无法访问私有网络,OpenSandbox 支持 public: false 但不支持 domains,因为其对私有网段的拒绝规则优先于域名解析出的私有地址。这些拒绝规则同样优先于到 Core 的连接,因此 OpenSandbox 需要安装公开 URL 解析到全局地址。解析到私有地址时,所有 OpenSandbox 沙箱都无法启动。所选 Provider 未声明的上限会返回 400 invalid_sandbox_configuration,param 为 network.public 或 network.domains。
E2B 配置
E2B 使用 template-id:build-uuid 形式的 configuration.template;构建 UUID 必须是规范形式且非零,仅提供可变模板别名将被拒绝。API 密钥在 PostgreSQL 中加密,绝不会出现在响应、引导配置、命令参数或日志中。默认情况下,Core 使用 https://api.e2b.app 和 e2b.app。对于兼容服务,请同时设置 configuration.api_url(一个不含路径、端口、查询、片段或凭据的 HTTPS 源地址)和 configuration.domain(沙箱数据平面 DNS 后缀);API 主机必须等于该域名或其子域。Core 会在发送守护进程凭据或使用 envd 之前,拒绝数据平面域名位于所选后缀之外的沙箱。
OpenSandbox 配置
OpenSandbox 使用 configuration.api_url 和 configuration.image:前者是 OpenSandbox 服务器的 HTTP 或 HTTPS 源地址,不含路径、查询、片段或凭据;后者是按其 adapter 指南所述为 OpenSandbox 构建的 Runtime 镜像。API 密钥在 PostgreSQL 中加密,绝不会出现在响应、引导配置、命令参数或日志中。Core 不检查镜像。首次选择时不会联系服务器,之后的更改会按密钥替换所述校验已保存的或新的密钥。镜像无法启动、服务器的出口 sidecar 未以 dns+nft 模式运行,或安装公开 URL 解析到非全局地址时,每次 Create 都会失败。
配置发现
POST /core/v1/sandbox/providers/{provider}/discovery 恰好接受 configuration、credential 和 query 对象,总大小最多为 64 KiB,运行时间最多为 30 秒。未知成员和 null 对象会被拒绝。凭据仅用于该请求,绝不会被存储或返回;发现操作不会保存任何内容、不会更改部署、不会分配任何资源,也绝不会证明某项选择会被准入。microsandbox 和 OpenSandbox 会以 400 sandbox_operation_unsupported 拒绝该操作。
发布 {"configuration": {…}, "credential": {…}, "query": {"field": "…", "path": […]}},其中 field 是提供商声明为 discovered 的字段,path 是前几级已选择的值。结果为 {"options": [{"value": "…", "label": "…", "resources": {"cpus": 2, "memory_mib": 2048}, "complete": true}]},可能为空。complete: true 的选项可保存为该字段的值,其余选项打开下一级。其他任何字段返回 400 invalid_request_error。
E2B 把 template 声明为 discovered。空 path 列出该密钥的模板,["template-id"] 以 template-id:build-uuid 值列出该模板的就绪构建及其 CPU 数和内存;官方端点可以省略 api_url 和 domain。固定版本 SDK 辅助工具读取 GET /v2/templates 并返回最多 200 条结果;达到限制或提供商失败会返回 503 和通用消息。部署写入操作会单独验证所选构建。
安全响应
GET 和成功的写入操作会返回 installation_id、provider、core_url(只读:安装公开 URL,即使配置前也存在)、mode、generation、owner_epoch、reset、rollout、idle_seconds、suspension、resources 和 credential_configured。已配置的部署还会返回 specification、specification_digest、configuration 和 metadata:这是适配器对其选择器及其记录的观测结果所作的公开投影,绝不会包含原始存储值或机密。E2B 返回 configuration.template、configuration.api_url、configuration.domain,并在记录后返回 metadata.template_build。OpenSandbox 返回 configuration.api_url、configuration.image 和空的 metadata 对象。microsandbox 返回空的 configuration 和 metadata 对象以及 credential_configured: false;未配置的部署则不含这两个对象。
metadata.template_build为{status, resources: {cpus, memory_mib, root_disk_mib}}:这是保存选择时 Core 通过固定版本 SDK 读取的构建。GET 绝不会调用 E2B,因此 E2B 中断期间该操作仍保持低成本。验证仅接受 CPU 数量和内存与所选值一致的ready构建;root_disk_mib是构建的原生磁盘大小,Core 不会强制执行该值。未知值为 null,metadata: {}表示未记录任何观测,在不提供凭据的情况下提交完全相同的 PUT 也不会刷新它。idle_seconds是部署的空闲超时,对每个提供商都适用。所选提供商声明 checkpoint 支持时,suspension为{retention_seconds},即 Core 的 suspension policy;其他部署(包括未配置的部署)返回 null。- 请求中的
resources和响应中的specification.resources是每个沙箱的限制。响应中的resources.allocations和resources.pending分别计算尚未释放的分配,以及尚未分配沙箱的待处理托管 Environment;resources.running计算计算资源正在运行的未释放分配,因此不含已挂起的分配。 - 未配置的部署具有空的提供商且没有 specification。microsandbox 使用
mode: nodes;E2B 和 OpenSandbox 使用mode: direct,且没有合成节点。 generation标识已保存的选择。owner_epoch用于对执行所有者和节点连接进行栅栏隔离;它不能替代expected_generation。specification_digest是服务器对提供商、限制和派生的工作区能力回执的标识;注册过程会原样回显该值。
packages/agents-client 中类型化的 SandboxAdminClient 会根据准确的这些结构检查部署、节点列表、节点详情和分配响应。未知成员、缺少成员或类型错误都会拒绝整个响应,并产生 502 invalid_admin_response 错误。节点的 rollout.diagnostic 可能不存在,也可能是一个代码,但绝不会为空;客户端会将未知代码读取为 provider_unavailable。
初始设置与同提供商更改
POST 会在持久保存候选配置之前对其进行验证,并且不会创建计算资源、Session 或模型请求。在当前代次上,完全相同的选择是无操作;使用旧代次则返回 409 sandbox_generation_stale,即使请求体相同也是如此。缺少前置条件或准备失败时,已提交的提供商保持不变。更改提供商前必须先重置。POST 还会在重置完成后使用该重置的新代次进行初始化。
仅在没有重置进行时,PUT 才接受同一提供商。只发送一次观测到的代次,绝不自动重放结果不确定的写入操作。新分配使用新提交的 specification,现有分配则保留其不可变的部署代次。同提供商更改不会停用任何节点、令牌或所有者 epoch,也不会排空任何执行:microsandbox 节点在继续提供旧固定版本的同时独立准备新目标,而 E2B 和 OpenSandbox 更改会立即生效。
E2B 密钥替换
在 PUT 中省略 credential 可保留当前密钥;不提供该字段的完全相同选择是无操作。提交密钥时,即使密钥相同,也始终会验证密钥并推进代次;null 或空密钥无效。仅更改密钥时使用相同的完整请求体(提供商、现有 configuration、可选 resources、expected_generation 和新 credential),无需单独路由,也不会隐式重置。
初始设置要求所选模板出现在该密钥所属团队的模板列表中;仅可公开读取并不足够。在线更改之前,Core 会验证已提交密钥拥有当前模板,然后要求候选密钥拥有完全相同的模板,从而确立团队所有权。Core 还会使用候选密钥在其原始端点读取候选构建和每个保留构建,并确认带安装标签的沙箱列表中每个已结算的实时回执。
| 结果 | 含义 |
|---|---|
409 sandbox_reset_required | 当前选择没有团队所有权锚点,或已提交密钥不再通过身份验证 |
409 sandbox_credential_ownership | 候选密钥属于另一个团队;初始化另一个团队前必须先重置 |
400 sandbox_credential_invalid | 候选密钥收到 401 或 403 |
400 sandbox_configuration_invalid | 候选构建无效或与资源不匹配 |
503 sandbox_verification_unconfirmed | 回执缺失或未结算,或读取未得到确认 |
不会返回提供商文本或凭据。写入操作及其 change 或 replace_credential 审计条目共用一个事务。替换操作会短暂对提供商调用设置栅栏,即使调用方已取消,也会等待辅助进程实际退出,并在提交前再次验证;辅助进程退出并不能证明远程 Create 已结算。栅栏和读取均有时间边界,失败时会保留旧密钥和生命周期。成功响应后,所有保留代次管理都使用已提交的密钥;只有在清理完成后,才能在 E2B 中撤销旧密钥,绝不能提前撤销。模板和资源更改不会排空生命周期。
OpenSandbox 密钥替换
请求规则与 E2B 密钥替换相同。候选密钥必须能通过每个保留代次的服务器的身份验证,并列出每个未释放分配的 sandbox;空列表不能证明任何事。401 或 403 返回 400 sandbox_credential_invalid,其他任何失败(包括某个分配的 sandbox 已不存在)返回 503 sandbox_verification_unconfirmed。服务地址和镜像的更改不会排空生命周期。
挂起策略
PATCH /core/v1/sandbox/deployment 接受 {"idle_seconds": 300}。idle_seconds 是必填整数,范围为 30–86400 秒,默认为 300。该设置保存在 Core 的数据库中。每个已配置的提供商都可修改;未配置或正在重置的部署拒绝写入。成功返回当前部署视图,idle_seconds 反映已保存的值。
支持 checkpoint 时,空闲超时触发挂起。不支持时,Session 持有的分配继续运行;超时对未挂载 Environment 的作用见无 Session 时的生命周期。
变更从下一轮生命周期检查起作用于现有和新建的运行中分配,不重启 Core、不推进配置代次,也不重新部署节点。已经开始的挂起不撤销;现有快照和 24 小时快照保留期不变。容量压力回收仍可提前挂起空闲的分配,并在 retained slot 已满时提前结束符合条件的检查点的保留期。Web 在 设置 → 沙箱与调度 → 自动挂起 管理此部署级设置,提供商不支持 checkpoint 时为 空闲超时;各节点的容量上限仍属于节点,在 节点 中通过 编辑节点 编辑。
代次所有权与推出
runtime_deployment 保存当前 specification。被取代的行仅保留不可变的 specification、构建和端点元数据,绝不保留另一个提供商密钥。直接分配(E2B、OpenSandbox)在预留时绑定其代次;节点放置在调度器预留兼容容量时绑定,其分配会复制该代次,即使之后发生更新也是如此。检查、续期、命令和清理使用分配的原始 specification 和端点以及当前密钥;缺失代次绝不会回退到当前 specification。已释放代次的标识仍会保留。
当一个代次为当前代次、被尚未释放的分配或放置引用,或者被尚未移除的节点固定时,该代次会保留。节点的持久服务固定状态可跨离线时段和零资源状态保留,并与当前就绪状态相互独立。回收操作与更新和准入共享部署锁,每轮最多删除 32 个符合条件的代次行。只有确认释放后,重置才会停用固定状态并清除被取代的行。
每个部署响应都包含 rollout:
"rollout": {"state": "settled", "previous_generation_sandboxes": 3, "nodes": null}previous_generation_sandboxes 使用与资源总数相同的快照,统计旧代次中尚未释放的分配以及没有分配的待处理放置,绝不会重复计算同一资源。直接(E2B、OpenSandbox)部署和未配置的部署返回 null nodes。节点部署将 nodes 返回为计数 {ready, preparing, failed, unknown},每个尚未移除的节点恰好归入一个类别:
- 在当前连接上离线的节点为
unknown; - 否则,当前连接和所有者 epoch 上的精确目标观测会给出
ready、preparing或failed,缺少观测则给出unknown。
flowchart TD
A{"Online on its current connection?"} -- no --> U["unknown"]
A -- yes --> C{"Target observation on this connection and epoch"}
C -- ready --> R["ready"]
C -- preparing --> P["preparing"]
C -- failed --> F["failed"]
C -- missing --> U
节点在当前所有者 epoch 下保持连接且心跳未过期时,即为在线。目标推出与服务就绪状态相互独立:unknown、preparing 或 failed 不会移除已独立确认的较旧服务代次。provider_ready 要求节点在线,并且在该连接和 epoch 上观测到精确的服务代次。固定状态本身绝不表示就绪。
每个节点会添加 rollout: {state, ready_generation, diagnostic?},其中 ready_generation 是可为 null 的持久服务固定状态,diagnostic 是目标代次的固定代码;分配项会添加 deployment_generation。仅当 rollout.state 为 preparing 或 reset 非 null 时,才每五秒轮询一次;旧 Session 以及失败或离线的节点本身均不会使轮询保持活动状态。
节点模式创建先验证目标部署,提交 Session、pending Environment 及初始输入,但不预留计算资源。节点全部已满、离线或准备中时,已接受的工作继续等待;未配置部署、reset 或不支持的组合仍拒绝准入。共同调度器对尚未放置的需求进行有界循环扫描,分页按需求记录时间和 Environment ID 排序,每轮使用固定时间上界,避免持续的新需求阻止重新访问较早的工作。它检查在线状态、精确服务代次就绪情况、地址、共享容量和所选代次的 Harness/文件系统兼容性,然后优先选择最新的合格固定代次。预留后的 placement 保持不可变,直到确认释放或已结清的检查点转移。有界扫描跳过暂时不可调度的需求,并在重启后继续。已有 suspended allocation 按检查点转移契约,通过同一容量锁预留符合条件的检查点容量;这不构成热恢复和未放置工作之间的全局公平性保证。输入保留原始五分钟期限,等待容量的时间也计入其中。从未有过沙箱的 Environment 在其初始输入过期后不再等待容量,并保持 pending,直到新输入到达。准备开始时,若 Environment 已不再等待容量,Core 释放其节点预留且不做任何准备;创建时没有输入的 Environment,以及有未过期输入或唤醒请求的 Environment,仍会准备。
如果准备工作在新 allocation 预留前失败,Core 仅释放该次尝试的节点预留,并保留已有文件系统身份。其下一次放置需求按不早于释放的时间排序,排在已经等待的工作之后;成功重试使用新选中代的 specification。计算结果不确定的 allocation 继续保留其预留。
重置
要更改提供商,请启动重置:
{"expected_generation": 7, "clear": "auto", "deadline_seconds": 3600}clear 必填,可取 auto 或 force。deadline_seconds 适用于 auto,默认值为 3600,接受 300 到 86400;force 必须省略该字段。在关闭新的托管准入之前,Core 会持久保存绝对截止时间和请求方的审计来源信息;请求结束后以及跨重启时,执行所有者会继续推进清除。在 auto 模式下,Core 会归档空闲的托管 Session,包括排队或待处理工作以及已暂停沙箱,并等待正在执行或等待的 root Turn 和 Subagent Turn 以及待处理的文件写入完成,同时在 Session 锁下重新检查。到达持久保存的截止时间时,Core 会持久地将操作升级为 force。force 会对每个符合条件的托管 Session 使用常规归档取消和清理路径。绝不触碰自托管 Session。重置还会让每个未挂载的独立 Environment过期,并请求清理它。
stateDiagram-v2
direction LR
[*] --> inactive
inactive --> auto: POST auto
inactive --> force: POST force
auto --> force: deadline or POST force
auto --> inactive: DELETE
force --> inactive: DELETE
auto --> unconfigured: no held resources
force --> unconfigured: no held resources
以相同代次和模式再次启动时,会保留原始截止时间。auto 可以升级为 force,但不能反向升级。使用当前 expected_generation 发出 DELETE 会取消剩余工作并重新开放准入;它不会撤销归档、恢复已过期 Environment,也不会取消已经请求的清理。没有活动重置时,DELETE 是无操作;请求过期则返回 409。
未激活时 reset 为 null,否则为:
{"clear": "auto", "requested_at": "2026-09-27T12:00:00Z",
"deadline_at": "2026-09-27T13:00:00Z", "forced_at": null,
"remaining": {"busy": 2, "idle": 1, "cleanup": 3, "on_offline_nodes": 2,
"offline_nodes": [{"node_id": "node-uuid", "name": "worker", "resources": 2}]}}一个数据库快照会先按 cleanup,再按 busy 或 idle,对每个尚未释放的分配和每个尚未分配沙箱的待处理托管 Environment 进行划分,因此 busy + idle + cleanup == resources.allocations + resources.pending。已删除或已过期且具有未释放回执的 Session 计入 cleanup。offline_nodes 是通过分配或活动放置持有资源的离线节点的完整列表,并按 ID 排序,其总和等于 on_offline_nodes;存在性依据节点是否在线判断,而不依据提供商就绪状态。直接的 E2B 和 OpenSandbox 资源没有节点。离线资源会持续构成阻塞条件,直到清理确认其已释放。
当两个占用计数均达到零时,所有者会排空执行,并原子清除提供商、mode、specification、提供商 configuration、credential、metadata 和提供商 policy,停用节点和未使用的注册令牌,递增代次与所有者 epoch,并记录 reset_complete。安装身份和历史会保留。Core 会立即发布未配置状态,即使没有提供商也保留新代次,因此延迟加载无法恢复旧配置。使用 POST 和返回的代次即可重新配置,无需重启。
重置期间,新的托管准入会返回 503 sandbox_reset_in_progress,并且不会留下临时 Session 行;实时输入、回执重试、恢复和清理会继续进行。管理写入和新注册会返回 409 sandbox_reset_in_progress,而已注册节点仍可读取其配置,以便恢复并执行清理。每个 Session 的 archive仅需要当前代次,无论是否正在重置均可使用。它会保留历史以及已持久化的 Files 和 Artifacts,丢弃未持久化的工作区,并阻止 Session 恢复;轮询 archive GET 以获取实际释放状态。重置绝不会伪造释放回执。
强制归档会立即对凭据和新工作设置栅栏。当 Turn 的托管传递仍处于连接状态时,Core 只会为该传递保留原生的取消和终止回执路径,直到终止提交完成;从最初取消请求起最多持续 20 秒;在取消确认或终止提交仍待处理时,done 不会结束此时间限制。该排空过程绝不会授权重新连接、访问 workspace 或 MCP 或继续执行,显式撤销凭据会终止它。回执缺失或失败时会如实保留失败结果;所有者断开连接、过期或重启时,会回退到常规提供商清理。
一个变更操作门会串行化设置、PUT、重置、取消和最终处理。archive 会先锁定 Session,再锁定部署,最终处理绝不会颠倒此顺序。候选操作会绑定到重置请求时间,因此取消后以相同代次启动的新重置无法复用旧工作。绝不重放被拒绝或结果不确定的写入操作:读取当前状态并重新决定。
节点与分配
节点容量独立于部署 specification 设置。POST /core/v1/sandbox/enrollment-tokens 接受可选的 max_active 和 max_retained,并返回 {token, expires_at, enrollment_id};enrollment_id 是该命令的公共句柄,绝不是凭据。Core 将令牌与发送的限制一同存储,省略的限制保持未设置。节点注册时,Core 把每个显式限制原样复制给节点,并把每个未设置的限制设为注册请求中的主机测量值与当前 specification 的推荐容量;限制未设置且没有主机测量值时,返回 409 sandbox_node_host_unmeasured,令牌保持未使用。只设置 max_retained 时,推导出的 max_active 不会超过它;只设置 max_active 时,推导出的 max_retained 会被提高到至少等于 max_active。microsandbox 会使用两个限制。E2B 和 OpenSandbox 没有节点,并返回 409 sandbox_deployment_conflict。节点不能提交限制,但未设置的限制取决于节点在注册时报告的主机测量值,范围限定在 1 到 1000000。其本地检查可以拒绝其无法运行的部署,但绝不会提高限制。显式值和之后的 PATCH 修改具有约束力:节点注册之后,Core 不再推导。节点容量为操作员说明了这些限制。
GET /core/v1/sandbox/nodes 返回 {data: [...]},其中每个节点包含 id、name、provider、online、last_seen_at、created_at、max_active、max_retained,计数项 active、reserved、running、retained、snapshots 和 cleanup_pending,以及 provider_ready、主机测量值 cpu_count、available_memory_bytes 和 available_disk_bytes、rollout、recommended_capacity、enrollment_id 和 core_url。recommended_capacity 是 {max_active, max_retained},即节点最新健康状态与当前 specification 的推荐容量;在节点报告 CPU 数量或有效核数以及总内存之前,以及当前 specification 未通过校验时,为 null。enrollment_id 是注册该节点的命令的句柄;如果 Core 没有该句柄,则为 null。core_url 是注册时的安装公开 URL;core_url 与当前公开 URL 不同的节点不会收到新放置。已放置到该节点的工作会继续在那里完成,包括已放置但尚未获得分配的 Environment;只要旧地址仍能访问 Core,其保留沙箱仍可恢复。参见更改公开 URL。
节点管理代次,因此其 provider_ready 取决于服务代次,目标代次的固定代码会出现在 rollout.diagnostic 中。节点会对首次失败的就绪检查进行分类,并且只发送代码;携带任何其他值的帧均无效,且 Core 绝不存储或返回探测文本或主机路径。这些代码是与提供商无关的类别:provider_unavailable、host_unsupported、artifacts_unavailable、runtime_image_unavailable 和 capacity_insufficient。就绪代码给出了原因和操作员应采取的措施。Core 和节点必须来自同一发行包。
PATCH /core/v1/sandbox/nodes/{node_id} 接受 {name, max_active, max_retained};降低限制不会停止任何正在运行的沙箱。当节点仍持有分配、快照、预留或待处理清理时,包括节点离线期间,DELETE /core/v1/sandbox/nodes/{node_id} 会拒绝操作并返回 409 runtime_node_in_use。移除操作不会删除任何计算资源,并且会停用该节点的身份;该主机只能作为新节点重新加入。不存在节点排空过程。
GET /core/v1/sandbox/nodes/{node_id}/allocations 列出节点尚未释放的分配。每个项的 session_id 是该分配的 Environment 当前挂载的存活 Session;没有挂载时为 null。每个项的 compute_phase_changed_at 表示该分配进入当前 compute_phase 的时间;未知时为 null。该时间是阶段切换时间,不是快照到期时间。此响应不提供快照截止时间,不应根据 suspension.retention_seconds 推算。
推荐容量
Core 用一条规则,从节点主机和单个沙箱的大小推导推荐值。cpus 在节点报告 effective_cpu_cores 时取该值,否则取 cpu_count。
max_active取floor(2 × cpus / specification cpus)与floor((total_memory − 2 GiB) / specification memory)中较小者,至少为 1,至多为 1000000。CPU 按核数的两倍分配,因为 Agent 沙箱大多在等待模型。内存从不超配,并为主机和节点服务保留 2 GiB。- 不支持检查点的提供商,
max_retained等于max_active。否则取max_active与floor(available_disk / 2 / root_disk)中较大者,至多为 1000000:挂起的沙箱把根磁盘检查点保留在节点上,其中一半可用磁盘留给它们。
主机未同时报告 CPU 数量或有效核数与总内存时,没有推荐值。Core 仅在注册令牌未设置某个限制时应用它;Web 在 编辑节点 中显示它,从不自行应用。
各沙箱提供商中的字段含义
某些字段在不同提供商中保持同一名称,但含义不同或不适用。部署字段来自 GET /core/v1/sandbox/deployment,节点和分配字段来自节点路由,Runtime 字段来自 Runtime 遥测 API;其中 disk 仅出现在观测列表中,历史则在 Session Runtime 历史下说明。
| 字段 | microsandbox | E2B | OpenSandbox |
|---|---|---|---|
| 独立工作区文件系统 | 必需:Kernel NFS adapter,与计算资源分开配置 | 不支持 | 不支持 |
部署 specification.network | public 和 domains | 仅 public;domains 必须为空,私有网络不可达 | 仅 public;domains 必须为空 |
部署 specification.resources | cpus、memory_mib、root_disk_mib,以及作为配额请求的 environment_disk_mib | cpus 和 memory_mib,必须等于就绪模板构建中的值;省略时取自该构建;无磁盘字段 | cpus 和 memory_mib,作为资源限制应用;无磁盘字段 |
部署 metadata.template_build | 不存在:metadata 为空 | Core 保存选择时读取到的构建 | 不存在:metadata 为空 |
部署 suspension | {retention_seconds} | {retention_seconds};Core 用 SDK 的原生 pause 暂停空闲的 E2B 沙箱 | null:不支持 checkpoint;见无 Session 时的生命周期 |
部署 resources.allocations、resources.pending | 所有节点的总数 | Core 中尚未释放的 E2B 沙箱,以及正在等待沙箱的托管 Environment | Core 中尚未释放的 OpenSandbox 沙箱,以及正在等待沙箱的托管 Environment |
注册令牌 max_active、max_retained | 两个限制均适用;省略的限制在注册时推导 | 先执行 400 容量检查,然后返回 409 sandbox_deployment_conflict;E2B 没有节点 | 先执行 400 容量检查,然后返回 409 sandbox_deployment_conflict;OpenSandbox 没有节点 |
| 节点列表和详情 | 已注册节点 | 空列表;详情返回 404 | 空列表;详情返回 404 |
节点 retained、snapshots、max_retained | 已暂停沙箱数为 retained 减去 active;snapshots 还包含恢复或清理期间保留的快照 | 不适用 | 不适用 |
节点 host.available_disk_bytes | 节点状态目录所在文件系统的可用空间;沙箱磁盘有自己的配额 | 不适用 | 不适用 |
分配 compute_phase、compute_phase_changed_at | 包含 suspended;时间表示当前阶段的起点,不是快照到期时间 | 不适用:没有节点分配 | 不适用:没有节点分配 |
Runtime 观测 memory | 来自 VM:内存限制和使用量 | 来自 E2B 指标:内存使用量和限制 | 来自 execd 指标:内存使用量和限制 |
Runtime 观测 disk | null | E2B diskUsed 和 diskTotal;模板未报告时为 null | null |
Runtime 观测 lifecycle_state: sleeping | 暂停期间 | 从不 | 从不 |
| Runtime 历史 CPU | 根据累计 CPU 时间派生 | 每个时间桶中 E2B 所报告使用率比值的平均值 | 每个时间桶中 execd 所报告使用率比值的平均值 |
错误
| HTTP | 代码 | 场景 |
|---|---|---|
| 400 | invalid_request_error 或 invalid_request | 请求格式错误 |
| 400 | invalid_sandbox_configuration | 配置验证产生的诊断错误 |
| 409 | workspace_storage_required | 提供商在工作区存储上运行每个 Environment,但尚未选择存储 |
| 409 | sandbox_generation_stale | expected_generation 不是当前值;current_generation 提供当前代次 |
| 409 | sandbox_reset_required | 提供商不同;详情会指明当前提供商和请求的提供商 |
| 409 | sandbox_not_configured | 更改未配置的部署 |
| 409 | sandbox_reset_in_progress | 重置期间执行管理写入或新注册 |
| 409 | sandbox_deployment_conflict | 更改无法应用于另一种状态 |
| 409 | runtime_node_in_use | 节点仍持有资源时移除节点 |
| 503 | execution_unavailable | 无法准备提供商 |
存储和凭据故障始终作为错误处理:读取为空或读取失败绝不能证明清理完成。机器连接 API列出了节点路由的错误。
规范的节点规格
sandbox/deployment_contract.go负责资源边界和规范字段顺序,每个已注册提供商的 sandbox.DeploymentPolicy 声明其要求;sandbox/deployment.go在 Core 中应用这些规则。安装程序会使用 deploy/node/node_spec.py 中生成的声明,TypeScript 客户端和 Web 使用 packages/agents-client/src/deployment-contract.ts 中生成的边界、提供商声明和各提供商的 setup 声明(sandbox.SetupDeclaration),因此不存在第二套限制或提供商列表。请在仓库根目录运行 go run ./services/core/cmd/specification-contract -write 重新生成两者;作为 make check 一部分的沙箱 Go 测试会拒绝过时的投影。
规范摘要是紧凑 UTF-8 JSON 的 SHA-256,其中 provider 位于首位,其次是 resources。资源字段遵循契约的声明顺序;值为零的可选磁盘字段会被省略,必填字段则保持存在。摘要绝不会受传入字段顺序或空白字符影响。services/core/internal/sandbox/testdata/deployment-contract.json保存共享验收用例、精确的规范字节和摘要,Go 与 Python 测试都会使用这些内容。
规范摘要的 JSON 在 resources 后包含可选的 workspace,字段按文件系统声明顺序排列:attachment、user_xattr、capacity_quota,布尔字段始终保留。该回执参与不可变 specification digest。