Skip to content

沙箱提供商协议

沙箱提供商协议连接 Core 与为 Core 管理的(openai_hosted)Environment 提供计算资源的 adapter,并由该 adapter 运行启动 Runtime daemon 的有界引导流程。本页面向 adapter 作者:说明提供商必须实现什么,以及可以依赖 Core 做什么。microsandbox、E2B 和 OpenSandbox 实现了该协议。

调用方Core 的 runtime manager 与 execution Worker
实现microsandbox(node adapter)、E2B 和 OpenSandbox(direct adapter);见参考 adapter
代码sandbox_provider.go 中的 SandboxProvider,以及 setup 阶段的 ConfigurationAdapter
传输direct adapter 在进程内被调用。node adapter 运行在沙箱节点上,通过沙箱节点协议接收同样的调用
版本规则进程内接口没有 wire 版本。沙箱节点协议和各 helper 协议要求精确版本匹配
术语含义
EnvironmentCore 拥有的持久执行场所;参见 Environment 与模板
AllocationCore 为 Environment 拥有的一份计算资源租约,由 Reference 标识
Deployment整个部署唯一的提供商选择;参见沙箱部署

实现提供商 ​

  1. 阅读契约。 实现每个方法,支持必需操作,并按实现接口对其余每项操作声明决定。
  2. 编写 adapter 包,放在 services/core/internal/sandbox/<kind>:包括原生 SDK 调用、所有权检查、身份转换、私有配置,以及 node adapter 的 node-local 构造。声明 var _ sandbox.SandboxProvider = (*YourAdapter)(nil)。进程外 helper 放在 services/core/tools/<kind>-provider。
  3. 注册 kind 一次,遵循注册提供商 kind。注册是明确构造,不是 init 时 plugin registry。
  4. 标记所属资源,使用 Runtime 名称表中的提供商 ownership label,不接受旧 label 名称作为回退。
  5. 运行契约套件 make check-sandbox-provider-contract;参见一致性测试。
  6. 对真实计算资源运行原生验收,再运行 make check。
  7. 在 adapter 旁编写文档,参考参考 adapter。

角色 ​

参与方拥有从不
Core持久 Environment、allocation、placement 和 cleanup 状态;lifecycle 串行化;创建、暂停、恢复或释放的每项决定调用提供商声明为不支持的操作,或在离线 node、超时或空读取时释放 allocation
沙箱提供商allocation 的计算资源、有界 Runtime 引导、原生身份与所有权检查,以及 Core 观察和清理所需的 receipt运行 Environment 初始化、Skill、Plugin、MCP 设置、初始文件、execution 或 Files,或凭裸原生 ID、名称或路径定位资源
Runtime通过 Core–Runtime 协议准备能力并执行 Turn,身份由提供商通过 Runtime 引导文件交付分配或销毁计算资源

隔离属于提供商基础设施,不属于 daemon;参见 Runtime 与外层隔离。使用薄 adapter 封装厂商维护的 SDK。

实现接口 ​

sandbox_provider.go 包含 Core–沙箱提供商协议:负责 allocation、checkpoint 和观测的 SandboxProvider 接口及其请求与结果类型,以及 setup 阶段的 ConfigurationAdapter 及其类型化错误。Core 在此边界之外也使用的值类型,例如 DeploymentSpec 和 CallFence,位于同一 package 的独立文件中。每个方法在编译期都必须实现,ProviderOperations() 声明提供商支持哪些方法。以下五项操作始终支持:

操作用途
Create为 Reference 创建计算资源,并运行有界 daemon 引导
GetInfo观察当前计算资源,不修改它
Renew延长原生租约;backend 没有租约时仅观察
Kill回收 allocation 的计算资源与保留资源
RunCommand在 allocation 的计算资源中运行有界命令

没有原生可续期租约的 backend 仍遵守 Core 的 hosted expiry 和 cleanup 要求。每个 adapter 都实现 RunCommand,测试也执行它,但 Core 编排不调用它;只有 node transport 转发。机密命令输入通过 Command.Stdin 传输,不放在参数或日志中;结果保留字节顺序、有界输出和实际退出状态。

Bootstrap.Workspace 和 ResumeRequest.Workspace 仅当提供商的 DeploymentPolicy.Workspace 已声明时才携带外部工作区绑定;提供商对此的义务见挂载。Core 仅在提供商声明支持 checkpoint 时设置 Bootstrap.SuspendControl,提供商将其原样放入 Runtime bootstrap。

明确的操作契约 ​

每个提供商返回完整的 ProviderOperations() 声明,SandboxProvider 中除 ProviderOperations 本身外的每个方法各占一项。接口的方法集就是操作清单,sandbox.ValidateOperations 根据它检查声明。下表中的分组是协议文件中的列表,由测试保证它们与该方法集一致,因此新增方法必须加入其中一组。

操作要求职责
Create、GetInfo、Renew、Kill、RunCommand支持Allocation 生命周期与有界命令
Observe明确决定检查所有权、只读地观测一个 allocation
Initial、NewCompute、GetCompute、RenewCompute、Suspend、Resume、ResumeCompute、KillCompute、DeleteSnapshot、RunCommandCompute所有 checkpoint 方法决定一致精确计算实例、捕获与恢复、保留源恢复和清理
RestorePreparation、SavePreparation两者决定一致复用已完成的 Environment 准备结果

Initial 和 NewCompute 构造 compute reference,不分配资源;ResumeCompute 在暂停中止后仅解冻同一驻留实例;RenewCompute 在提供商有原生租约时延长精确运行实例的租约,否则与 GetCompute 完全一样只做观察;RunCommandCompute 在一个精确 compute incarnation 中运行有界命令。Core 使用 RunCommandCompute 在恢复后唤醒 parked daemon(runtime_compute_wake.go)。

