企业官网建设流程全解析

OpenSandbox API 规范详解：生命周期、诊断、沙箱内执行与出站策略四份 OpenAPI 契约

【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox

OpenSandbox 通过specs/目录下的四份 OpenAPI 3.1 文档定义了项目的全部公共 API 契约：沙箱生命周期管理（sandbox-lifecycle.yml）、沙箱诊断（diagnostic-api.yml）、沙箱内代码执行（execd-api.yaml）与出站策略（egress-api.yaml）。读完本篇，你可以掌握每个 API 的 Base URL、认证方式、完整端点清单、核心请求/响应模型与状态机语义，并能结合服务端与组件源码理解这些契约在实现侧的落点。

一、规范文件总览

四份规范文档均位于仓库根目录的 specs/ 目录下：

各文档 servers 声明的 Base URL 即构建请求时使用的地址，例如生命周期 API 为http://localhost:8080/v1，execd 为http://localhost:44772，egress 为http://localhost:18080。

从源码结构看，这些契约的职责划分在 specs/AGENTS.md 中有明确说明：specs/下的规范文件被视为公共接口的 source of truth，变更倾向于 additive（只做增量）；契约变更后需要联动server/（生命周期）、sdks/（各语言 SDK 再生成）以及components/（execd/egress）等下游消费方。该文档还给出了生命周期消费方的验证命令（uv sync --all-groups、uv run ruff check、uv run pytest），说明规范、服务端实现与测试是作为一组同步维护的。

生命周期 API 的认证方式为 API Key，可通过两种方式提供（见 securitySchemes）：

1. HTTP 请求头：OPEN-SANDBOX-API-KEY: your-api-key
2. 环境变量OPEN_SANDBOX_API_KEY（SDK 客户端会自动读取）

二、沙箱生命周期管理 API（sandbox-lifecycle.yml）

生命周期 API 定义从容器镜像或快照创建、管理并销毁沙箱的完整接口。其服务描述给出了沙箱生命周期流程（info.description）：

1. Creation— 沙箱被供给并进入Running状态
2. Execution— 运行中并接受请求
3. Pause（可选）—Pausing→Paused（异步）
4. Resume（可选）—Resuming→Running（异步）
5. Termination—Stopping→Terminated（由 kill 操作、TTL 到期或错误触发）
6. Error— 任何状态遇到关键错误都可转入Failed

status字段通过state、reason、message提供细粒度信息。SandboxState 枚举 列出的状态包括Pending、Running、Pausing、Paused、Resuming、Stopping、Terminated、Failed，并给出了完整状态迁移规则（如Running → Pausing、Pausing → Paused、Running/Paused → Stopping等），同时明确提示客户端应优雅处理未来新增的未知状态值。

2.1 核心端点清单（base path/v1）

沙箱管理：

• POST /sandboxes— 从镜像或快照创建沙箱，可指定超时与资源限制
• GET /sandboxes— 按状态/元数据过滤并分页列出沙箱
• GET /sandboxes/{sandboxId}— 获取沙箱完整信息（含启动来源与 entrypoint）
• DELETE /sandboxes/{sandboxId}— 删除沙箱
• POST /sandboxes/{sandboxId}/snapshots— 从沙箱创建快照
• POST /sandboxes/{sandboxId}/pause— 暂停沙箱（异步，返回 202）
• POST /sandboxes/{sandboxId}/resume— 恢复已暂停的沙箱
• POST /sandboxes/{sandboxId}/renew-expiration— 续租沙箱过期时间（TTL）
• PATCH /sandboxes/{sandboxId}/metadata— 以 JSON Merge Patch（RFC 7396）语义修补元数据
• GET /sandboxes/{sandboxId}/endpoints/{port}— 获取沙箱内某服务端口的访问端点

快照管理：

• GET /snapshots— 按来源沙箱、精确名称、状态过滤并分页列出快照
• GET /snapshots/{snapshotId}— 获取快照状态与元数据
• DELETE /snapshots/{snapshotId}— 删除快照

除上述主线端点外，规范还包含若干补充端点：GET/PUT /sandboxes/{sandboxId}/networkpolicy（读取/整体替换出站策略，Fsb 后端返回的是持久化的策略意图而非实时执行状态）、POST /metrics/events（SDK 侧 best-effort 遥测上报）、以及POST/GET /templates与GET/DELETE /templates/{templateId}（fsb golden-image 模板管理，仅 Kubernetes 系后端可用，否则返回 501）。

