OpenSandbox API 规范详解生命周期、诊断、沙箱内执行与出站策略四份 OpenAPI 契约【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandboxOpenSandbox 通过specs/目录下的四份 OpenAPI 3.1 文档定义了项目的全部公共 API 契约沙箱生命周期管理sandbox-lifecycle.yml、沙箱诊断diagnostic-api.yml、沙箱内代码执行execd-api.yaml与出站策略egress-api.yaml。读完本篇你可以掌握每个 API 的 Base URL、认证方式、完整端点清单、核心请求/响应模型与状态机语义并能结合服务端与组件源码理解这些契约在实现侧的落点。一、规范文件总览四份规范文档均位于仓库根目录的 specs/ 目录下规范文件服务本地 Base URL认证方式sandbox-lifecycle.yml生命周期管理服务server/http://localhost:8080/v1OPEN-SANDBOX-API-KEY请求头diagnostic-api.yml诊断服务server/http://localhost:8080/v1OPEN-SANDBOX-API-KEY请求头execd-api.yaml沙箱内执行守护进程execdhttp://localhost:44772X-EXECD-ACCESS-TOKEN请求头egress-api.yaml沙箱内 egress sidecarhttp://localhost:18080可选OPENSANDBOX-EGRESS-AUTH请求头各文档 servers 声明的 Base URL 即构建请求时使用的地址例如生命周期 API 为http://localhost:8080/v1execd 为http://localhost:44772egress 为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可通过两种方式提供见 securitySchemesHTTP 请求头OPEN-SANDBOX-API-KEY: your-api-key环境变量OPEN_SANDBOX_API_KEYSDK 客户端会自动读取二、沙箱生命周期管理 APIsandbox-lifecycle.yml生命周期 API 定义从容器镜像或快照创建、管理并销毁沙箱的完整接口。其服务描述给出了沙箱生命周期流程info.descriptionCreation— 沙箱被供给并进入Running状态Execution— 运行中并接受请求Pause可选—Pausing→Paused异步Resume可选—Resuming→Running异步Termination—Stopping→Terminated由 kill 操作、TTL 到期或错误触发Error— 任何状态遇到关键错误都可转入Failedstatus字段通过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}— 获取沙箱完整信息含启动来源与 entrypointDELETE /sandboxes/{sandboxId}— 删除沙箱POST /sandboxes/{sandboxId}/snapshots— 从沙箱创建快照POST /sandboxes/{sandboxId}/pause— 暂停沙箱异步返回 202POST /sandboxes/{sandboxId}/resume— 恢复已暂停的沙箱POST /sandboxes/{sandboxId}/renew-expiration— 续租沙箱过期时间TTLPATCH /sandboxes/{sandboxId}/metadata— 以 JSON Merge PatchRFC 7396语义修补元数据GET /sandboxes/{sandboxId}/endpoints/{port}— 获取沙箱内某服务端口的访问端点快照管理GET /snapshots— 按来源沙箱、精确名称、状态过滤并分页列出快照GET /snapshots/{snapshotId}— 获取快照状态与元数据DELETE /snapshots/{snapshotId}— 删除快照除上述主线端点外规范还包含若干补充端点GET/PUT /sandboxes/{sandboxId}/networkpolicy读取/整体替换出站策略Fsb 后端返回的是持久化的策略意图而非实时执行状态、POST /metrics/eventsSDK 侧 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 中的示例值为8640024 小时。注意手动清理manual cleanup是否可用与运行时相关Kubernetes 侧若 workload provider 不支持非过期沙箱可能拒绝省略或为 null 的 timeout。resourceLimitsKubernetes 风格的硬上限cpu: 500m、memory: 512Mi、gpu: 1新资源类型无需 API 变更即可扩展。resourceRequests仅对 Kubernetes 系运行时有效省略时用resourceLimits同时作为 requests/limitsGuaranteed QoS提供后形成 Burstable QoS。platformoslinux/windows与archamd64/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均使用统一的 PaginationInfopage默认 1、pageSize默认 20返回totalItems、totalPages、hasNextPage。过滤逻辑为不同过滤条件之间 AND同一state参数多次出现之间 OR如?stateRunningstatePausedmetadata过滤值需 URL 编码例如?metadataproject%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_proxytrue互斥。Sandbox.allocation 为可选响应字段AllocationSummarymode: poolpoolRefstate: allocated语义在规范中写得很严格仅在运行时确认了当前具体 Pool 分配时返回未确认、非 Pool 沙箱及正在释放的分配均省略。它不是请求回显、不是分配历史、也不是就绪信号且不暴露 Pod 名等 Kubernetes 内部字段。三、沙箱诊断 APIdiagnostic-api.yml诊断 API 暴露 best-effort 的纯文本诊断快照面向人类与排障 Agent用于在不依赖稳定结构化可观测模型的前提下收集运行排障材料。规范明确声明这不是审计日志 API也不定义规范化的可观测 schema结构化遥测、长期留存、过滤、分页与流式可能由其他机制单独提供。端点base path/v1GET /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/expiresAtdelivery: url时必须包含contentUrl与expiresAt且省略contenttruncated表示服务端是否主动截断了载荷不代表后端留存缺口如过期的 Kubernetes Events后者应通过warnings上报。规范同时给出了内联与 URL 两种交付形态的完整响应示例例如内联容器日志、可下载的运行时事件文本本版本不提供流式、分页或稳定的行级 schema服务端可对留存与响应大小实施实现定义的限制。未实现的部署返回 501NotImplemented。四、沙箱内代码执行 APIexecd-api.yamlexecd API 提供沙箱内的代码执行、命令执行、文件操作与系统监控能力全部端点要求X-EXECD-ACCESS-TOKEN认证头。本地 Base URL 为http://localhost:44772。核心能力包括有状态代码执行Python、JavaScript 等、Shell 命令执行前台/后台 状态轮询、完整文件 CRUD、SSE 实时输出流、CPU/内存实时指标。4.1 健康检查与代码解释器GET /ping— 服务健康检查常用于负载均衡与编排平台的存活探测GET /code/contexts?languagepython— 按语言过滤列出活跃代码执行上下文DELETE /code/contexts?languagepython— 删除某语言下的全部上下文DELETE /code/contexts/{context_id}— 删除指定上下文终止底层线程/进程并释放资源POST /code/context— 创建代码执行上下文返回会话 ID请求体如{language: python}POST /code— 在上下文中执行代码输出通过 SSE 流式返回支持无状态执行省略 contextDELETE /code?idsession-123— 中断代码执行4.2 命令执行与 Bash 会话POST /command— 执行 shell 命令流式输出。RunCommandRequest 要求commandshell 文本与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?cursor120— 拉取后台命令累积的 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 对象的映射含typefile/directory/symlink/other、size、modified_at、owner、group、八进制modeDELETE /files?path...— 删除文件不含目录目录用目录端点POST /files/permissions— 批量修改权限请求体为路径到 Permissionowner/group/modemode 默认 755的映射POST /files/mv— 批量重命名/移动[{src: ..., dest: ...}]目标目录必须存在GET /files/search— 按 glob 模式搜索文件POST /files/replace— 批量替换文件内容old/new返回每个文件的replacedCountPOST /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/实现目录相对应可用于进一步对照实现。五、出站策略 APIegress-api.yamlegress API 由沙箱内的 egress sidecarcomponents/egress 组件直接暴露用于沙箱创建后对出站网络策略的运行时检查与变更创建期的初始出站策略仍属于生命周期 API 的 create 请求。访问模型为两步info.description先用生命周期 API 解析 egress 服务端口的沙箱端点直接向该端点的/policy或/credential-vault路由发请求。sidecar 可选要求OPENSANDBOX-EGRESS-AUTH请求头当沙箱端点解析器返回所需请求头时客户端必须在每次 egress API 请求中原样转发。策略端点GET /policy— 返回当前执行的出站策略及派生运行时模式status、mode如deny_all、enforcementMode如dns、policyPATCH /policy— 以合并语义将新规则并入当前策略现有规则保留除非被入站规则覆盖入站规则优先级更高同一 payload 中重复target时第一条生效DELETE /policy— 按 targetFQDN 或通配域移除规则未命中的 target 静默忽略幂等NetworkPolicy 由defaultActionallow/deny缺省语义为 deny与按序评估的egress规则数组组成NetworkRule 的target目前仅支持 FQDN 或通配域如*.example.comIP/CIDR 在 egress MVP 中尚未支持。规范中另一组端点为沙箱本地 Credential Vault 管理POST/GET/PATCH/DELETE /credential-vault及 credentials/bindings 的只读元数据接口其内联凭据值为 write-only、永不回显且要求 sidecar 运行于dnsnft模式并存在出站策略。六、贯穿三套 API 的技术特性6.1 SSE 流式输出事件类型代码执行与命令执行接口使用 SSE 做实时流式输出。ServerStreamEvent 定义了事件类型枚举init初始化、status状态更新、stdout/stderr标准输出/错误流、result执行结果、execution_complete执行完成、execution_count执行计数、error错误信息规范中还包括ping保活类型。事件载荷除type外还可携带text、execution_count、execution_time毫秒、timestampUnix 毫秒与多 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 Mapsandbox-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 URL8080/44772/18080来自各规范servers声明实际部署中端点地址由平台决定egress API 必须经“先解析沙箱端点、再直连 sidecar”的两步方式访问而非通过服务端生命周期转发。生命周期 API 的secureAccess、templateId、Pool 模式与 fsb 模板端点均对运行时有前提如 Kubernetes ingress 网关模式、kubernetes/fsb运行时Docker 运行时下模板端点返回 501。诊断 API 本版本无流式、分页与稳定行级 schemaegress 策略的target暂不支持 IP/CIDR。契约演进遵循 additive 原则规范中的状态枚举与 scope 均声明“未来可能新增取值客户端应优雅处理未知值”编写客户端时建议将未知状态/事件类型按默认分支处理。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考