OpenSandbox 1.1.1：学习路线

这门课的目标：不是背 OpenSandbox 的 API，也不是通读每一行源码，而是建立一套能迁移到任何 AI 执行平台的完整心智模型——知道不可信代码为什么需要隔离、环境如何被安排和回收、命令如何变成可验证的证据、网络和密钥如何被约束。

适合谁：会一点 Python、能在命令行运行项目，了解 Docker 基本概念，但还没有系统理解 AI 执行基础设施的读者。

源码目录：$OSB_SRC，固定在 release-1.1.1（531700ca）。总览：先读整体架构，把本清单当路线图，再按阶段读详解。

一、先建立总图：OpenSandbox 到底是什么

一句话：OpenSandbox 是 AI 应用与不可信执行之间的基础设施层。 它不替你做 Agent 编排，而是负责把“模型想做的动作”放进一个有边界、有期限、可观测的环境里执行。

模型决定做一个动作
   │
   ▼
应用 / Agent
   │  管理请求
   ▼
生命周期控制面：认证、状态机、TTL、端点解析
   │  选择运行时
   ▼
运行时：Docker / Kubernetes / FastSandbox
   │  创建
   ▼
沙箱：用户负载 + execd
   │  执行请求（绕过控制面）
   ▼
命令 / 文件 / 代码 / 终端
   │  出站
   ▼
egress sidecar → 外部服务

旁边还有一条持续产生的证据流：状态、SSE 事件、退出码、日志、指标和审计。它决定你是否真的成功。

AI 执行平台的八个功能块

任何 AI 执行平台都可以拆成八块。学习 OpenSandbox，就是看这八块如何互相配合：

功能块	要回答的问题	OpenSandbox 中的主要位置	对应阶段
入口	谁通过什么使用平台？	SDK、CLI、MCP	6
契约	客户端与后端靠什么解耦？	`specs/`	1、6
生命周期	环境何时创建、续期、销毁？	`server/`	2
运行时	资源实际落在哪里？	Docker、Kubernetes、FastSandbox	4
执行	模型动作怎样发生？	`components/execd/`	3
网络	流量怎样进出、怎样受限？	endpoint、ingress、egress	5
安全	不可信代码和密钥怎样被约束？	隔离运行时、策略、Credential Vault、租户	4、5、8
工程	怎样证明可靠、可观测、可演进？	测试、诊断、指标、发布	8

三条贯穿全系统的纵线

除了八块，还要一直带着这三个问题：

证据是怎么流动的？ 状态、SSE 事件、退出码、日志和指标，是判断“真的成功了没有”的唯一依据。
信任边界在哪里？ 用户、模型、工具、沙箱、宿主机、外部网络，各自能控制什么。
能力依赖哪些条件？ 看到“支持”时，追问：哪个后端、什么配置、什么版本、什么镜像。

二、整门课只围绕一条主线：一次沙箱任务的一生

后面每一章都在拆这条线中的一段：

模型决定执行一个动作
  → 应用发起创建请求
  → 控制面认证、校验、选择运行时
  → 运行时创建容器 / Pod / 微虚拟机
  → SDK 等待状态、解析端点、健康检查
  → 客户端直接调用 execd 执行命令或操作文件
  → 沙箱出站流量经过 egress 策略
  → 结果以 SSE / 文件 / 退出码回到应用
  → 续期、暂停、快照或销毁
  → 状态、日志、指标、审计留存

你需要能随时回答四个问题：

这次动作从哪里进来？ SDK、CLI、MCP，还是 Agent 框架？
环境在哪里？ 哪个运行时、哪个后端、当前状态是什么？
动作怎样执行？ 走哪个端点、用哪种身份、输出怎样回来？
系统何时真正结束？ 是 close()、kill()、TTL 到期，还是暂停成快照？

能沿着这条线解释每个部件，才算真正理解；只记住文件名不算。

三、怎么学：每章都走同一个五步循环

第 1 步：先用自己的话回答本章问题

比如阶段 3 的问题不是“execd 有哪些路由”，而是：

模型说“运行这段代码”之后，系统凭什么让应用相信它真的运行了、真的成功了？

