CubeSandbox v0.2.1 版本解析官方 Python SDK、启动性能优化与 Seccomp 安全修复全解读【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox导读CubeSandbox 是一个面向 AI Agent 的即时、并发、安全且轻量的沙箱项目。v0.2.12026.05.14是一次以「开发者体验 运行时稳定性 供应链安全」为核心的里程碑版本它首次发布了与 CubeAPI OpenAPI 规范完全对齐的官方 Python SDKcubesandboxv0.1.0在 Cubelet 启动路径上通过拆分内核文件同步逻辑跳过了昂贵的 SHA256 对比同时修复了 Seccomp 默认吞噬全部系统调用、shim stderr 被错误路由到 stdout 等多个关键缺陷。读完本文你将掌握该版本 SDK 的完整用法、各项性能优化与安全修复的源码级原理以及这些变更对后续 v0.2.x 系列演进的意义。一、版本总览一次「体验、性能、安全」三线并进的迭代v0.2.1 是 CubeSandbox 在 2026.05.14 发布的补丁级版本变更内容横跨仓库中的sdk/python、Cubelet、CubeMaster、CubeShim、CubeProxy、agent、hypervisor、CubeVS、network-agent、CubeAPI等多个组件。按变更日志docs/changelog/v0.2.1.md可归纳为六个维度维度核心变更新特性官方 Python SDKcubesandboxv0.1.0 首发性能Cubelet 启动跳过 SHA256CubeMaster 跳过冗余docker pull安全修复protobuf、rand、golang.org/x/net 等依赖升级Seccomp 默认放行修复关键修复shim stderr 路由、CubeProxy PRNG 种子、dev-env 同步符号链接、Dockerfile HTTPS-only 镜像源体验增强cubemastercli tpl watch阶段化输出IPAM 全面重构工程/CIexamples 重组为顶层目录DCO 检查ARC 自托管 runner下文将按「新特性 → 性能 → 安全 → 关键修复 → 工程与 CI」的顺序逐项深入每项均给出仓库中的源码或配置文件证据。二、重磅新特性官方 Python SDKcubesandboxv0.1.02.1 SDK 定位与安装v0.2.1 将 SDK 从示例级工具提升为官方一等公民。SDK 源码位于 sdk/python包名为cubesandbox其 pyproject.toml 声明了Python 版本要求requires-python 3.9运行时依赖httpx0.27与requests2开发依赖pytest、pytest-cov、mypystrict 模式、ruff测试配置testpaths [tests]并以 markere2e区分需要真实 CubeAPI 实例的端到端测试。SDK 与 CubeAPI 的 OpenAPI 规范openapi.yml完全对齐覆盖了沙箱全生命周期create / connect / pause / kill / list / health。安装方式为标准 pip 安装pip install cubesandbox2.2 快速上手与配置项SDK 使用环境变量或显式Config对象完成配置。环境变量清单完整继承自 sdk/python/README.md环境变量必填默认值说明CUBE_API_URL✅http://127.0.0.1:3000CubeAPI 管理面地址CUBE_TEMPLATE_ID✅—创建沙箱使用的模板 IDCUBE_PROXY_NODE_IP远程访问时—CubeProxy 节点 IP用于绕过*.cube.app的 DNS 解析CUBE_API_KEY—开启鉴权部署时的 API KeyCUBE_PROXY_PORT_HTTP80CubeProxy HTTP 端口CUBE_SANDBOX_DOMAINcube.app沙箱域名后缀最简用法只需三行from cubesandbox import Sandbox with Sandbox.create() as sb: result sb.run_code(1 1) print(result.text) # 2v0.2.1 版本还支持通过Config对象进行显式配置sdk/python/_config.py适合在代码中管理多环境参数from cubesandbox import Config, Sandbox cfg Config( api_urlhttp://10.0.0.1:3000, api_keymy-secret-key, template_idtpl-xxxxxxxxxxxxxxxxxxxxxxxx, proxy_node_ip10.0.0.1, ) with Sandbox.create(configcfg) as sb: print(sb.run_code(2 ** 10).text) # 10242.3 核心能力生命周期、代码执行与流式输出SDK 覆盖了与 CubeAPI 各端点一一对应的完整生命周期操作。类方法完整继承自 SDK README方法对应 API说明Sandbox.create(template, *, timeout, env_vars, envs, metadata, distribution_scope, volume_mounts, config)POST /sandboxes创建沙箱可选限定计算节点或挂载卷envs是 E2B 兼容的env_vars别名Sandbox.connect(sandbox_id, *, config)POST /sandboxes/:id/connect连接沙箱暂停中的沙箱会自动恢复Sandbox.list(config)GET /sandboxes列出运行中的沙箱v1Sandbox.list_v2(config)GET /v2/sandboxes列出沙箱v2支持过滤Sandbox.health(config)GET /health服务健康检查实例方法完整继承方法对应 API说明sb.run_code(code, *, on_stdout, on_stderr, on_result, on_error, envs, timeout)POST /execute执行代码返回Execution对象sb.get_info()GET /sandboxes/:id获取沙箱状态与元数据返回SandboxInfosb.pause(*, wait, timeout, interval)POST /sandboxes/:id/pause暂停沙箱默认等待至 paused超时 30ssb.resume(timeout)POST /sandboxes/:id/resume恢复沙箱已废弃建议改用connectsb.set_timeout(timeout)POST /sandboxes/:id/timeout设置沙箱空闲超时sb.kill()DELETE /sandboxes/:id销毁沙箱sb.get_host(port)—返回虚拟主机名{port}-{id}.{domain}代码执行与流式输出是 AI Agent 场景的核心诉求。SDK 同时支持捕获 stdout 列表与实时流式回调with Sandbox.create() as sb: # 捕获 stdout result sb.run_code(print(hello)) print(result.logs.stdout) # [hello\n] # 实时流式输出 sb.run_code( for i in range(3): print(i), on_stdoutlambda msg: print(out:, msg.text), )执行结果统一封装为Execution对象sdk/python/_models.py其属性包括.text最终表达式值、.logs.stdout/.logs.stderr全部输出行、.errorExecutionError异常信息与.results全部 result 事件。暂停/恢复在 v0.2.1 中强调「连接即自动恢复」的语义暂停时可自定义轮询参数sb Sandbox.create() sb.pause() # waitTrue, timeout30s 默认 sb.pause(waitFalse) # 提交即返回fire-and-forget sb.pause(timeout60, interval0.5) # 自定义轮询参数 sb2 Sandbox.connect(sb.sandbox_id) # 自动恢复暂停的沙箱2.4 网络策略L3/L4 与 L7 双层模型SDK 的network参数可同时组合三层能力L3/L4allow_out/deny_out的 CIDR 或主机名列表L7rules按 host / path / SNI 匹配支持审计与凭据注入使用类型化的Rule/Match/Action/Inject数据类sdk/python/_policy.pyInbound Hostmask_request_host定制 CubeProxy 转发给用户服务的 Host 头${PORT}会展开为请求的沙箱端口。规则按列表顺序首条匹配生效first-match-wins凭据注入仅在 SNI 与 Host 均匹配的 HTTPS 请求上执行由服务端强制。典型 L7 规则示例from cubesandbox import Sandbox, Rule, Match, Action, Inject rules [ Rule( namedeepseek_api, matchMatch( schemehttps, hostapi.deepseek.com, method[POST], path/v1/chat, sniapi.deepseek.com, ), actionAction( allowTrue, auditmetadata, inject[Inject( headerAuthorization, formatBearer ${SECRET}, secretsk_xxxxxxxx, )], ), ), ] with Sandbox.create( network{allow_out: [172.67.0.0/16], rules: rules}, ) as sb: sb.run_code(import requests; requests.post(https://api.deepseek.com/v1/chat))此外network[rules]还接受 E2B 风格的 host 键控映射per-host request transforms每个transform.headers条目会被转换为 CubeEgress 的 L7 规则在发往该主机的出站 HTTPS 请求中注入相同头。两种形态类型化Rule列表与 E2B 键控字典可任选其一但同一Sandbox.create调用中不可混用。旧的metadata{network-policy: ...}接口仍可用于仅 IP 的 deny-all / 自定义 allow-list 场景。2.5 文件系统、挂载与持久卷sb.files覆盖常用文件操作read/write/write_files批量支持 bytes/list/stat/exists/make_dir/rename/remove并支持watch_dir流式监听目录变更事件sdk/python/_filesystem.py。卷管理通过Volume辅助类实现E2B 兼容语义由卷插件如 COS、NFS 支撑from cubesandbox import Sandbox, Volume, VolumeMount vol Volume.create(my-data) # 默认插件driver 省略时不发送 driver 字段 with Sandbox.create(volume_mounts{/workspace: vol}) as sb: sb.files.write(/workspace/note.txt, persisted!) print(sb.files.read(/workspace/note.txt))Volume.create(nameNone, *, driverNone, configNone)→POST /volumes省略driver时后端使用第一个配置的插件Volume.connect(volume_id)/Volume.list()/Volume.get_info(volume_id)/Volume.destroy(volume_id)每个沙箱挂载点可独立选择读写模式VolumeMount(vol, read_onlyTrue)仅让本次挂载只读卷名必须匹配^[a-zA-Z0-9_-]$且不超过 128 字符非法名称会在发起任何网络调用前抛出ValueError。2.6 远程访问的 DNS 绕过机制当 SDK 运行在 CubeSandbox 节点之外时操作系统 DNS 无法解析*.cube.app。设置CUBE_PROXY_NODE_IP后启用IPOverrideTransportsdk/python/_transport.py所有数据面连接直接路由到该 IP同时保留虚拟Host头供 CubeProxy 做路由Without CUBE_PROXY_NODE_IP: SDK → OS DNS (*.cube.app) → CubeProxy With CUBE_PROXY_NODE_IP: SDK → TCP direct to CUBE_PROXY_NODE_IP:80 Host: 49999-{sandboxID}.cube.app (preserved for routing)2.7 测试与示例配套变更日志声明 SDK 附带 12 个工作示例、1 个并发基准以及 76/76 全部通过的测试。仓库中的实际布局为sdk/python/tests 包含test_sandbox.py、test_policy.py、test_volume.py及两个 L7 自定义端口端到端测试示例在 examples/code-sandbox-quickstart、examples/network-policy、examples/host-mount 等顶层目录中。测试可通过pytest运行端到端用例以e2emarker 标记需要真实 CubeAPI 实例。三、性能优化为启动延迟与镜像构建瘦身3.1 Cubelet将SyncKernelFile拆分为「检查」与「刷新」两条路径在 v0.2.1 之前Cubelet 每次启动都会对内核文件做一次 SHA256 对比以确认目标与共享内核一致。在模板数量较多的主机上这一「每启动一次的全量校验」明显拖慢了正常启动延迟。v0.2.1 将原SyncKernelFile拆分为两个职责分明的函数实现在 Cubelet/pkg/container/pmem/kernel_sync.goEnsureKernelFilePresent(ctx, sharedKernelPath, targetKernelPath)快速路径copy-if-missing。它仅检查共享内核合法requireValidSharedKernel然后通过inspectKernelFileState判断目标文件的三种状态——valid直接返回成功、missing报错提示文件不存在、invalid报错提示文件非法。全程不做任何 SHA256 计算。RefreshKernelFile(ctx, sharedKernelPath, targetKernelPath)强制刷新路径force-refresh with verification。它通过CopyFileAtomically以「同目录临时文件 os.Rename」的方式原子复制共享内核随后用validateRefreshedKernelFile做双重校验——先validateKernelFile检查目标文件本身再sameFileSHA256对比目标与共享内核的 SHA256校验失败或版本文件写入失败时通过cleanupKernelRuntimeFiles清理目标内核、version文件及其.tmp文件避免留下半成品。从调用点可以清晰看到两条路径的用途Cubelet/internal/cube/server/images/ext4image/utils.go常规启动走EnsureKernelFilePresent快路径不校验内容仅在需要强制对齐共享内核版本时才走RefreshKernelFile。CBRI 插件侧Cubelet/plugins/cbri/cubeboxcbri/cubebox.go在需要重新拉取内核时调用RefreshKernelFile。该拆分的正确性由一组表驱动单元测试保障Cubelet/pkg/container/pmem/kernel_sync_test.goTestRefreshKernelFileVerifiesCopiedContent刷新后必须与共享内核内容一致TestRefreshKernelFileCleansTargetOnVerificationFailure/TestRefreshKernelFileCleansRuntimeFilesOnVersionFailure校验失败或版本文件失败时清理运行时文件TestEnsureKernelFilePresentRejectsMissingTarget/TestEnsureKernelFilePresentRejectsSmallTarget/TestEnsureKernelFilePresentRejectsDirectoryTarget/TestEnsureKernelFilePresentRequiresValidSharedKernel快速路径对缺失、过小、目录等非法目标逐一拒绝TestEnsureKernelFilePresentDoesNotRequireVersion/TestEnsureKernelFilePresentIgnoresInvalidVersion快速路径不要求也不校验版本文件——这正是「跳过校验换启动速度」语义的直接印证。3.2 CubeMaster跳过本地已存在镜像的冗余docker pull模板构建过程中CubeMaster 此前即使源镜像已存在于本地也会执行一次docker pull造成无谓的 registry 往返。v0.2.1 在拉取前先检查镜像是否已存在存在则直接跳过拉取环节减少了模板构建阶段的网络开销与等待时间。该行为属于 CubeMaster 镜像/模板构建链路CubeMaster/pkg/service的优化方向与「本地优先、按需拉取」的通用镜像管理实践一致。四、安全修复依赖升级与 Seccomp 语义纠偏4.1 依赖安全升级清单v0.2.1 针对多个已知 CVE 完成了依赖升级完整清单来自变更日志组件变更背景shimprotobuf3.4.0 → 3.7.2RUSTSEC构造的未知字段可触发栈溢出连带升级containerd-shim-protos、containerd-shim、nixcubeapi/agent/shim/hypervisorrand0.8.5 → 0.8.6GHSA-cq8v-f236-94qcThreadRng重播种相关的健全性问题CubeVSgolang.org/x/net→ v0.38.0golang.org/x/sys→ v0.38.0Go 生态常规安全/修复升级network-agentgoogle.golang.org/grpc→ 1.79.3gRPC 库安全升级CubeAPI/examplespygments→ 2.20.0语法高亮库安全升级其中 protobuf 升级对应CubeShim的 protobuf 生成代码CubeShim/protocrand 升级横跨 agent/Cargo.toml、hypervisor 等多个 Rust 工作区成员。4.2 修复 Seccomp 默认吞噬全部系统调用这是本版本最值得关注的运行时安全修复。此前Seccomp初始化时未显式设置默认动作导致DefaultAction落入「拒绝一切」的语义——一旦 syscall 列表为空过滤器会静默拦截所有系统调用表现为沙箱内程序大面积异常。v0.2.1 的修复包含两个层面实现见 agent/rustjail/src/seccomp.rs默认动作修正为ActAllowinit_seccomp从 OCILinuxSeccomp配置解析default_action作为过滤器默认动作而 OCI 配置生成侧agent/rustjail/src/lib.rs 的seccomp_grpc_to_oci会透传 gRPC 中的DefaultAction。测试数据agent/rustjail/src/seccomp.rs明确使用defaultAction: SCMP_ACT_ALLOW配合SCMP_ACT_ERRNO的显式拒绝规则构成「默认放行、显式拒绝」的安全基线。空 syscall 列表短路为 no-op循环添加规则时若syscall.names为空会返回syscall name is required错误当action与def_action相同时直接continue避免冗余规则。空列表整体走默认动作路径不再产生「静默全拒」的副作用。此外init_seccomp还做了多项健壮性处理无法解析的系统调用名ScmpSyscall::from_name失败会被安全跳过而非报错兼容不同内核版本不支持的条件操作符会明确报错过滤器属性通过set_filter_attr应用SECCOMP_FILTER_FLAG_TSYNC/LOG/SPEC_ALLOW。单元测试test_init_seccomp覆盖了无条件规则、参数条件规则OR/AND 组合与 errno 返回值的验证。4.3 修复 shim 的 stderr 被路由到 stdout执行流Exec的流转发路径此前错误地调用 stdout 读取方法来读取 stderr导致标准错误流与标准输出流混叠。v0.2.1 修正了该路径stderr 现在会被正确捕获并独立转发。相关的流端口定义可以在 CubeShim/protoc/protos/agent.proto 中看到CreateContainerRequest第 11 字段、ExecRequest第 8 字段等均声明了独立的stderr_port与stdout_port严格区分——这为正确转发提供了协议层面的支撑。五、关键修复与健壮性增强5.1 CubeProxy为每个 worker 独立播种 PRNGOpenResty 默认情况下所有 worker 进程以相同种子启动通常为 1导致math.random()在各 worker 中产生相同序列。当缓存 TTL 抖动jitter依赖随机数时所有 worker 会在同一时刻集中过期引发同步的缓存雪崩stampede。修复位于 CubeProxy/lua/init_worker_phase.lua-- In OpenResty, math.randomseed should be called in the init_worker phase. -- Without this, all worker processes would start with the same seed (typically 1), -- causing math.random() to return the same sequence of values across all workers. -- This is critical for cache TTL jitter and other randomized behaviors to ensure -- they are truly distributed and dont lead to synchronized stampedes. math.randomseed(ngx.now() * 1000 ngx.worker.id())种子由「当前毫秒时间戳 × 1000 worker 编号」构成保证每个 worker 的随机序列互不相同。init_worker_phase.lua同时承载了 CubeProxy 副本的 Redis 注册逻辑proxy_registry.setup由CUBE_PROXY_REGISTRY_ENABLE等环境变量控制供 Cube Lifecycle Manager 发现副本。5.2 dev-env修复同步覆盖cube-shim符号链接dev-env 的开发环境同步脚本此前会直接覆盖cube-shim的符号链接布局。v0.2.1 改为将cube-runtime与containerd-shim-cube-rs写入${TOOLBOX_ROOT}/cube-shim/bin从而保留 toolbox 的符号链接结构。5.3 Dockerfile适配仅 HTTPS 的内部镜像源此前构建过程中ca-certificates的安装时机晚于 apt 源切换到内部镜像在仅支持 HTTPS 的镜像源环境下会导致apt update因证书缺失而失败。v0.2.1 将ca-certificates的安装前置到 apt 源切换之前。5.4 IPAM基于net/netip的全面重构Cubelet 与 network-agent 的 IPAM 模块在 v0.2.1 中完成了可靠性重构校验逻辑改用 Go 标准库net/netipCubelet/pkg/allocator 等模块IP ↔ 索引的转换改用encoding/binary.BigEndian消除字节序歧义补充边界检查、安全上限与nil保护文档化保留地址语义新增覆盖表驱动与并发场景的测试。5.5cubemastercli tpl watch阶段化输出模板构建/迁移/镜像任务的 watch 输出从「多行全量状态转储」改为简洁的进度行加终端摘要对 CI 日志更友好。相关实现位于 CubeMaster/cmd/cubemastercli/commands/cubebox/template_watch.go非交互场景管道、--json、--detach/--no-wait走*Plain轮询路径仅在状态变化current ! lastPrinted如fmt.Sprintf(%s/%d/%s, rsp.Status, rsp.Progress, rsp.Message)时打印一行交互终端stdout 与 stdin 均为 TTY启用基于charmbracelet/bubbletea的 TUI支持q/esc/ctrlc退出退出后可template watch --job-id id恢复观察任务以READY/FAILED镜像任务或ready/error构建任务结束并打印完成摘要--json模式下最终以 JSON 输出默认轮询间隔defaultWatchInterval 2 * time.Second可由--interval覆盖。六、工程、示例与 CI 演进6.1 示例重组为独立顶层目录v0.2.1 将示例从CubeAPI/examples/迁出重组为仓库根目录下的独立目录examples其中host-mount与network-policy各自独立成目录并附带 README注释统一翻译为英文。这一调整与 SDK 的推广相配合——examples/code-sandbox-quickstart 提供了 Python 快速上手系列。6.2cube-bench升级为独立 Go 模块并发基准工具cube-bench升格为独立 Go 模块 examples/cube-bench自带Makefile、go.mod代码拆分为runner.go、stats.go、report.go、network_policy.go、ui.go等并配套runner_test.go与main_test.go测试。6.3 Go 工具链对齐与 i18nCubeVS与network-agent升级至 Go 1.24.8cubecli中benchrun.go残留的中文 usage 字符串翻译为英文完成国际化收尾。6.4 构建上下文与镜像源优化Makefile的 builder 镜像改为从./docker目录构建而不是仓库根目录收窄 Docker 构建上下文相关 Dockerfile 见 docker/Dockerfile.builderAlpine 的 APK 软件源从dl-cdn.alpinelinux.org切换到mirrors.tencent.com提升国内构建网络可用性。6.5 CI/DevOps 加固DCO 检查工作流新增 PR 门禁若任一非 merge 提交缺少合法的Signed-off-by尾注则阻止合入GitHub ARC 支持接入自托管 Actions Runner ControllerARCrunner用于内核/软件包构建工作流消除重复 PR 检查多个工作流的push触发范围收窄到master分支PR 校验仅走pull_request事件CI 成本减半sync-to-cnb改用CNB_GIT_PASSWORD密钥。6.6 文档更新部署指南重做PVM 与 bare-metal 被确立为首选部署路径docs/zh 下新增 OpenCloudOS 9 的 PVM 快速部署分步说明pvm-deploy.md新增「About us」中英文页面并接入 VitePress 导航项目 README 增加 XTwitter链接README_zh.md刷新微信/客服二维码修正文档中的 Python 导入路径与架构图间距。七、总结v0.2.1 对 CubeSandbox 演进的意义从源码证据看v0.2.1 的三条主线各有明确落点开发者入口成熟化官方 Python SDK 从示例工具升级为与 OpenAPI 规范对齐的一等公民覆盖生命周期、代码执行、文件系统、网络策略与卷管理配合 12 个示例与 76/76 测试为 AI Agent 集成提供了标准化的 Python 入口运行时性能与正确性内核文件同步的「检查/刷新」拆分消除了每次启动的 SHA256 开销Seccomp 默认动作修正与 stderr 流修复解决了两个可能造成「静默故障」的隐患CubeProxy 的 per-worker PRNG 播种消除了缓存雪崩的同步化风险工程与供应链健康多语言依赖的 CVE 升级、Go 1.24.8 对齐、DCO 门禁与 ARC runner为持续迭代奠定了更稳的底座。对于希望把 CubeSandbox 集成进 Agent 工作流、或正在排查沙箱启动性能与网络行为的开发者建议直接阅读 sdk/python/README.mdSDK 完整 API、Cubelet/pkg/container/pmem/kernel_sync.go启动优化核心实现、agent/rustjail/src/seccomp.rsSeccomp 语义以及 CubeMaster/cmd/cubemastercli/commands/cubebox/template_watch.gowatch 输出重构四份关键文件结合本文各节的命令与配置示例即可快速上手验证。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考