2.2 创建沙箱请求的关键语义

CreateSandboxRequest 是整份规范中最复杂的模型，创建语义可归纳为三种模式：

• 标准模式：image与snapshotId二选一（互斥），且resourceLimits必填。提供image时entrypoint必填；提供snapshotId时entrypoint可选，缺省时服务端默认为["tail", "-f", "/dev/null"]。
• Pool 模式：通过extensions.poolRef从预配置 Pool 中分配 Pod；此时image、resourceLimits、entrypoint均可选（由 Pool CRD 模板决定），但snapshotId、networkPolicy、platform、volumes、credentialProxy.enabled不得同时提供。
• 模板模式：templateId指向 fsb golden-image 模板，与image/snapshotId互斥；模板模式下工作负载形状由模板固定，entrypoint、env、resourceLimits、volumes、platform、credentialProxy、secureAccess、lifecycle均会被拒绝（400），且timeout必填；模板必须属于请求者租户且构建Succeeded，否则返回 404（不做存在性泄漏）。

其他关键字段：

• timeout：秒数（最小 60）或null；省略或置null表示禁用自动过期、要求显式清理。上限由服务端配置server.max_sandbox_timeout_seconds控制——在服务端 config.py 中该字段默认为None（不封顶），而 example.config.toml 中的示例值为86400（24 小时）。注意手动清理（manual cleanup）是否可用与运行时相关：Kubernetes 侧若 workload provider 不支持非过期沙箱，可能拒绝省略或为 null 的 timeout。
• resourceLimits：Kubernetes 风格的硬上限（cpu: "500m"、memory: "512Mi"、gpu: "1"），新资源类型无需 API 变更即可扩展。
• resourceRequests：仅对 Kubernetes 系运行时有效，省略时用resourceLimits同时作为 requests/limits（Guaranteed QoS），提供后形成 Burstable QoS。
• platform：os（linux/windows）与arch（amd64/arm64）的调度约束；省略时由运行时应用默认行为，无法满足时必须显式失败。
• lifecycle：声明式生命周期钩子，本版本支持preStart（每次容器启动时、用户 entrypoint 之前执行，失败会阻止 entrypoint 启动，超时上限 3 小时）与periodic（由 execd 按 cron 或@every描述符调度，超时上限 300 秒，同名钩子运行不重叠）。
• secureAccess：默认false。开启后沙箱端点访问需要凭据，仅在通过 ingress 网关暴露的 Kubernetes 沙箱上支持；服务端会签发访问凭据，并在端点响应中返回客户端必须携带的请求头。
• volumes：存储挂载数组，每条记录必须指定恰好一种后端（host宿主机绑定挂载、pvc平台命名卷、ossfs阿里云 OSS），配合mountPath、readOnly、subPath。例如pvc后端默认createIfNotExists: true，可通过storage、storageClass、accessModes控制自动创建行为；deleteOnSandboxTermination仅对服务端自动创建的卷生效。
• extensions：不透明扩展容器，保留给内部特性与实验性标志，SDK 应透明透传。其中知名键access.renew.extend.seconds（取值 300–86400 的十进制字符串）用于订阅 OSEP-0009 的“访问时自动续租”，非法值在创建时即以 400 拒绝。

创建成功的响应（202）包含id、status.state: "Running"、metadata、expiresAt、createdAt与entrypoint；启动来源详情（image/snapshotId）不在创建响应中，需用GET /sandboxes/{sandboxId}获取完整表示。此外创建端点对 Kubernetes 配额耗尽定义了明确的 fail-fast 语义：agent-sandboxprovider 下返回 403 且ErrorResponse.code为KUBERNETES::QUOTA_EXCEEDED；默认batchsandboxprovider 下则等待创建超时。Pool 容量在获取超时前不可用则返回 429 并携带Retry-After头。

2.3 列表过滤、分页与元数据修补

GET /sandboxes与GET /snapshots均使用统一的 PaginationInfo（page默认 1、pageSize默认 20，返回totalItems、totalPages、hasNextPage）。过滤逻辑为：不同过滤条件之间 AND，同一state参数多次出现之间 OR（如?state=Running&state=Paused）；metadata过滤值需 URL 编码，例如?metadata=project%3DApollo%26note%3DDemo%252520Test。