先写下你的直觉答案，再去读材料。带着问题读，比从目录开始读有效得多。

第 2 步：画一张图

每一章至少产出一张图：请求流、生命周期状态机、执行时序、运行时链路、网络路径、工具循环。图不必漂亮，但必须能让你不看代码讲出关系。

第 3 步：到代码里验证

只追本章相关的路径，不要从仓库根目录开始通读。每个概念都要落到一个具体对象或函数：

生命周期：Sandbox.create、SandboxService、runtime.type、TTL
执行：commands.run、RunCommandOpts、execd /command、SSE
运行时：BatchSandbox、Pool、SandboxSnapshot、FastSandbox 路由
网络：networkPolicy、endpoint 解析、egress 策略、Credential Vault
接口：specs/、adapter、CLI 命令、MCP 工具
工程：测试、诊断、指标、发布验证

第 4 步：做一个小实验

每章都要有一个能跑或能验证的动作：创建并销毁一个沙箱、观察一次 Pending、跑一条流式命令、写一个带 TTL 的封装、画一张网络策略、读一个 adapter、写一个工具、做一次故障注入。

第 5 步：讲回来

合上文档，用 3–5 分钟讲给“三个月后的自己”听。讲不清的地方，就是下一轮要回去补的地方。

学习的敌人不是难，而是只读不验证、只记名词不建模型、只跟着步骤走却不问为什么。 这门课用“问题 → 图 → 代码 → 实验 → 复述”反复拆掉这三个坏习惯。

四、阶段路线：每一阶段只解决一个大问题

阶段 0 · 先让最小闭环真实跑起来【准备】

问题：源码版服务端、Docker、SDK 和第一个沙箱，能不能在本机完整工作？ 你要得到：能创建、执行、读输出、销毁；见过一次鉴权失败；知道服务端配置中的 runtime 和 API Key。产出：一次成功的最小脚本 + 一次故意失败的记录。 为什么先做：没有真实行为，后面的所有概念都会变成纸上谈兵。

阶段 1 · 系统地图：一次任务如何穿过平台【核心】

问题：OpenSandbox 有哪些层？谁把输入交给谁？为什么创建和执行是两条路径？ 你要得到：能用一张图讲清“使用层 → 控制面 → 运行时 → 数据面 → 网络面”，并标出证据回流。产出：架构图 + 创建时序图 + 执行时序图 + 一份失败点清单。 关键区别：生命周期服务器是控制面，execd 是数据面；端点解析是契约，不是猜地址。

阶段 2 · 生命周期：环境从生到死【核心】

问题：沙箱什么时候算真正可用？TTL 到期、进程崩溃、用户取消时，谁来回收远端资源？ 你要得到：能画出状态机；能解释异步创建、绝对 TTL、续期语义、暂停/恢复和快照边界。产出：一个在成功、异常、取消三条路径都能销毁远端资源的封装。 核心认识：生命周期管理的本质是所有权管理；close()、kill()、destroy() 不是一回事。

阶段 3 · 执行：模型的手脚【核心】

问题：命令、文件、代码怎样变成可验证、可限制、可回传的动作？ 你要得到：能处理流式输出、超时、非零退出码、stderr、大文件和连接失败。产出：一个带超时、截断和结构化返回的命令工具层。 核心认识：execution.text 不是全部证据；传输成功不等于命令成功。

阶段 4 · 运行时：同一份契约，不同的落脚点【进阶】

问题：同一个创建请求，怎样落到 Docker 容器、Kubernetes Pod 或 FastSandbox 微虚拟机？池化和快照改变了什么？ 你要得到：能画出 server → CRD → controller → Pod → execd 的链路；能解释 Pool、Snapshot、Template 的职责和边界。产出：一张运行时选型表 + 一份 Pool/快照故障说明。 核心认识：运行时中立不等于能力等价；“接口支持”必须带上后端和配置条件。

阶段 5 · 网络与凭据：让该通的通、该断的断【进阶】

问题：外部怎样访问沙箱？沙箱能访问哪些外部目标？密钥怎样不进入不可信进程？ 你要得到：能设计默认拒绝的出站策略，解释 ingress 路由和错误语义，说明 Credential Vault 的注入原理和失败边界。产出：一页网络策略设计 + 一次允许/拒绝验证。 核心认识：只限制 DNS 不等于只允许域名；凭据保险箱不是“把密钥加密后放进沙箱”。

阶段 6 · 接口与契约：同一种能力的多个入口【进阶】

问题：五种语言 SDK、osb CLI、MCP 和四个 OpenAPI 契约是什么关系？遇到行为不一致时相信谁？ 你要得到：能画出“契约 → 生成 API → adapter → 高层 SDK → CLI/MCP”的层级图；能追一个 SDK 调用到 HTTP。产出：一张接口选型表 + 一次契约对照实验。 核心认识：契约是源，SDK 是消费者；生成代码、手写适配和语言便利接口不能互相替代。

阶段 7 · Agent 集成：把沙箱变成受控工具【AI 应用核心】

问题：怎样让模型安全地“写文件 → 运行 → 看结果 → 修正”，而不是变成不可控的自动执行脚本？ 你要得到：能设计少量清晰的工具、预算和停止条件；能处理上下文截断、错误分类和提示注入。产出：一个带工具合同、步骤预算和完整轨迹的最小 Agent。 核心认识：模型可以提建议，批准规则必须由代码、策略和运行时执行。

阶段 8 · 工程化：从“能跑”到“敢上线”【核心】

问题：怎样证明系统安全、可观测、可测试、可发布、可回滚？ 你要得到：能完成威胁建模、密钥分类、资源预算、测试金字塔、指标与发布验证。产出：一份 5–8 页的生产就绪评审。 核心认识：沙箱只是执行边界，不是完整的业务安全模型；测试要证明行为，不只证明“能启动”。

阶段 9 · 综合实战：做一个完整的受限执行应用【实战】

问题：能不能把八块能力合成一个可演示、可解释、可复盘的产品？ 你要得到：不再依赖教程，能独立设计生命周期、工具、网络、观测和失败路径。产出：一个数据分析与报告 Agent + 架构图 + 威胁模型 + 测试记录 + 成本对比 + 复盘。 核心认识：真正的掌握不是“会用 API”，而是能把不确定的模型行为放进确定的工程边界里。

五、推荐节奏与路线

完整路线建议 8 周，每周 8–12 小时。时间是估算，不是考核标准；能讲清、能验证比赶进度重要。

周次	主线	阶段
第 1 周	跑起来 → 系统地图	0、1
第 2 周	生命周期	2
第 3 周	执行与文件	3
第 4 周	运行时与部署	4
第 5 周	网络与凭据	5
第 6 周	接口与 Agent 集成	6、7
第 7 周	工程化与生产	8
第 8 周	毕业项目与复盘	9

四种走法

最小路线：0 → 1 → 2 → 3 → 7 → 8 → 9。先做出一个安全的小 Agent，再补运行时和网络。
完整路线：0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9。适合想系统掌握平台能力的人。
AI 应用开发者路线：0 → 1 → 2 → 3 → 5 → 6 → 7 → 8 → 9。重点在工具、网络、上下文和生产化；阶段 4 可先读概念。
平台/基础设施路线：0 → 1 → 2 → 3 → 4 → 5 → 8 → 选修区。重点在运行时、池化、快照、多租户和发布。

如果时间不够，不要跳过阶段 1–3 的“理解 + 小实验”；可以暂时不深挖 FastSandbox、Windows guest 和 node-agent。

三个里程碑

第 1 周末：能讲清“创建和执行为什么是两条路径”，并用原始 HTTP 走通一次创建、端点解析和删除。
第 4 周末：能独立写出带 TTL、异常清理和输出截断的沙箱工具层。
第 8 周末：能交付一个有安全边界、可观测、可复现的 AI 应用，并诚实标注未验证能力。

六、最终毕业设计：一个受限执行 Agent

阶段 9 的核心不是再做几道散题，而是把前面的知识重新组装。最低要求如下：

生命周期：带 TTL、异常清理、状态查询和幂等销毁；
工具层：至少四个工具（写文件、读文件、运行命令、列/取产物），统一结构化返回；
网络边界：默认拒绝的出站策略，只放行任务所需域名；
密钥边界：真实密钥不进入沙箱环境、文件、日志或模型上下文；
Agent 循环：有轮数、工具调用数、时间预算和明确停止原因；
观测：request_id、sandbox_id、工具调用、退出码、耗时能串起来；
测试：至少覆盖超时、非零退出码、429、清理失败和提示注入；
报告：产物可追溯，数字不靠模型编造；
复盘：一页架构图、一页威胁模型、一页成本/延迟对比。

如果你能不看教程完成这套设计，并解释为什么每个部件存在，这门课的目标就达到了。

七、核心术语小抄

术语	一句话解释
Sandbox	一个隔离的执行环境，由容器、Pod 或微虚拟机承载
Lifecycle	创建、查询、续期、暂停、恢复、销毁这一套管理动作
Endpoint	某个沙箱端口在当前部署下可访问的地址、协议和请求头
execd	沙箱内的执行守护进程，提供命令、文件、代码、PTY、指标 API
Runtime	真正创建资源的后端：Docker、Kubernetes、FastSandbox
TTL	沙箱的绝对过期时间，不是空闲超时
Renew	把过期时间设为“当前时间 + 指定时长”，不是累加
Pause / Resume	暂停并保存可恢复检查点；恢复通常不保留运行内存
Snapshot	根文件系统或（可选）VM 状态的检查点
Template	FastSandbox 预先构建的不可变工作负载定义
Pool	预热的 Pod 容量池，降低分配延迟
BatchSandbox	Kubernetes 中描述一个或多个沙箱的 CRD
Egress	沙箱出站流量的策略执行面
Ingress	外部访问沙箱服务的入站网关
Credential Vault	把真实凭据留在 sidecar，按目标注入的机制
Isolated Session	沙箱内基于 bubblewrap 的独立命名空间会话
Contract	`specs/` 中的公开 OpenAPI 契约

八、文档地图

文档	作用
整体架构	先读的总览：主线、八块、分层、请求旅程、设计取舍
阶段 0	环境搭建与最小闭环
阶段 1	系统地图、三类 API、创建与执行两条链路
阶段 2	生命周期、TTL、暂停恢复、快照、清理语义
阶段 3	execd、命令、流式输出、文件、会话、代码上下文
阶段 4	Docker、Kubernetes、Pool、Snapshot、FastSandbox、隔离运行时
阶段 5	端点、ingress、egress、Credential Vault、secure access
阶段 6	契约、多语言 SDK、CLI、MCP
阶段 7	工具合同、Agent 循环、上下文、提示注入
阶段 8	威胁模型、测试、观测、多租户、发布验证
阶段 9	毕业项目、里程碑、验收与答辩
选修区	Code Interpreter、浏览器、存储、Windows、隔离会话等

使用顺序：总览读两遍 → 当前阶段清单 → 阶段详解 → 做实验 → 回到总图复述。不要从文档目录顺序硬读所有源码。

九、环境与常用命令

源码目录固定在 $OSB_SRC。在 PowerShell 中：

cd $OSB_SRC

# 版本与源码状态
git describe --tags --always
docker version

# Python 环境（源码安装，和教材对齐）
uv venv .venv
.\.venv\Scripts\Activate.ps1
uv pip install -e .\server -e .\sdks\sandbox\python

# 生成 Docker 运行时配置并启动服务端
opensandbox-server init-config "$HOME\.sandbox.toml" --example docker
opensandbox-server

# 验证
curl.exe http://127.0.0.1:8080/health
curl.exe -H "OPEN-SANDBOX-API-KEY: dev-secret" http://127.0.0.1:8080/version

观察原始 API 时，优先用 curl.exe 或 PowerShell 的 Invoke-RestMethod；不要让 SDK 的封装遮住状态码、请求头和错误体。

十、学习进度表

基于 OpenSandbox release-1.1.1（531700ca，2026-10-09）重写 · 2026-10-30