SavePreparation(reference, key) 在准备完整完成后保存该分配初始 compute 中准备写入 /environment 的内容(workspace、packages 和 initialization,从不包括 Runtime 状态),RestorePreparation(reference, key) 把已保存的内容放回,没有有效条目时返回 false。key 是不透明的:Core 由 Project 和所有进入准备的内容推导它,从不使用 Environment、Session、Harness 或 Agent,提供商也从不解释它。存储、按 Runtime 镜像划分范围、过期和淘汰由提供商负责。条目在保存后 24 小时内有效,恢复不得使用已过期的条目。Core 在 Runtime 连接后调用 RestorePreparation,命中时只发送 finalize 操作即完成初始化。未命中时完整准备并调用 SavePreparation;保存错误只记录日志,不会使 Session 失败。两者都未声明的提供商始终完整准备。microsandbox 适配器在 Runtime home 下的私有目录中为每个 key 保存一个归档。

每个声明项为不带 reason 的 state: supported,或带 authored reason code 的 state: unsupported。缺失、零值、未知或不安全项都会验证失败。给 SandboxProvider 添加方法时,必须在每个 adapter 中明确决定并实现;不提供 base type,也不生成笼统的不支持实现。

不支持的方法在任何原生 I/O 前返回 providercontract.UnsupportedError。错误指明精确操作和安全 code,不包含原生消息、资源身份、endpoint 或凭据。空结果、nil error、Unavailable 或未知 mutation 结果都不能代替 unsupported,五项必需方法不能返回 unsupported。

每个 adapter 拥有一个 Operations() 函数,由实例和注册共享。providers.ValidateBinding 根据接口并相互对照检查两者,Runtime admission 与 node generation 加载也拒绝不完整提供商。调用方在调用操作前用 providercontract.Require 检查声明,从不使用 type assertion。

Observe 读取一个 allocation,不续期、启动、准备或停止计算资源;参见 Runtime 可观测性。

契约测试在未配置原生 client 时调用每个声明不支持的方法,要求匹配错误和零值结果,并拒绝不完整或矛盾的声明。支持的行为仍需要原生和生命周期测试。

身份与资源所有权 ​

Reference 是精确的 (TenantID, EnvironmentID, AllocationID) 元组。Core 在 Create 前持久化新的 allocation ID;它不是 Environment ID。adapter 还将资源绑定到安装实例,不按裸原生 ID、display name、猜测路径或未验证 label 定位或授权资源。每次修改、读取和清理验证相同所有权。

Core 串行化生命周期操作,并在任何不确定 mutation 后保留 allocation,因此 adapter 必须保留足够的原生身份和回执供观测与清理。失败调用可以同时返回 Info 和 error:保留与 reference 绑定的结算证据,不把失败变成成功。冲突后不得悄悄创建替代资源、覆盖凭据或切换新 allocation。

Info.ProviderID 和 Info.State 描述计算资源。仅在有匹配 Reference 和原生身份时,Core 将计算资源视为 running;可以观察其他原生状态,但不声明就绪。BootstrapComplete 表示引导到达最终修改步骤。CreateSettled 证明原始尝试不能再修改资源,不表示成功:

  • State="absent" 携带匹配 Reference 和 CreateSettled=true,是明确的创建不存在回执,不含原生 ID 或已完成引导。
  • ErrNotFound、空列表、超时或单独成功的 Kill 都不能证明进行中的 Create 不会稍后出现。
  • Core 也可以依据匹配的 running resource 和已完成 bootstrap 结算创建。取得此类证据或明确回执前,创建保持未知,即使清理尝试看不到资源。

Microsandbox 在返回创建不存在回执前永久关闭初始 Create 准入;其 helper 协议定义持久化 allocation 锁屏障。普通 GetCompute 的不存在观察不关闭准入。

Kill 负责清理 allocation 的计算资源和保留资源,包括部分 bootstrap storage;名称冲突时不删除其他租户资源。Core 仅在确认清理和创建已结算后释放持久所有权。关闭 Executor 或取消 Harness 不删除 Environment、工作区或 allocation。

操作结果与重试 ​

每次调用接收有界 context。到期或取消结束调用方等待,不证明回滚、停止、清理或不存在。adapter 或 transport 不得脱离跟踪执行 mutation,也不重放超时命令。

操作已确认结果失败或未知结果恢复
Create匹配计算资源与 bootstrap 证据;执行仍需要 Runtime preparation无效或外来配置被拒绝;重复返回 ErrExists;transport 失败可能隐藏已创建资源观察原 Reference。不重放 Create,即使使用新凭据。保留部分资源用于所属清理
GetInfo不修改的当前计算资源观测ErrNotFound 仅表示缺少观测;error 不是不存在的证明重复有界读取;不将其变成 create、start 或 renew
Renew原生租约已延长,或无租约提供商的观测超时可能隐藏延期;停止或缺失计算资源仍保持原样先观察,再由 reconciler 续期同一 allocation。不复活计算资源或虚构 lease expiry
Kill所属计算资源与保留存储已移除;重复已确认不存在时成功error 保留所有权与清理意图;所有权不匹配不删除外来资源未决创建或 mutation 已隔离后重试同一 Reference 的清理;不提前释放 owner
RunCommand, RunCommandCompute收集到输出和实际 exit code;非零退出是已结算命令失败缺失原生完成为 ErrCommandUnconfirmed;部分输出不是成功不重放。无法证明完成时保留 owner,并在复用前回收

ErrInvalid、ErrOwnership、ErrExists、ErrNotFound、ErrComputeUnconfirmed、ErrCommandUnconfirmed,以及仅用于 Resume 的 ErrCheckpointUnusable 保持其定义含义。未分类原生或 transport error 表示未知,不授权重试 mutation。Core 不将提供商 diagnostics 读作生命周期事实,也不暴露原生错误文本或凭据;node transport 将错误映射为固定 code,直接 SDK 细节保持私有。

Checkpoint 支持增加 Compute generation、name、ID 和 SnapshotIdentity;原样持久化 operation ID 与提供商 snapshot provenance。suspend 或 resume 的 ObserveOnly 仅观察上次尝试,不启动另一 capture 或 restore。ResumeCompute 仅解冻保留源,不冷启动已停止源。RenewCompute 从不复活已停止的 compute;运行中 allocation 的 Runtime 保持连接时,Core 调用它而不是 GetCompute,因为 Renew 只寻址初始 incarnation。清理针对精确 compute incarnation 和 snapshot,不针对当前同名实例。只有所属节点已验证精确 incarnation 不再存在时,GetCompute 才返回 ErrNotFound;同名但 native ID 不同的实例为 ErrOwnership,节点或提供商不可达属于未知结果。ComputeState.Status 为 stopped 或 crashed 表示 adapter 已验证该精确 incarnation 的进程不再存在;其记录或磁盘可保留到 KillCompute 将其移除。paused、没有 Runtime 连接的 running 和未知状态均不证明进程已终止。声明 checkpoint 支持前阅读 runtime_compute.go 及其失败测试。

四个独立就绪事实 ​

事实证据不证明
计算资源可用提供商对所属 allocation 的观测已认证 Runtime 连接或已准备能力
Runtime 已连接Gateway 认证和精确 Environment、device 绑定preparation 已完成或 Harness 可用
能力已准备使用固定配置完成公共 Runtime preparationTurn 已接受或完成
执行已准入已验证 Harness 能力及 executor、Turn 接受路径输入已完成、取消已完成或计算资源已回收

托管和自托管 Environment 使用相同 Runtime preparation;提供商不实现另一套竞争流程。

注册提供商 kind ​

sandbox/providers/registry.go 是唯一注册表。每项绑定 adapter 的 sandbox.ConfigurationAdapter、部署模式(nodes 或 direct)、sandbox.DeploymentPolicy(磁盘限制、可选的外部工作区要求,以及 setup 推荐的默认大小;ValidatePolicy(kind, Policy) 据此校验每个 specification 和 resource)、operation 声明,以及 node-local(BuildLocal)或 direct(BuildDirect)constructor。providers.Build 和 providers.BuildDirect 构造 adapter,不分配计算资源。没有 init 时注册或 plugin 加载。

新提供商执行以下步骤:

  1. 在 adapter 包中实现 operation 契约,并编写原生契约测试。
  2. 声明 sandbox.DeploymentPolicy。adapter 不再编写 specification 或 resource validator。
  3. 基于类型化原生配置实现 sandbox.ConfigurationAdapter。DecodeInput 严格解析请求中独立的公开 configuration 与只写 credential 对象。Encode 生成白名单公开 selector、只读观测和独立 secret bytes,不透传请求 JSON。Decode 恢复已存储 selector 并保留对所属资源的访问,不做远程 admission 或新模板验证。Normalize 修改前复制输入。ResolveChange、Equal 和 WithCredential 负责继承、身份与凭据组合。Requirements 声明是否需要凭据和公开 Core origin,以及支持哪些 setup 操作:Discovery 对应 DiscoverConfiguration,SelectionDiscovery 对应 DiscoverSelection,CredentialVerification 对应 VerifyCredential。DiscoverConfiguration 接收 ConfigurationDiscoveryQuery{Field, Path},其中 Field 是已声明的 Discovered 字段,Path 是前几级已选择的值,并返回 ConfigurationOptions:由 {Value, Label, Resources, Complete} 组成的列表,Complete 表示该选项可保存为字段值,其余选项通向下一级。它验证 query 并返回安全 catalog,不做 mutation 或 admission decision;Core 保留授权、输入限制与 deadline。DiscoverSelection 在提交前解析候选项省略的原生值,VerifyCredential 验证凭据对所属资源的访问,不修改资源。两者都接收候选项的 sandbox.DirectConfig,原生 client 只为该次调用构造。node 提供商仅接受空公开对象,拒绝凭据,对每项 setup 操作和 credential replacement 返回 Unsupported。
  4. node adapter 从自己的包中导出 BuildLocal constructor、它解码的类型化 native 对象,以及它在共享 node artifact 之外添加的原生文件。node-local 设置(如主机路径)只存放在该对象中;resources 从 node 配置的 specification 读取,Runtime 镜像来自同一对象。
  5. 在 providers/registry.go 中注册 constructor、policy、configuration adapter 和 operation 声明。其键即提供商 kind,也用于标记该提供商的观测;checkpoint 支持读取此项。生成的投影见规范节点规格。
  6. 提供 adapter 和 helper 的发行产物,通过已注册 configuration 契约把该提供商交付给运维人员。
  7. 在 Policy() 旁声明 setup 向导的内容:编写 sandbox.SetupDeclaration,并注册为条目的 Setup。它包含中英文的标签、摘要和注意事项,该提供商是否为其模式的 Recommended 选择,公开配置字段和凭据字段(Name、本地化的 Label、Secret、Discovered、Optional、Help),以及填充字段值并链接凭据控制台的 preset。注册会拒绝:凭据非必需却声明了 secret 字段、不支持 Discovery 却声明了 discovered 字段、空的语言文本和指向未知字段的 preset 值。生成部署契约时会拒绝同一模式下多于一个 Recommended 提供商。

node 配置 sandbox.NodeConfig 包含 provider、generation、installation_id、core_url、specification,以及 adapter 的不透明 native 对象。providers.Build 验证 provider、generation、installation_id 和 specification,并将配置与临时 sandbox.LocalOptions 传给 BuildLocal,由它严格解码 native。调用方通过 Standalone 明确选择独立注册或单提供商执行,或通过 GenerationStateDirectory 中的规范绝对 node state directory 选择 generation 拥有的执行。context 缺失或混合时拒绝。adapter 负责 generation 特有的原生 preparation 和 readiness 检查。Microsandbox 将 helper lease 绑定到安装实例、generation 和 specification digest,然后在平台、容量和 artifact readiness 后检查固定 image。

注册验证 ​

providers.ValidateRegistration 是唯一 wiring 检查。lookup、constructor binding 和生成的投影在任何 configuration callback 或 constructor 前运行它。未知提供商名称 保持为无效输入;格式错误的注册返回安全 providercontract.ErrContract,不包含提交的配置或原生诊断。

  • nodes 注册仅有 BuildLocal,direct 注册仅有 BuildDirect;缺失、混合或未知 mode 被拒绝。
  • configuration adapter 与完整 operation 声明都是必需项,因此不完整注册不能发布部分投影。声明的默认大小必须通过 ValidatePolicy("", Policy)。
  • Checkpoint 对两种模式都准入:公共 lifecycle 对 direct allocation 的暂停、保留、恢复和清理与 node allocation 完全一致,只是没有 node。注册不携带 suspension 数值:Core 对每个声明 checkpoint 支持的提供商应用同一个 suspension policy。

configuration adapter 必须非 nil,包括其具体值。每个 ConfigurationRequirements 字段都需要明确有效的决定:Credential 和 PublicOrigin 为 Required 或 NotRequired,Discovery、SelectionDiscovery 和 CredentialVerification 使用共享 supported 或 unsupported 声明并携带安全 reason。新增 requirement field 需要明确更新验证,不继承已有决定。要求凭据不承诺支持 VerifyCredential 操作。这些检查证明注册完整,不证明原生 SDK 行为正确;constructor 和 adapter 契约测试仍然适用。

配置存储与构造 ​

预览和持久化使用 providers.Normalize 与 providers.Describe。providers.DiscoverSelection 在提交前解析省略的原生值,持久化时再次验证完整 specification。providers.ResolveChange 负责配置继承,比较使用 normalized selector,使预览、重试和提交共享默认值。store 负责事务、凭据加密、generation fencing、资源所有权和通用对象存储:仅 adapter 解释 provider_config 与 provider_metadata,provider_credential 保存绑定到安装实例与 generation 的密文。保留 generation 保持原公开配置和 metadata,通过 adapter 组合当前凭据,因此替换凭据不重写保留 selector。数据库约束检查对象结构,不检查注册列表。

具有凭据的 direct adapter 在替换 key 前验证全部保留 generation 与 allocation reference。公共 sandbox.CallFence 排除原生调用并等待 helper 完成,包括调用方已超时的调用;execution 调用已准备的 verification 和 fencing callback,不按厂商分支。

厂商部署验证和 SDK setup 留在构造边界,构造不创建 Environment。node-local adapter 的 sandbox.Built 返回提供商、probe、installation identity、backend fingerprint 和 specification digest;helper 可能比调用方存活更久时,还返回 Quiescent 检查,generation 回收会等待它。factory 还返回 close 函数。execution.RuntimeProvider 将 adapter 绑定到 kind、installation ID、backend fingerprint、generation、mode 和 node ownership;选择由数据库负责,内存副本不构成另一权限来源。microsandbox 在 node 上运行,E2B 和 OpenSandbox 直接构造。node proxy 仅对注册声明支持 checkpoint 的 backend 暴露 checkpoint 操作,公共 lifecycle 通过 checkpoint 声明准入 suspension,不通过提供商名称。

backend fingerprint 标识原生资源命名空间,不表示容量。Core 保留部署 generation,使所属 allocation 继续解析到原 backend;不要将保留 allocation 重新指向替代 backend。

发行产物与进程路径 ​

每个 node adapter 注册负责其类型化 NodeArtifacts 声明,即共享 node artifact 加上其包导出的原生文件:逻辑发行路径、release filename suffix 和安装角色(node、runtime 或 image)。注册拒绝缺失声明、不安全路径和未知角色。go run ./services/core/cmd/provider-artifacts -write 生成共享 Web catalog 和 Python projection。不带 -write 运行可检查是否最新。发行打包、Web availability 和 node 安装读取此投影;添加提供商 payload 不在这些消费者中增加按提供商名称的分支。

launcher 从派生进程环境提供 sandbox.ProcessPaths。Core 读取这些路径一次,并传给 direct construction 和 setup 操作。它们是固定发行属性,不是部署设置或用户可选 helper 路径。每个 adapter 解析自己的相对 helper 和 state 位置;E2B 使用 e2b/oac-e2b-provider 和 e2b/。root 缺失或不是绝对路径时,在执行 helper 前失败。提供商构造与发现不读取进程环境变量。

Core 对提供商的保证 ​

adapter 不实现这些行为,但依赖它们。代码层面的机制见 Core implementation constraints。

  • Core 在调用 Create 之前提交 allocation、其 daemon 凭据摘要和 Session 绑定。只有新的 allocation receipt 才允许 Create;重试和 Core 重启只观察同一个 Reference,不重放 Create,也不轮换凭据。
  • 每个 node 有一个串行 lifecycle worker,同一 node 的调用从不并发;direct 提供商的 allocation 共用一个 worker。某个 node 上卡住的提供商不会阻塞其他 node。
  • Core 从不根据引擎或提供商名称推断引导完成;由 adapter 通过 Info.BootstrapComplete 声明。
  • Core 只在撤销 device 权限、结清待处理 input 并请求取消之后才调用 Kill。临时提供商故障、未知的 Create 结果和已停止的计算资源都不证明永久失败。超时与限制中的启动期限限定了等待从未进入运行状态的计算资源的时间:它结束该 Environment,但并不声明 Create 已失败。
  • Core 只有在确认清理 allocation 的计算资源与 volume,并证明原始 Create 已结算后才释放 allocation。在此之前它保留清理归属,包括观察到资源不存在之后,有界扫描继续捕获迟到的资源,不再次 Create。公开删除 Session 之后同样适用。
  • Core 从不在离线 node、超时或空读取时释放 allocation,也不对不在线的 node 执行 lifecycle 操作。保留的归属需要精确的提供商证据:socket 路径、实例缺失或空列表都不证明已清理,也不授权替代。
  • Placement 是自动的,调用方不能选择 node。活动 allocation 即使离线也保留原 node。确认释放后,符合条件的保留 Session 可以再次预约兼容容量,包括在其他 node 上。释放 active 容量前必须确认 source 已拆除,未知操作保留其预约。等待、排序和 generation 选择由部署契约负责。
  • 挂载了 Session 时,Core 在 Turn 之间观察已连接的计算资源仍是该 Environment 的 running allocation。该检查不改变任何状态。运行中的计算资源从不到期,没有确认的不可达、已停止或缺失实例不授权丢弃保留的工作区或历史,也不授权选择替代计算资源。
  • Core 在一个暂停策略下,暂停每个声明 checkpoint 支持的提供商的空闲 allocation。空闲超时对每个提供商是同一个设置;不支持 checkpoint 时它的作用见独立 Environment。
  • 禁用提供商会停止新的托管准入和引导,但从不阻塞既有 Session 的取消、函数结果或 input 重试结果。
stateDiagram-v2
    [*] --> creating: allocation committed before Create
    creating --> running: matching running compute with completed bootstrap
    creating --> cleanup_pending: cleanup requested
    running --> cleanup_pending: cleanup requested
    cleanup_pending --> released: cleanup confirmed and Create settled
    released --> [*]

当 Session 被删除或归档、Environment 失败或到期,或管理员重置部署时,allocation 进入 cleanup_pending。released 要求 CreateSettled;参见身份与资源所有权。

网络出站 ​

Provider 声明 DeploymentPolicy.Network:Restrict 表示能拒绝公开地址并允许具名公开域名,Core 仅在此时准入 disabled 和 restricted Environment;PrivateDomains 表示能允许具名主机解析出的私有地址。保存选择时,Core 会依据该声明校验部署的网络上限,绝不替换为其他行为。

Core 在 Bootstrap 和每个 ResumeRequest 中发送同一个 Egress,它由分配所属的部署代次和 Environment 冻结的 network 策略,以及(对 Session 拥有的 Environment)其 Session 的模型提供商推导而来。disabled 只留下 Endpoints;restricted 清除 Public,上限列出的域名放入 PrivateDomains,其余放入 Domains(策略):

  • Public:允许公开地址。
  • PrivateDomains:精确主机名,或 *.example.com(覆盖其子域名,不含 example.com 本身),其解析出的地址(包括私有地址)都被允许。
  • Domains:只在公开地址上被允许的精确主机名,私有应答仍被阻止。上限允许公网时,它们承载 restricted Environment 的 allowed_domains。
  • Endpoints:模型提供商 base_url 的 host:port 条目(net.JoinHostPort 形式),端口取自 URL,https 默认 443,http 默认 80,主机为回环时省略。Harness 运行在沙箱内,直接调用它。条目只允许该 TCP 端口在公开地址上的访问,绝不包括私有地址。上限的额外域名列出了模型主机名或覆盖它的 *. 条目时,Core 还会把该名称加入 PrivateDomains,使私有模型主机在任何策略下都能工作。

Provider 在始终允许到 Core 的连接之上严格执行这些内容,并阻止回环、链路本地、云元数据以及 Egress 未列出的所有私有地址,但 E2B 无法阻止元数据地址 169.254.169.254。它在创建和恢复时用主机 DNS 解析 Core 主机。MCP 流量没有条目:它遵循 Public、PrivateDomains 和 Domains。

microsandbox 按首条匹配的顺序和默认拒绝来应用规则,创建与恢复相同,并关闭严格主机名校验和 DNS rebind 保护。沙箱只能访问主机的 DNS 服务器:发往其他服务器的 DNS 和主机的其他端口都被拒绝,因此只有主机的应答能把名称绑定到地址。该服务器不论策略都会应答任何名称,因此被拒绝的名称仍能解析,只是连接会失败。名称成为不带端口的域名放行规则,放行这些应答解析出的地址(包括私有地址);*.example.com 条目成为子域名放行规则,永远不匹配 example.com。E2B 只声明 Restrict:Public 时加入回环、私有和链路本地网段的拒绝列表,非 Public 时拒绝除 Core 主机、Endpoints 和 Domains 之外的全部 IPv4 和 IPv6 流量。E2B 只在 80 和 443 端口匹配主机名,因此 adapter 还会为 Core 主机和每个 Endpoint 在其他端口上允许其全球 IPv4 地址。IP 字面量只作为单地址的全球地址范围被允许,私有字面量没有规则。

OpenSandbox 同样只声明 Restrict,并要求其出口 sidecar 以 dns+nft 模式运行(OpenSandbox egress),其拒绝规则优先于所有放行规则,而域名规则会放行其应答解析出的地址的所有端口。因此每个沙箱都拒绝私有、共享和链路本地网段,adapter 无法遵守 PrivateDomains。当 Core 主机由其主机解析出的地址不全在全局网段时,Create 在派发前返回 ErrInvalid:私有网段的拒绝规则优先于对它的任何放行。Public 时其余流量默认放行。非 Public 时默认拒绝,并放行 Core 主机、Endpoints 和 Domains:名称作为域名规则,全局 IP 字面量在其端口上放行。回环保持开放,因为在沙箱内部它就是沙箱自己的网络命名空间。

检查点生命周期 ​

声明了 checkpoint 操作(Initial、NewCompute、GetCompute、RenewCompute、Suspend、Resume、ResumeCompute、KillCompute、DeleteSnapshot、RunCommandCompute)的提供商,使 Core 能把空闲 allocation 暂停为快照,并在同一或另一个兼容 node 上恢复。Core 记录 allocation 的 compute_phase;未声明 checkpoint 支持的提供商为 disabled,其余阶段按下图变化。删除、归档、重置和保留期到期会在完成Core 对提供商的保证中描述的清理后,从任意阶段释放 allocation。

stateDiagram-v2
    [*] --> disabled: allocation created
    disabled --> running: checkpoint Provider, compute running and bootstrapped
    running --> quiescing: idle
    quiescing --> suspending: daemon quiesced
    quiescing --> running: daemon rejected quiesce
    quiescing --> waking: new work or lost acknowledgement
    suspending --> suspended: Suspend reports SourceStopped
    suspending --> waking: capture cancelled or source still running
    suspended --> restoring: new work or file access
    restoring --> waking: Resume reports running
    waking --> running: daemon resumed
    running --> [*]: confirmed compute loss releases the allocation
    suspended --> [*]: cold replacement after retention

暂停与唤醒流程按下列顺序调用提供商。Core 在每个效果发生之前先持久化相应阶段。

sequenceDiagram
    participant C as Core
    participant R as Runtime
    participant P as Provider
    Note over C: idle, phase running
    C->>C: persist quiescing
    C->>R: environment_quiesce
    R-->>C: environment_quiesced
    C->>C: persist suspending
    C->>P: Suspend(OperationID, Source)
    P-->>C: Snapshot, SourceStopped
    C->>C: persist suspended
    Note over C: new work or live file access
    C->>C: persist restoring, reserve destination
    C->>P: NewCompute, then Resume(Snapshot, Target)
    P-->>C: running Compute
    C->>C: persist waking
    C->>P: RunCommandCompute wakes a parked daemon
    C->>R: environment_resume
    R-->>C: environment_resumed
    C->>P: DeleteSnapshot
    C->>C: persist running

暂停 ​

Core 在初始化完成、没有 root 或 Subagent Turn 处于排队、进行中或等待状态、没有待处理的 input 或文件操作,并且真实活动已空闲达到策略的空闲超时之后暂停 allocation。Session 不必运行过 Turn。存在兼容的等待需求时,容量压力可以在超时与限制所列的无活动宽限期之后,提前暂停已经空闲的 node allocation。没有空闲 active slot、但有空闲 retained slot 的 node 还会保留一个空闲 active slot:达到超时与限制所列的空闲 slot 无活动时间后,即使没有等待需求,Core 也可以暂停空闲的 allocation,让下一个 Session 不必等待暂停。如果已放置到该 node 的 Session 还在等待创建沙箱或完成初始化,则不会这样做,否则 node 要等这次暂停完成后才会为那个 Session 创建沙箱和执行准备。它从不打断活动 Turn,也不会在常规 quiesce、capture 和 source-stop 证明完成之前释放容量。如果暂停无法让容量可用,等待中的请求保留原有期限。retained slot 已满时,容量压力可以释放空闲检查点,并且只暂停其检查点随后可被释放的 allocation。

提供商依赖以下规则:

  • Core 在效果发生之前持久化 quiesce、capture 和 restore 意图,只有新的 receipt 才执行 capture 或 restore。恢复流程用 ObserveOnly 观察精确的 attempt,从不重试结果未知的创建、capture 或 restore。
  • 确认计划暂停之前,daemon 关闭准入,并排空原生 cleanup、输出 receipt 和文件工作。quiesce 确认丢失时可以通过 ResumeCompute 解冻同一 source,但不授权 capture。
  • 排队工作和实时 Environment file access 唤醒 suspended Environment;history 和已发布 Artifact read 不唤醒。通过 RunCommandCompute 发送、受 PID 与 start-time fencing 的本地 control signal 唤醒 parked daemon,daemon 在准入工作前重新认证。
  • 保留的检查点在原 node 仍具资格时优先恢复,也可以按检查点转移在其他符合条件的 node 恢复。Core 负责 snapshot retention deadline,daemon 没有相应 timer。
  • 已消费的 snapshot 从不让运行中的 generation 回滚。已消费的 artifact 和旧计算资源会被删除,因此多次暂停不会形成可写磁盘链。
  • 删除、撤销和保留期到期优先于唤醒,直到最后的数据库 compare-and-swap。未知的清理身份一直保留,直到确认所属资源已不存在。

检查点转移 ​

支持检查点的 generation 报告 CheckpointCompatibility,包含不透明的 ArtifactDomain 与 ExecutionClass token。每个已验证 SnapshotIdentity 携带同样的资格。它还携带最长 4096 字节的不透明 Evidence,只有提供商解释它;Core 与 node 代理原样存储并返回。Core 只比较这些值,不解释 CPU 特性、文件系统路径或存储实现。恢复目标必须在线、对 allocation 的不可变 deployment generation 已就绪、两个 token 均匹配,并有 active 容量;跨 node 时还需 retained slot。allocation、Device 和 Session 身份保持不变。Session 与 deployment 事务先提交目标路由、placement 和精确 restore intent,再执行目标侧原生操作。没有容量或兼容目标时,保留快照的所有权一直持续到配置期限。目标必须已持有该精确 generation;Core 不会在新节点自动准备历史 generation。节点会保留被取代的 generation 的提供商,直到检查点保留义务结束。

Suspend 只有在持久发布已验证的完整检查点、停止精确 source compute,并结清 source 本地 capture 与 cleanup 义务后,才能报告 SourceStopped。Core 先持久化快照,再标记 suspended;仅原生资源不存在并不足够。Suspend.ObserveOnly 可以为同一 operation 已验证的快照完成检查点发布和源清理,但不能重新捕获快照,也不能停止已经恢复 running 的源。此前已发布的检查点缺失或损坏时,ObserveOnly 可以返回其精确持久 ownership receipt,标记 Status: unknown 和 SourceStopped: false,供清理使用;该 receipt 不证明检查点当前可用,也不证明源不存在。Resume 仍在执行前验证检查点。完成源结清屏障后,source node 不可用不再阻止恢复。删除和正常到期可以将空闲 suspended allocation 的清理路由转给同一 artifact domain 内的在线 node;删除不要求 execution class 匹配。清理目标必须已提供同一不可变 generation,且有 retained 容量。没有这样的 node 时,清理保持 pending,不释放所有权;运维需恢复符合条件的 node 或其容量。未知 running 或 restoring writer 不会仅因 node 不可达而迁移。

恢复用 Resume.ObserveOnly 观察已持久化的 target 与 operation。RestoreAttemptClosed 是精确 operation ID,不是通用 absence 标志:adapter 只有在持久关闭从未进入原生执行的 attempt,并隔离该 ID 的所有迟到请求后才能返回。如果 adapter 能证明当前调用在派发原生恢复之前失败,也可以关闭已持久 admitted 的 attempt。wire deadline 到期或未分类失败会关闭该 attempt,Core 随后持久化新的 operation ID。快照缺失、未通过身份或完整性校验,或未通过 adapter 对当前 generation 的资格检查(例如资源、workspace 或 runtime image 不匹配)时,也会关闭该 attempt,并报告为 ErrCheckpointUnusable。该结果是持久的:同一 operation 的 Resume.ObserveOnly 会再次报告它,该 operation ID 的迟到请求仍被隔离。一旦已派发原生恢复,提供商不会返回它。收到 ErrCheckpointUnusable 后,Core 不再恢复该快照,并立即结束其保留。一旦已派发原生恢复,结果未知的 attempt 保留相同 target、所有权与原始 retention deadline;原生列表缺失、helper 死亡或超时都不授权重放。这种恢复可能一直不可用,直到显式删除或正常保留期到期;等待中的 input 可能达到其公共 deadline。用户删除仍需精确原生 settlement,之后才能释放资源与所有权。

E2B adapter 的 checkpoint 行为见 E2B provider 指南。E2B 没有独立的 workspace 文件系统,因此保留期到期走下面的未满足条件分支。

私有 checkpoint_root 见 microsandbox provider 指南。每个保留的检查点都是 guest 内存与根磁盘层的未压缩原生快照,因此共享 store 要为每次挂起和跨 node 恢复承载这部分数据量。恢复 RAM 与文件描述符不保证外部 TCP 连接连续,也不保证应用副作用可安全重放。

检查点保留期后的冷替换 ​

快照保留期限制计算资源,不限制符合条件的保留 Session 的生命周期。到期后,只有独立文件系统对象已就绪、初始化已完成、Session 与 Environment 均未终结,且此前已认证 Runtime 的 retained_native_history 声明已持久化时,Core 才能在不终结 Session 的情况下清理 allocation。能力及原生恢复义务由 Core–Runtime 协议定义。仅保留文件系统并不足够。

不可用的检查点(恢复中的 allocation 的 Resume 报告 ErrCheckpointUnusable)会立即结束保留,如同其 deadline 已到。Core 通过正常的到期清理删除 target 与快照;符合条件的 Session 按下文继续,不符合条件的则如正常到期一样结束。

仅当等待中的放置需求被节点已满的 retained slot 阻塞时,容量压力才会提前结束保留期,且只针对该节点上最早挂起、空闲,并满足上述条件或属于未挂载 Session 的独立 Environment 的 allocation。Core 将其视为已过期,每个被阻塞的需求只释放一个;其他已挂起的 allocation 在配置的期限到达前保留快照并继续占用 retained slot。恢复时缺少容量或兼容节点的检查点不会因此被冷替换。等待请求保持原有的输入期限。常规 expiry cleanup 必须确认资源已删除,其他 allocation 才能预留该 slot;已验证的 Session 保留文件与原生历史,未挂载的 Environment 则像到期时一样过期。

Core 在释放 allocation 和 placement 归属前,确认原始创建已结算且所属计算资源与快照均已清理。替代计算资源准入前撤销旧 device 的权限。Create、Kill 或 DeleteSnapshot 的结果尚未确认时,Core 保留归属,不准入替代写入方。可恢复的 Session 与 Environment 保持断连,保留同一文件系统对象和初始化结果。归档、重置和删除优先,唤醒请求不能撤销它们。

新 input 或实时 Environment 文件访问会在兼容 node 上预约新 allocation,并引导新的 Runtime device。准备流程复用同一文件系统和已完成的初始化,不重放初始化。验证替代 Runtime 的声明后,执行从保留历史续接同一原生 Session。原生历史缺失或无效时明确失败;Core 不替换为新的原生 Session,也不重放已完成的 input。读取历史和已发布 Artifact 不预约计算资源。此路径不保留 VM 内存、后台进程或开放连接,也不为未声明能力的 Runtime、Harness 或文件系统组合提供资格。它同样不提供 node 级 drain、从不可达写入方 failover、并发写入方、多活 Core、自动扩缩容或快照复制。

已确认的计算资源丢失 ​

正在运行的计算资源没有保留期限,因此主机崩溃或重启后,其 allocation 原本会无限期保持归属。所属节点重新上线后,对于计算阶段为 running 且支持检查点的 allocation,只有同时满足以下条件时,GetCompute 对已持久化的精确 incarnation 返回 ErrNotFound 或已验证的 stopped、crashed 状态才会释放该 allocation:原始创建已结算,该 incarnation 有 native ID,未记录 capture、restore 或 rollback 意图,allocation 的 device 没有已认证的 Runtime 连接,且 Session 满足冷替换条件。随后 Core 对该精确 incarnation 调用 KillCompute。只有其结果得到确认,才允许一次持有 Session 锁的提交:重新检查计算 revision 与上述条件,撤销 device,并释放 allocation 和 placement。Session、Environment、等待中的 input、原生 Session 身份和文件系统均保留,新 input 或实时文件访问按冷替换续接。

其他观察结果均保留归属及其诊断:paused、running 或未知原生状态、身份不匹配、超时或传输错误、未知创建、已记录的 restore、存在 Runtime 实时连接、自带工作区存储、初始化未完成、Session 已终结,或缺少 retained_native_history 声明。KillCompute 失败时不做任何修改,并发的归档、删除或计算阶段变更优先。节点离线时 Core 从不执行此操作,因为没有节点就无权停止计算资源。续接保留文件系统并使用已记录的原生 Session ID;Harness 恢复出错时执行失败,不创建另一个原生 Session。Core 不重放已中断或已完成的输入。OpenAI 兼容性记录已通过资格验证的续接场景,包括完成确认后立即崩溃。任意崩溃受损原生历史的完整性仍未通过资格验证;身份检查无法检测已截断但仍可解析的历史尾部。

超时与限制 ​

值适用于到期或超出时
有界 context每个提供商调用结束调用方的等待,不证明已回滚、停止、清理或不存在。adapter 从不分离未跟踪的 mutation,也不重放已超时的命令
空闲超时每个 allocation,由 idle_seconds 设定支持检查点时 Core 开始暂停;不支持时见独立 Environment
快照保留期支持检查点的 allocation,由暂停策略设定保留期结束时 Core 清理快照,并对符合条件的 Session 通过冷替换替换计算资源
15 s空闲 node allocation 在容量压力暂停之前的无活动时间存在兼容的等待需求时,Core 可以早于空闲超时暂停它
2 min所在 node 没有空闲 active slot 但有空闲 retained slot 时,空闲 allocation 的无活动时间Core 可以早于空闲超时、在没有等待需求时暂停它,让下一个 Session 找到空闲 slot
10 min从 allocation 创建到 Core 观测到其计算运行且引导完成的时间Core 使 Environment 失败,然后像任何清理一样调用 Kill 并释放 allocation。未结算的 Create 在结算之前保留清理归属
50 MiB 加 32 字节(MaxCommandInputBytes)Command.Stdin命令无效

在线窗口和其他节点计时器见沙箱节点协议。

一致性测试 ​

Go adapter 的 E2B 模板和 endpoint validator 消费共享 selector fixture。任何验证修改都扩展这些 case。

开发时运行 make check-sandbox-provider-contract。它通过真实 adapter 边界和受控原生失败运行共享 contracttest 套件,以及 adapter 和 node transport 测试;make check 包含相同 package。使用 native-side fixture 调用公开 failure runner,不使用假的 SandboxProvider,保留外来 ownership、未知 mutation result、cancellation、不自动 replay、failed cleanup 和 reference-bound settlement 测试。

node 测试单独覆盖 disconnect、reconnect fencing,以及 Create response 丢失后的 cleanup。helper protocol 和 sandbox node 协议要求精确版本匹配;直接进程内接口没有独立 wire version。

原生验收证明 fixture 无法证明的事实:creation、lease 行为、所属 partial cleanup、声明的 isolation 与 limit,以及支持时的 snapshot。SDK helper 使用 make check-e2b-provider 和 make check-microsandbox-provider。mock compute 不能证明 reclamation 或 isolation。

参考 adapter ​

KindAdapterHelper 与 adapter 规则运维指南
microsandbox (node)sandbox/microsandboxtools/microsandbox-providerNode
E2B (direct)sandbox/e2btools/e2b-provider沙箱部署;应用管理的模板见 deploy/e2b
OpenSandbox (direct)sandbox/opensandboxdeploy/opensandbox选择沙箱提供商

基于 MIT 许可证发布。© 2026 MiniMax-AI