Skip to content

Runtime 引导

Runtime 引导协议连接沙箱提供商与其启动的托管 Runtime。提供商向 Runtime 交付一个引导文件,该文件是此次启动中 Runtime 唯一的认证输入,也是其 Environment 绑定的唯一来源。

属性内容
调用方沙箱提供商。Go 提供商使用 runtime_bootstrap.go 中的 sandbox.Bootstrap.RuntimeConnection() 构造输入;SDK helper 原样转发序列化对象。
实现方Runtime,以及参考实现中列出的提供商
代码internal/runtimebootstrap:类型与验证器
传输一个 JSON 文件,其绝对路径传给 oac-daemon connect --bootstrap-file
版本规则精确的 version(启动输入)

职责与就绪状态 ​

参与方拥有绝不
沙箱提供商账户、挂载和工作区;交付该文件;Runtime 的资源与 Environment 绑定配置;以无特权 Runtime 账户启动 daemon读取或写入 Runtime 的私有认证存储
Runtime验证输入、认证和连接为同一次启动接受第二个认证来源

启动成功仅证明交付完成:经过认证的连接、已准备的能力和执行就绪是 Core–Runtime 协议 下的独立观测;沙箱提供商协议 列出各自证明的事实。

自托管执行器和运维人员供应的设备通过其他方式获取 daemon 身份,其 Environment 绑定来自注册以及 oac-daemon connect --workspace 或原生安装;机器连接 API 列出所有凭据来源。它们都进入同一 Runtime 执行循环。

启动顺序 ​

sequenceDiagram
    participant P as Sandbox Provider
    participant R as Runtime daemon
    participant C as Core
    Note over P: Write the bootstrap file
    P->>R: start oac-daemon connect --bootstrap-file PATH
    Note over R: Validate the file, read the credential into memory
    R->>C: Connect over the Core-Runtime protocol

启动输入 ​

将一个 JSON 对象交付到普通文件中,该文件仅允许 Runtime 账户和可信资源供应进程读取(托管 Linux 上权限为 0600),并传入其绝对路径:

sh
oac-daemon connect --bootstrap-file /home/runtime/runtime-bootstrap.json
字段含义
version精确的引导版本 runtimebootstrap.Version
core_url以 /api/v1 结尾的 HTTP(S) 机器 API 基址,不含凭据、查询或片段
device_idCore 签发的 daemon 身份的规范非零 UUID
credentialCore 签发的非空 daemon 凭据,不含空白或 NUL
environment_idRuntime 所服务 Environment 的规范非零 UUID
workspace工作区的干净绝对目录;打包的 Runtime 布局中为 runtimebootstrap.RuntimeWorkspace。Runtime 将其作为 runtimebootstrap.PublicWorkspace(/workspace)提供,这是应用与 Core 使用的路径
suspend_control必填布尔值。当且仅当提供商声明检查点支持时,Core 将其置为 true,提供商原样转交

解码器拒绝未知、重复、缺失和大小写别名字段,拒绝其他版本及超过 runtimebootstrap.MaxBytes的文档。错误不包含提交的值。文件缺失或格式错误时,daemon 在连接前失败。

该文件是此次启动唯一的认证输入:daemon 拒绝将其与自托管注册选项组合使用,并将凭据读入内存而不保存到存储的 profile。凭据不进入命令参数、环境变量或回执。提供商为进程重启保留该文件,仅在明确清理自己拥有的资源时删除。

挂起控制 ​

suspend_control 为 true 时,daemon 在 runtimebootstrap.SuspendControlFile 发布其挂起控制并为挂起而停放。Core 的唤醒命令 oac-daemon resume --control-file 读取该文件。声明检查点支持的提供商在启动 daemon 前准备该文件所在目录:仅 Runtime 账户可访问(权限 0700,属主 UID 1000)。suspend_control 为 true 而 oac-daemon connect 无法发布该控制时,连接失败;没有任何其他设置可以启用该控制。

超时与限制 ​

数值适用对象超出时
16 KiB(runtimebootstrap.MaxBytes)引导文档解码器拒绝该文档,daemon 在连接前失败。

参考实现 ​

提供商交付方式
microsandbox、E2B在启动同一命令之前交付文件。
OpenSandbox通过 execd 上传文件,然后启动同一命令。

验证 ​

go test ./internal/runtimebootstrap ./apps/daemon/internal/cli 覆盖输入契约、凭据来源互斥规则和重启行为。提供商测试验证交付与文件权限,不依赖 Runtime 的私有存储。

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