PATCH /sandboxes/{sandboxId}/metadata遵循 JSON Merge Patch 规则：非 null 值新增或替换、null值删除（键不存在时静默忽略）、缺省键保持不变、空{}为无操作。元数据键值需符合 Kubernetes label 规则（值不超过 63 字符、匹配[A-Za-z0-9](https://link.gitcode.com/i/567d19901156cd45b35891e2f21776a2)?），opensandbox.io/前缀保留。该操作不会重启沙箱容器；规范也坦承其为无乐观锁的 read-modify-write，并发写入可能交错丢失，需要单一写者或带外协调。

2.4 端点访问与可选 allocation 字段

GET /sandboxes/{sandboxId}/endpoints/{port}返回沙箱内指定端口服务的公网访问 URL（格式{endpoint-host}/sandboxes/{sandboxId}/port/{port}）。查询参数有两个：use_server_proxy（返回服务端代理 URL，默认 false）与expires（设定后签发 OSEP-0011 签名访问路由，取值为 Unix epoch 秒数，与use_server_proxy=true互斥）。

Sandbox.allocation 为可选响应字段（AllocationSummary，mode: "pool"+poolRef+state: "allocated"），语义在规范中写得很严格：仅在运行时确认了当前具体 Pool 分配时返回；未确认、非 Pool 沙箱及正在释放的分配均省略。它不是请求回显、不是分配历史、也不是就绪信号，且不暴露 Pod 名等 Kubernetes 内部字段。

三、沙箱诊断 API（diagnostic-api.yml）

诊断 API 暴露 best-effort 的纯文本诊断快照，面向人类与排障 Agent，用于在不依赖稳定结构化可观测模型的前提下收集运行排障材料。规范明确声明：这不是审计日志 API，也不定义规范化的可观测 schema；结构化遥测、长期留存、过滤、分页与流式可能由其他机制单独提供。

端点（base path/v1）：

• GET /sandboxes/{sandboxId}/diagnostics/logs— 获取指定 scope 的诊断日志内容描述符
• GET /sandboxes/{sandboxId}/diagnostics/events— 获取指定 scope 的诊断事件内容描述符

scope为必填查询参数，已知取值可能包括container、lifecycle、runtime、network、process、all；支持的 scope 是实现定义的，服务端可持续新增。在仍暴露旧版 DevOps 纯文本行为的部署上，不带scope的请求会被视为弃用的旧式请求，可能返回text/plain而非 JSON 描述符。

成功响应返回 DiagnosticContentResponse JSON 描述符，诊断文本要么以content内联，要么通过contentUrl提供下载：

• delivery: inline时必须包含content且省略contentUrl/expiresAt；
• delivery: url时必须包含contentUrl与expiresAt且省略content；
• truncated表示服务端是否主动截断了载荷（不代表后端留存缺口，如过期的 Kubernetes Events，后者应通过warnings上报）。

规范同时给出了内联与 URL 两种交付形态的完整响应示例（例如内联容器日志、可下载的运行时事件文本），本版本不提供流式、分页或稳定的行级 schema，服务端可对留存与响应大小实施实现定义的限制。未实现的部署返回 501（NotImplemented）。

四、沙箱内代码执行 API（execd-api.yaml）

execd API 提供沙箱内的代码执行、命令执行、文件操作与系统监控能力，全部端点要求X-EXECD-ACCESS-TOKEN认证头。本地 Base URL 为http://localhost:44772。核心能力包括：有状态代码执行（Python、JavaScript 等）、Shell 命令执行（前台/后台 + 状态轮询）、完整文件 CRUD、SSE 实时输出流、CPU/内存实时指标。

4.1 健康检查与代码解释器

• GET /ping— 服务健康检查，常用于负载均衡与编排平台的存活探测
• GET /code/contexts?language=python— 按语言过滤列出活跃代码执行上下文
• DELETE /code/contexts?language=python— 删除某语言下的全部上下文
• DELETE /code/contexts/{context_id}— 删除指定上下文（终止底层线程/进程并释放资源）
• POST /code/context— 创建代码执行上下文，返回会话 ID（请求体如{"language": "python"}）
• POST /code— 在上下文中执行代码，输出通过 SSE 流式返回；支持无状态执行（省略 context）
• DELETE /code?id=session-123— 中断代码执行

4.2 命令执行与 Bash 会话

• POST /command— 执行 shell 命令（流式输出）。RunCommandRequest 要求command（shell 文本）与argv（原生参数）恰好提供其一；cwd支持变量展开与~展开、未定义变量会校验失败；background: true进入分离（detached）模式；timeout为毫秒级强制时限；还可通过uid/gid指定运行身份（提供gid时必须同时提供uid），通过envs注入环境变量（按请求值 >EXECD_ENVS> 守护进程变量的优先级覆盖）。
• DELETE /command?id=...— 中断命令执行
• GET /command/status/{id}— 查询前台/后台命令状态（running标志、退出码、错误信息、起止时间戳）；已完成命令元数据至少保留 24 小时，由每小时一次的清理移除，运行中命令永不被留存清理移除
• GET /command/{id}/logs?cursor=120— 拉取后台命令累积的 stdout/stderr；响应体为可直接渲染的纯文本，支持类文件 seek 的增量读取——响应头EXECD-COMMANDS-TAIL-CURSOR给出最新行号供下次轮询

Bash 会话（跨执行保留工作目录与环境等 shell 状态）：

• POST /session— 创建 bash 会话，请求体可选（{}使用默认选项，或{"cwd": "/workspace"}指定工作目录）
• POST /session/{sessionId}/run— 在会话中执行命令（SSE 流式输出，支持cwd覆盖与timeout毫秒超时）
• DELETE /session/{sessionId}— 删除会话，终止底层 shell 进程

4.3 文件系统与目录操作

• GET /files/info?path=...— 获取一个或多个文件的元数据，返回路径到 FileInfo 对象的映射（含type：file/directory/symlink/other、size、modified_at、owner、group、八进制mode）
• DELETE /files?path=...— 删除文件（不含目录，目录用目录端点）
• POST /files/permissions— 批量修改权限，请求体为路径到 Permission（owner/group/mode，mode 默认 755）的映射
• POST /files/mv— 批量重命名/移动（[{"src": ..., "dest": ...}]），目标目录必须存在
• GET /files/search— 按 glob 模式搜索文件
• POST /files/replace— 批量替换文件内容（old/new，返回每个文件的replacedCount）
• POST /files/upload— 多部分上传文件
• GET /files/download— 下载文件，支持 range 请求

目录操作：

• GET /directories/list— 列目录内容，支持深度控制
• POST /directories— 创建目录并设置权限（mkdir -p语义）
• DELETE /directories— 递归删除目录

系统指标：

• GET /metrics— 获取 CPU/内存等系统资源指标（cpu_count、cpu_used_pct、mem_total_mib等）
• GET /metrics/watch— 以 SSE 流实时监视指标

4.4 隔离执行（base path/v1/isolated）

规范还提供了一组按会话做命名空间隔离的执行 API（标签 IsolatedExecution，描述为 per-session namespace isolation、代码执行与文件系统代理），原文档列举的主要端点包括：

• POST /v1/isolated/session— 创建隔离 bash 会话
• GET /v1/isolated/capabilities— 查询隔离器能力
• GET/DELETE /v1/isolated/session/{sessionId}— 查询/删除隔离会话
• POST /v1/isolated/session/{sessionId}/run— 在隔离会话中执行代码（SSE 流式）
• GET /v1/isolated/session/{sessionId}/diff— 下载 upper 目录差异
• POST /v1/isolated/session/{sessionId}/commit— 将 upper 变更提交到工作区
• GET/DELETE /v1/isolated/session/{sessionId}/files及/files/info、/files/download、/files/upload、/files/mv、/files/permissions、/files/replace、/files/search— 会话内文件操作
• GET /v1/isolated/session/{sessionId}/directories/list、POST/DELETE .../directories— 会话内目录操作

从源码结构看，该 API 组还有 GET /v1/isolated/sessions、GET .../runs/{runId}与GET .../runs/{runId}/logs等端点，与components/execd/的pkg/isolation/实现目录相对应，可用于进一步对照实现。

五、出站策略 API（egress-api.yaml）

egress API 由沙箱内的 egress sidecar（components/egress 组件）直接暴露，用于沙箱创建后对出站网络策略的运行时检查与变更；创建期的初始出站策略仍属于生命周期 API 的 create 请求。访问模型为两步（info.description）：

1. 先用生命周期 API 解析 egress 服务端口的沙箱端点；
2. 直接向该端点的/policy（或/credential-vault）路由发请求。

sidecar 可选要求OPENSANDBOX-EGRESS-AUTH请求头；当沙箱端点解析器返回所需请求头时，客户端必须在每次 egress API 请求中原样转发。

策略端点：

• GET /policy— 返回当前执行的出站策略及派生运行时模式（status、mode如deny_all、enforcementMode如dns、policy）
• PATCH /policy— 以合并语义将新规则并入当前策略：现有规则保留除非被入站规则覆盖；入站规则优先级更高；同一 payload 中重复target时第一条生效
• DELETE /policy— 按 target（FQDN 或通配域）移除规则；未命中的 target 静默忽略（幂等）

NetworkPolicy 由defaultAction（allow/deny，缺省语义为 deny）与按序评估的egress规则数组组成；NetworkRule 的target目前仅支持 FQDN 或通配域（如*.example.com），IP/CIDR 在 egress MVP 中尚未支持。规范中另一组端点为沙箱本地 Credential Vault 管理（POST/GET/PATCH/DELETE /credential-vault及 credentials/bindings 的只读元数据接口），其内联凭据值为 write-only、永不回显，且要求 sidecar 运行于dns+nft模式并存在出站策略。

六、贯穿三套 API 的技术特性

6.1 SSE 流式输出事件类型

代码执行与命令执行接口使用 SSE 做实时流式输出。ServerStreamEvent 定义了事件类型枚举：init（初始化）、status（状态更新）、stdout/stderr（标准输出/错误流）、result（执行结果）、execution_complete（执行完成）、execution_count（执行计数）、error（错误信息），规范中还包括ping（保活）类型。事件载荷除type外还可携带text、execution_count、execution_time（毫秒）、timestamp（Unix 毫秒）与多 MIME 类型的results（如text/plain），错误事件带ename/evalue/traceback结构。

6.2 资源限制

生命周期 API 支持类 Kubernetes 的灵活资源配置：

{ "cpu": "500m", "memory": "512Mi", "gpu": "1" }

ResourceLimits以字符串键值对表达（cpu 用毫核、memory 用字节或人类可读格式），新资源类型无需 API 变更即可加入。

6.3 文件权限

execd 文件权限管理采用 Unix 风格：Permission模型包含owner、group与八进制mode（如 644、755，默认 755），通过POST /files/permissions批量应用。

七、契约与实现的对应关系

四份规范文件与消费方的对应关系（引自 specs/AGENTS.md 的 Contract Map）：

• sandbox-lifecycle.yml— 被server/、cli/与各沙箱 SDK 使用
• diagnostic-api.yml— 被服务端诊断、CLI 诊断与排障流程使用
• execd-api.yaml— 被components/execd/与 code-interpreter SDK 使用
• egress-api.yaml— egress sidecar API 及相关文档

实现侧可对照验证的路径包括：服务端路由与模型在 server/opensandbox_server/api/（lifecycle.py、schema.py、network_policy.py、templates.py等），服务端超时上限配置max_sandbox_timeout_seconds在 server/opensandbox_server/config.py 与 server/configuration.md 中有说明；execd 端点在components/execd/pkg/web/等目录；egress sidecar 策略处理在components/egress/policy_server.go与pkg/policy/。此外 specs/tests/test_execd_schema.py 对 execd 规范中的关键字段（如command/argv互斥约束）做了契约级测试，可作为理解规范细节的可靠佐证。

八、适用前提与限制

• 本地 Base URL（8080/44772/18080）来自各规范servers声明，实际部署中端点地址由平台决定；egress API 必须经“先解析沙箱端点、再直连 sidecar”的两步方式访问，而非通过服务端生命周期转发。
• 生命周期 API 的secureAccess、templateId、Pool 模式与 fsb 模板端点均对运行时有前提（如 Kubernetes ingress 网关模式、kubernetes/fsb运行时），Docker 运行时下模板端点返回 501。
• 诊断 API 本版本无流式、分页与稳定行级 schema；egress 策略的target暂不支持 IP/CIDR。
• 契约演进遵循 additive 原则：规范中的状态枚举与 scope 均声明“未来可能新增取值，客户端应优雅处理未知值”，编写客户端时建议将未知状态/事件类型按默认分支处理。

【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox