github.com/TencentCloud/CubeSandbox

Go SDK 0.6.0 — auto-generated from go-sdk-v0.6.0

2026.07.24 Release v0.6.0

CubeSandbox 0.6.0 continues to strengthen core capabilities for production deployment and operations.
This release introduces 6 major features along with multiple enhancements and bug fixes. 92 commits from 31 contributors.

🎯 Major Features

Kubernetes Deployment: Deploy Cube Control Plane and Compute Nodes on K8s

Deploy CubeSandbox control-plane components and compute nodes directly onto Tencent Cloud TKE, standard Kubernetes, or k3s clusters via Helm Chart. Perform rolling upgrades, canary releases, and other operations using standard Kubernetes practices. For details, see the Kubernetes Deployment Guide.

::: warning Preview
Kubernetes deployment is currently in preview. Advanced capabilities such as seamless upgrades are still under active development. Feedback is welcome.
:::

E2B-Compatible Volume Framework

Introduces an E2B-compatible Volume framework that lets users plug in custom backend storage while remaining compatible with the E2B standard. Provides four hooks — Create / Destroy / Attach / Detach — and two plugin forms: Binary and RPC. This release includes Volume lifecycle management, sandbox–Volume binding APIs, and supporting SDK and cubemastercli capabilities. For details, see the Volume Plugin Guide.

Template Aliases

Support setting an alias when creating a template, and creating sandboxes by specifying that alias.

Note: Aliases can only be set at template creation time; existing templates cannot have aliases added or changed. Specifying an alias when creating a sandbox is currently supported only in the Python SDK; other SDKs will follow soon.

Configurable Host for Inbound Sandbox Requests

Allow configuring the Host header forwarded to the sandbox (instead of the default <port>-<sandboxId>.<domain>), improving compatibility with Host-based services inside the sandbox. The new network.maskRequestHost parameter can be set when creating a sandbox to specify the Host forwarded to in-sandbox services (for example localhost:${PORT}, which expands to localhost:3000 when accessing port 3000), so applications that rely on Host for routing, validation, or callbacks work correctly.

Compute Node Isolation

Support isolating a compute node at the scheduling layer so operators can log in for maintenance, upgrades, and troubleshooting. After isolation, no new sandboxes are scheduled to that node; existing sandboxes continue to run unaffected.

Isolate a node with cubemastercli node isolate <node-id>, and lift isolation with the unisolate subcommand. For details, see Node Isolation.

CubeOps Operations Service: Decouple Ops & Web Console Logic from CubeAPI

Web console capabilities are split out of the CubeAPI module into a standalone CubeOps service, making CubeAPI lighter and more extensible.

✨ Enhancements

SDK

• Go SDK PTY (#815): Improved interactive terminal capabilities.
• Python SDK X-API-Key coverage (#995): Carry X-API-Key on all request paths.
• Go SDK Connect protocol frames and dataplane fixes (#828, #941): process.Process/Start, exit-0 end event parsing, encode deduplication, and dataplane defect fixes.
• Short sandbox ID prefix resolution (#697): CubeMaster / Cubelet support short ID prefix resolution for easier ops and troubleshooting.

Templates & Storage

• Templates can enable the ivshmem device (#858).
• cubemastercli UX improvements (#891): Better experience for tpl info / delete / redo.
• New cubemastercli volume-related subcommands (#1077).

Lifecycle & Control Plane

• CLM state sync (#956): Stronger sandbox lifecycle state consistency; control-plane pause/resume actions are synced to the dataplane.
• Async CubeProxy state push (#1044): Push with backoff retries to reduce sync-push jitter.
• Skip capacity checks for delete-triggered auto-resume (#1015): Prevent resume on the delete path from being wrongly blocked by capacity checks.
• Schema migration toggle (#1037, #1076): New CUBE_AUTO_MIGRATION env var to skip automatic DB migration at startup for controlled upgrades.
• Support deleting sandboxes that are in the paused state.

Networking & Security Proxy

• CubeEgress MITM leaf certificate SAN (#948): Write subjectAltName on leaf certificates for better TLS verification compatibility.
• Return 403 on traffic token validation failure (#1053): Align with E2B and avoid confusion with other error codes.
• CubeProxy Redis hostname resolver (#714): Correctly resolve Redis hostnames.
• Disable gzip on Connect streams (#1083): Prevent streaming RPCs from being broken by compression.

Deployment & Runtime

• PostgreSQL metadata backend (#674, #1000): CubeMaster DAO layer supports PostgreSQL.
• Switch in-sandbox cgroup from v1 to v2 (#899).
• Cubelet state tmpfs supports dynamic expansion (#1008).

Web UI / CubeOps / Other

• Improved compute-node component version inventory reporting (#1020).
• CubeMaster HTTP APIs now handled with the gin framework (#922).

🐛 Bug Fixes

Lifecycle & Sandbox

• Nested host-mount mount order: apply configuration in user-specified order (#946).
• Periodic compute-node health sync (#730): Avoid inconsistency between health state and the scheduling view.
• WebUI: Converge to a 404 terminal state after sandbox timeout cleanup (#1036); eliminate session invalidation risk (#1048).

Security & Validation

• CVE-2026-24834 / CVE-2026-47243 fixes (#1066).
• Stronger image reference validation (#868): Prevent parameter injection.
• PVM kernel update (#937): Address security vulnerabilities.

📚 Documentation

• Kubernetes deployment guide (#1067 and others): EN/ZH install / architecture / upgrade / FAQ.
• Node isolation guide (#1093).
• Volume plugin guide and COS examples (#997, #1089).
• Component troubleshooting guide (#968).

title: v0.6.0 — 2026.07.24

2026.07.24 Release v0.6.0

CubeSandbox 0.6.0 continues to strengthen core capabilities for production deployment and operations. This release introduces 6 major features along with multiple enhancements and bug fixes. 92 commits from 31 contributors.

🎯 Major Features

Kubernetes Deployment: Deploy Cube Control Plane and Compute Nodes on K8s

Deploy CubeSandbox control-plane components and compute nodes directly onto Tencent Cloud TKE, standard Kubernetes, or k3s clusters via Helm Chart. Perform rolling upgrades, canary releases, and other operations using standard Kubernetes practices. For details, see the Kubernetes Deployment Guide.

::: warning Preview Kubernetes deployment is currently in preview. Advanced capabilities such as seamless upgrades are still under active development. Feedback is welcome. :::

E2B-Compatible Volume Framework

Introduces an E2B-compatible Volume framework that lets users plug in custom backend storage while remaining compatible with the E2B standard. Provides four hooks — Create / Destroy / Attach / Detach — and two plugin forms: Binary and RPC. This release includes Volume lifecycle management, sandbox–Volume binding APIs, and supporting SDK and cubemastercli capabilities. For details, see the Volume Plugin Guide.

Template Aliases

Support setting an alias when creating a template, and creating sandboxes by specifying that alias.

Note: Aliases can only be set at template creation time; existing templates cannot have aliases added or changed. Specifying an alias when creating a sandbox is currently supported only in the Python SDK; other SDKs will follow soon.

Configurable Host for Inbound Sandbox Requests

Allow configuring the Host header forwarded to the sandbox (instead of the default <port>-<sandboxId>.<domain>), improving compatibility with Host-based services inside the sandbox. The new network.maskRequestHost parameter can be set when creating a sandbox to specify the Host forwarded to in-sandbox services (for example localhost:${PORT}, which expands to localhost:3000 when accessing port 3000), so applications that rely on Host for routing, validation, or callbacks work correctly.

Compute Node Isolation

Support isolating a compute node at the scheduling layer so operators can log in for maintenance, upgrades, and troubleshooting. After isolation, no new sandboxes are scheduled to that node; existing sandboxes continue to run unaffected.

Isolate a node with cubemastercli node isolate <node-id>, and lift isolation with the unisolate subcommand. For details, see Node Isolation.

CubeOps Operations Service: Decouple Ops & Web Console Logic from CubeAPI

Web console capabilities are split out of the CubeAPI module into a standalone CubeOps service, making CubeAPI lighter and more extensible.

✨ Enhancements

SDK

• Go SDK PTY (#815): Improved interactive terminal capabilities.
• Python SDK X-API-Key coverage (#995): Carry X-API-Key on all request paths.
• Go SDK Connect protocol frames and dataplane fixes (#828, #941): process.Process/Start, exit-0 end event parsing, encode deduplication, and dataplane defect fixes.
• Short sandbox ID prefix resolution (#697): CubeMaster / Cubelet support short ID prefix resolution for easier ops and troubleshooting.

Templates & Storage

• Templates can enable the ivshmem device (#858).
• cubemastercli UX improvements (#891): Better experience for tpl info / delete / redo.
• New cubemastercli volume-related subcommands (#1077).

Lifecycle & Control Plane

• CLM state sync (#956): Stronger sandbox lifecycle state consistency; control-plane pause/resume actions are synced to the dataplane.
• Async CubeProxy state push (#1044): Push with backoff retries to reduce sync-push jitter.
• Skip capacity checks for delete-triggered auto-resume (#1015): Prevent resume on the delete path from being wrongly blocked by capacity checks.
• Schema migration toggle (#1037, #1076): New CUBE_AUTO_MIGRATION env var to skip automatic DB migration at startup for controlled upgrades.
• Support deleting sandboxes that are in the paused state.

Networking & Security Proxy

• CubeEgress MITM leaf certificate SAN (#948): Write subjectAltName on leaf certificates for better TLS verification compatibility.
• Return 403 on traffic token validation failure (#1053): Align with E2B and avoid confusion with other error codes.
• CubeProxy Redis hostname resolver (#714): Correctly resolve Redis hostnames.
• Disable gzip on Connect streams (#1083): Prevent streaming RPCs from being broken by compression.

Deployment & Runtime

• PostgreSQL metadata backend (#674, #1000): CubeMaster DAO layer supports PostgreSQL.
• Switch in-sandbox cgroup from v1 to v2 (#899).
• Cubelet state tmpfs supports dynamic expansion (#1008).

Web UI / CubeOps / Other

• Improved compute-node component version inventory reporting (#1020).
• CubeMaster HTTP APIs now handled with the gin framework (#922).

🐛 Bug Fixes

Lifecycle & Sandbox

• Nested host-mount mount order: apply configuration in user-specified order (#946).
• Periodic compute-node health sync (#730): Avoid inconsistency between health state and the scheduling view.
• WebUI: Converge to a 404 terminal state after sandbox timeout cleanup (#1036); eliminate session invalidation risk (#1048).

Security & Validation

• CVE-2026-24834 / CVE-2026-47243 fixes (#1066).
• Stronger image reference validation (#868): Prevent parameter injection.
• PVM kernel update (#937): Address security vulnerabilities.

📚 Documentation

• Kubernetes deployment guide (#1067 and others): EN/ZH install / architecture / upgrade / FAQ.
• Node isolation guide (#1093).
• Volume plugin guide and COS examples (#997, #1089).
• Component troubleshooting guide (#968).

title: v0.6.0 — 2026.07.24

2026.07.24 Release v0.6.0

CubeSandbox 0.6.0 面向生产部署与运维持续增强关键能力。 当前版本引入了 6 个核心特性以及多个功能增强与问题修复。共计 92 个提交，来自 31 位贡献者。

🎯 核心特性

K8s 部署：支持在 K8s 中部署 Cube 的控制面组件及计算节点

支持通过 Helm Chart，将 CubeSandbox 的控制面组件和计算节点直接部署到腾讯云 TKE、标准 K8s 或 k3s 集群中。可通过标准 K8s 运维方式执行组件滚动升级、灰度发布等操作。关于 K8s 部署的详细信息请参考 K8s 部署指南。

::: warning 预览版本 K8s 部署功能当前处于预览阶段，平滑升级等高级功能仍在积极开发中，欢迎体验和反馈。 :::

兼容 E2B 标准的 Volume 框架

新引入兼容 E2B 标准的 Volume 框架，在兼容 E2B 标准的前提下允许用户以插件形式自定义后端存储方案。提供 Create/Destroy/Attach/Detach 四个 HOOK 点，以及 Binary/RPC 两种插件形态。当前版本提供 Volume 生命周期管理、沙箱绑定 Volume 相关 API、配套 SDK 与 cubemastercli 能力。详细信息请参考 Volume 插件文档。

支持模板别名

支持在创建模板时为模板设置别名，并通过指定别名创建沙箱。

说明：别名只能在创建模板时设置，不支持为已有模板修改别名。当前仅 Python SDK 支持指定别名创建沙箱，其他 SDK 后续即将支持。

支持配置沙箱入向请求的 Host

允许配置请求转发至沙箱时的 Host（而非默认的 <port>-<sandboxId>.<domain>），更好地兼容沙箱内基于 Host 的服务。新增 network.maskRequestHost 参数，可在创建沙箱时指定转发给沙箱内服务的 Host（例如 localhost:${PORT}，访问 3000 端口时展开为 localhost:3000），以便兼容依赖 Host 做路由、校验或回调的应用。

支持计算节点隔离

支持从调度层面“隔离”某个计算节点，便于运维时登录节点进行维护、升级和排查问题。计算节点被隔离后，将不会调度新的沙箱到该节点，存量沙箱运行不受影响。

可通过 cubemastercli node isolate <node-id> 进行节点隔离，通过 unisolate 子命令解除隔离，详细用法请参考 隔离节点。

CubeOps 运维服务：将运维 & Web 控制台逻辑从 CubeAPI 模块中解耦

Web 控制台相关能力从 CubeAPI 模块中剥离，独立为 CubeOps 服务，使 CubeAPI 更轻量、更具可扩展性。

✨ 功能增强

SDK

• Go SDK PTY (#815)：优化交互式终端能力。
• Python SDK X-API-Key 认证补齐 (#995)：全路径请求携带 X-API-Key。
• Go SDK Connect 协议帧与数据面修复 (#828, #941)：process.Process/Start、exit-0 end 事件解析，以及 encode 去重与数据面缺陷修复。
• 短沙箱 ID 前缀解析 (#697)：CubeMaster / Cubelet 支持短 ID 前缀解析，运维与排障更方便。

模板与存储

• 模板支持启用 ivshmem 设备 (#858)。
• cubemastercli 用户体验优化 (#891)：tpl info / delete / redo 命令体验优化。
• 新增 cubemastercli volume 相关子命令 (#1077)。

生命周期与控制面

• CLM 状态同步 (#956)：增强沙箱生命周期状态一致性，控制面的暂停/恢复动作会同步给数据面。
• CubeProxy 状态推送异步化 (#1044)：带退避重试，降低同步推送抖动。
• 删除触发的 auto-resume 跳过资源容量检查 (#1015)：避免 delete 路径上的 resume 被容量检查误拦。
• Schema 迁移开关 (#1037, #1076)：新增 CUBE_AUTO_MIGRATION 环境变量，可跳过启动期数据库自动迁移，便于受控升级。
• 支持删除处于暂停状态的沙箱。

网络与安全代理

• CubeEgress MITM 叶子证书 SAN (#948)：叶子证书写入 subjectAltName，改善 TLS 校验兼容性。
• Traffic token 校验失败返回 403 (#1053)：对齐 E2B，避免与其他错误码混淆。
• CubeProxy Redis hostname resolver (#714)：正确解析 Redis 主机名。
• Connect 流禁用 gzip (#1083)：避免流式 RPC 被压缩破坏。

部署与运行时

• PostgreSQL 元数据后端 (#674, #1000)：CubeMaster DAO 层支持 PostgreSQL。
• 沙箱内从 cgroup v1 改为 cgroup v2 (#899)。
• Cubelet state tmpfs 支持动态扩容 (#1008)。

Web UI / CubeOps / 其他

• 计算节点组件版本清单上报优化 (#1020)。
• CubeMaster HTTP 接口改为使用 gin 框架处理 (#922)。

🐛 Bug 修复

生命周期与沙箱

• 嵌套 host-mount 挂载顺序：按用户指定顺序进行配置 (#946)。
• 计算节点健康状态周期性同步 (#730)：避免健康状态与调度视图不一致。
• WebUI：沙箱超时清理后收敛 404 终态 (#1036)，消除会话失效风险 (#1048)。

安全与校验

• CVE-2026-24834 / CVE-2026-47243 修复 (#1066)。
• 镜像引用校验强化 (#868)：防止参数注入。
• PVM kernel 内核更新 (#937)：解决安全漏洞。

📚 新增文档

• Kubernetes 部署指南（#1067 等）：中英文安装 / 架构 / 升级 / FAQ。
• 节点隔离指南 (#1093)。
• Volume 插件指南与 COS 示例 (#997, #1089)。
• 组件排障指引 (#968)。

chore: bump image tags from v0.6.0-rc1 to v0.6.0-rc3 (#1134)

Bump all image tag references across Makefiles, Helm chart values, docs,
and deployment scripts from v0.6.0-rc1 to v0.6.0-rc3.

## Changes

- Updated default `IMAGE_TAG` in CubeEgress, CubeProxy, and
cube-lifecycle-manager Makefiles
- Updated all image tag references in
`deploy/kubernetes/chart/values.yaml`
- Updated tag references in docs (Kubernetes guide, Terraform deploy
guide, FAQ)
- Updated deployment scripts and Terraform configs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Signed-off-by: jinlong <[email protected]>

fix(volume): CubeMaster/Cubelet mixed-version volumeMounts compatibil…

…ity (#1123)

## Summary

- **Goal:** keep CubeMaster and Cubelet **new/old versions mutually
compatible** when sandboxes use plugin `volumeMounts` (rolling upgrades
/ mixed clusters).
- **Bug:** newer CubeMaster injected plugin volumes as
`EmptyDir(StorageMediumDefault)` placeholders plus
`plugin-volume-sources`. Older Cubelets have no plugin skip path and
treat every Default EmptyDir as a second rootfs derive
(`sb-<id>-rootfs-gen0`), which collides with `cube_rootfs_rw` and fails
create with `cubecow object already exists` (e.g. CubeAPI `130545`).
- **Fix (CubeMaster):** stop injecting Default EmptyDir for plugin
volumes; wire an empty `VolumeSource` name-only entry. New Cubelets
still Attach via the Volume Plugin framework + annotation; older
Cubelets skip the empty source in `prepareDefaultMedium` and no longer
collide on rootfs.
- **Defense (Cubelet):** keep `isPluginVolume` skip so a CubeMaster that
still sends Default EmptyDir placeholders does not break a newer
Cubelet.

### Compatibility matrix (intended)

| CubeMaster | Cubelet | Plugin volumeMounts create |
|---|---|---|
| new (this PR) | old | OK — no Default EmptyDir placeholder |
| new (this PR) | new | OK — annotation + plugin Attach |
| old (EmptyDir placeholder) | new | OK — Cubelet skips plugin EmptyDir
|
| old (no volume plugin) | old | N/A — volumes API not used |

## Test plan

- [x] Unit: `CubeMaster/pkg/service/sandbox` plugin volume annotation
test asserts no Default EmptyDir on the wire
- [x] Smoke: create sandbox with COS `volumeMounts` succeeds after
deploying fixed CubeMaster
- [x] E2E: `examples/volume/tests/e2e-volume-lifecycle.sh` with
`DRIVER=cos` and `DRIVER=cos-rpc`
- [x] SDK examples: `verify_volume.py` (cos / cos-rpc) and
`volume_complex_concurrent_test.py`

Assisted-by: Cursor:Composer

Made with [Cursor](https://cursor.com)

Signed-off-by: ls-ggg <[email protected]>
Co-authored-by: ls-ggg <[email protected]>
Co-authored-by: Cursor <[email protected]>

v0.6.0-rc1

d7eb3b2

This commit was created on GitHub.com and signed with GitHub’s verified signature .

GPG key ID: B5690EEEBB952194

Verified Learn about vigilant mode .

2026.07.10 Release v0.5.1

CubeSandbox 0.5.1 is a production follow-up to 0.5.0, hardening AutoPause, ARM64, and cluster deployment for real-world scale. Headline items: a standalone cube-lifecycle-manager control-plane service (extracted from the CubeProxy sidecar so CubeProxy can scale horizontally), a three-value timeout semantics refactor with server-side defaults and NEVER_TIMEOUT, and host-mount path allowlisting to close arbitrary host bind-mounts. The release also fixes ARM64 64 KB page snapshot integrity and substantially improves egress policy / TAP recycle reliability. 59 commits from 18 contributors.

🎯 Major Features

cube-lifecycle-manager: Standalone AutoPause Coordinator

Splits the former in-image cube-proxy-sidecar into a standalone control-plane service — cube-lifecycle-manager (CLM) — so CubeProxy can run multiple replicas without a single-instance sidecar bottleneck.

• Standalone deploy: CLM is wired into cube-sandbox-control.target; one-click and TencentCloud Terraform deployments both include it.
• Redis service discovery: each CubeProxy replica registers its admin endpoint in Redis; CLM discovers live replicas and coordinates auto-pause / auto-resume with no static replica list.
• Protocol compatibility: wire protocol, Redis schema, and SDK behavior are unchanged; existing AutoPause / AutoResume semantics are preserved.
• TencentCloud Terraform (#814): control plane gains a cube-lifecycle-manager Deployment; supports TENCENTCLOUD_CUBE_PROXY_REPLICAS multi-replica plus CLM replica count / discovery refresh / admin token knobs.

Three-Value Timeout Semantics + Server-Side Default

Unifies sandbox idle-timeout semantics (E2B-aligned) and moves the "not set" vs "explicit default" decision from SDK / CubeAPI down to CubeMaster.

• SDK: Go / Python CreateOptions.Timeout become optional pointers; Create / Connect / Resume no longer inject a hard-coded default. Expose NeverTimeout / NEVER_TIMEOUT sentinels.
• CubeAPI / CubeMaster: timeout fields are Option / *int, preserving "unset"; EndAt follows three-value rules (-1 → no deadline).
• RPC deadline decoupled from idle TTL: new create_timeout_insec (default 300s) bounds only the create/scheduling RPC.
• CLM sweeper: skip reclaim when TimeoutSeconds < 0; immediate reclaim at == 0; legacy nil falls back to DefaultIdleTimeout.
• Runtime adjustment: Python / Go SDKs add set_timeout() / SetTimeout(), including NEVER_TIMEOUT (#743, #850). Web UI can pass timeout on sandbox create (#798).

Host-Mount Path Allowlist Hardening

Host-mount previously accepted any absolute path, letting sandboxes bind-mount arbitrary host directories. Paths are now restricted to configurable prefixes (default /data/shared/), with filepath.Clean neutralizing .. traversal; / is explicitly forbidden in config (#756).

Persistent-storage docs updated (path restriction, permissions, multi-tenant isolation, multi-node shared storage); examples aligned to the default prefix (#768).

✨ Enhancements

SDK

• Node.js / TypeScript SDK (preview) (#792): adds @cubesandbox/sdk aligned with the Python / Go surface; still under validation — use with caution in production.
• Python / Go set_timeout (#743, #850): E2B-aligned; CubeAPI / CubeMaster accept -1 (NEVER_TIMEOUT) and reject other negatives.
• Go SDK allowOut guard alignment (#802): AllowPublicTraffic=false is no longer treated as deny-all; matches CubeAPI (deny-all only when AllowInternetAccess=false or denyOut contains 0.0.0.0/0).

Networking & Egress

• CubeEgress credential injection on plain HTTP (#726): allows inject against HTTP-only upstreams. The security boundary is that sandbox code never sees the secret, not that egress→upstream must be TLS.
• CubeEgress transparent-proxy IP from sandbox CIDR (#851): no longer hard-codes 192.168.0.1; derives the first usable IP from CUBE_SANDBOX_NETWORK_CIDR so custom sandbox networks get correct TPROXY / OpenResty listen addresses.
• Minimum TTL for DNS-learned egress entries: clamp learned allow entries to ≥300s so short DNS TTLs do not cause reconnect denials.
• Skip policy re-check for established CubeEgress sessions: CubeVS skips egress policy re-evaluation for existing TCP sessions so DNS expiry does not break live connections; policy check folded into create_nat_session with per-session caching.
• Always replay default deny on replace: replace / flush always replays private / link-local default deny entries so create and replace policy shapes stay consistent.

Deployment & Installer

• CubeProxy pre-published multi-arch images (#849): one-click pulls TCR multi-arch images instead of building on-host; supports MIRROR=cn|int and airgap local-cache fallback.
• Component image release pipeline (#795): release-docker-images.yml pushes multi-arch component images to GHCR / TCR; bump-image.sh is the single source of truth for hard-coded tags.
• CubeMaster Dockerfile (#813, #824): unified Docker build args / context and ARG scoping fixes; CubeAPI Dockerfile switched to single-shot build with safety gates (#854).
• One-click dnsmasq fallback (#740): optional script-owned dnsmasq when systemd-resolved is absent and NetworkManager's dnsmasq plugin never spawns, restoring cube.app resolution.
• Anchored cubelet config patching (#776): sed replacements anchored at line start so updating CUBE_SANDBOX_NETWORK_CIDR cannot rewrite an empty cube_router_cidr.

Web UI / AgentHub / Other

• CubeAPI lifecycle snake_case (#772): accepts Python-style lifecycle.on_timeout / lifecycle.auto_resume, avoiding silent fallback to kill / no-resume.
• AgentHub OpenClaw bind=lan (#769): force gateway bind to lan so cube-proxy can reach it via tap IP (auto could resolve to loopback).
• ARM64 runtime hardening (#807): dirty-bitmap granularity uses host page size (fixes severely incomplete snapshots on 64 KB pages and 200% CPU on restore); aarch64 vCPU falls back to PMU-less init when the host lacks PMUv3.
• Dev-env QEMU 10.x (#713): explicit -drive if=none + -device virtio-blk-pci fixes empty-drive errors on QEMU 10.2.2+.

🐛 Bug Fixes

Lifecycle & Sandboxes

• Idempotent resume (#817): already-Running sandboxes return an "already in target state" signal (treated as success by CLM), distinct from truly non-resumable states.
• 404 on delete missing sandbox (#759): CubeAPI / CubeMaster map missing-sandbox deletes to NotFound.
• Stable sandbox list order (#762): sort by creation time descending with SandboxID tie-break so WebUI / SDK refreshes no longer reshuffle.
• Preserve template network rules & resource defaults (#581): keep egress rules when creating templates from images; retain the first CPU/memory validation error; request-side overrides win under first-match-wins.

Networking & Data Plane

• Safe TAP recycle (network-agent): do not return TAPs to the pool until cleanup and pool prep succeed; failed cleanup keeps residual policy off the reusable pool; clear policy / DNS allow state before reuse to prevent cross-sandbox leakage.
• Go SDK envd port (#821): envd RPCs (commands / files / filesystem / PTY) route to port 49983 instead of Jupyter 49999; only RunCode / /execute stays on Jupyter.

Other

• Example host-mount paths (#768): examples and docs use /data/shared/... to match the default allowlist.

📚 Documentation

• ARM64 support announcement blog (#866): bilingual InfoQ-style post on the joint Arm multi-arch effort.
• Pi Agent integration guide (#701): bilingual docs + runnable example (pause/resume, network policy, credential injection).
• Lifecycle / quota docs (#739): ARM64 install notes and lifecycle quota documentation.
• Persistent storage guide (#756): host-mount path restriction, permissions, multi-tenant isolation, multi-node shared storage.
• Roadmap (#731): roadmap added to README and docs site.
• v0.5.0 release materials (#770, #781): release blog and feature copy updates; Quickstart notes Multi-Arch image availability (#806).
• Dev skills & doc hygiene (#788, #789): Claude Code run-dev skill; i18n sync checks and change-driven doc audit rules.

⚙️ Engineering Improvements

• Platform-suffixed versions in matrix checks (#747).
• PVM guest build trigger tightened (#819): only on version tags.
• Image tag bumps: one-click / Terraform defaults synced through v0.5.1-rc* candidates (#826, #867).
• Python SDK version bump to 0.5.0 (#818).
• CubeAPI dead-code cleanup (#796) and other small engineering tidy-ups.

Note: Web Example Center (#615) was merged and immediately reverted (#778); it is not part of this release.

title: v0.5.1 — 2026.07.10

2026.07.10 Release v0.5.1

CubeSandbox 0.5.1 is a production follow-up to 0.5.0, hardening AutoPause, ARM64, and cluster deployment for real-world scale. Headline items: a standalone cube-lifecycle-manager control-plane service (extracted from the CubeProxy sidecar so CubeProxy can scale horizontally), a three-value timeout semantics refactor with server-side defaults and NEVER_TIMEOUT, and host-mount path allowlisting to close arbitrary host bind-mounts. The release also fixes ARM64 64 KB page snapshot integrity and substantially improves egress policy / TAP recycle reliability. 59 commits from 18 contributors.

🎯 Major Features

cube-lifecycle-manager: Standalone AutoPause Coordinator

Splits the former in-image cube-proxy-sidecar into a standalone control-plane service — cube-lifecycle-manager (CLM) — so CubeProxy can run multiple replicas without a single-instance sidecar bottleneck.

• Standalone deploy: CLM is wired into cube-sandbox-control.target; one-click and TencentCloud Terraform deployments both include it.
• Redis service discovery: each CubeProxy replica registers its admin endpoint in Redis; CLM discovers live replicas and coordinates auto-pause / auto-resume with no static replica list.
• Protocol compatibility: wire protocol, Redis schema, and SDK behavior are unchanged; existing AutoPause / AutoResume semantics are preserved.
• TencentCloud Terraform (#814): control plane gains a cube-lifecycle-manager Deployment; supports TENCENTCLOUD_CUBE_PROXY_REPLICAS multi-replica plus CLM replica count / discovery refresh / admin token knobs.

Three-Value Timeout Semantics + Server-Side Default

Unifies sandbox idle-timeout semantics (E2B-aligned) and moves the "not set" vs "explicit default" decision from SDK / CubeAPI down to CubeMaster.

• SDK: Go / Python CreateOptions.Timeout become optional pointers; Create / Connect / Resume no longer inject a hard-coded default. Expose NeverTimeout / NEVER_TIMEOUT sentinels.
• CubeAPI / CubeMaster: timeout fields are Option / *int, preserving "unset"; EndAt follows three-value rules (-1 → no deadline).
• RPC deadline decoupled from idle TTL: new create_timeout_insec (default 300s) bounds only the create/scheduling RPC.
• CLM sweeper: skip reclaim when TimeoutSeconds < 0; immediate reclaim at == 0; legacy nil falls back to DefaultIdleTimeout.
• Runtime adjustment: Python / Go SDKs add set_timeout() / SetTimeout(), including NEVER_TIMEOUT (#743, #850). Web UI can pass timeout on sandbox create (#798).

Host-Mount Path Allowlist Hardening

Host-mount previously accepted any absolute path, letting sandboxes bind-mount arbitrary host directories. Paths are now restricted to configurable prefixes (default /data/shared/), with filepath.Clean neutralizing .. traversal; / is explicitly forbidden in config (#756).

Persistent-storage docs updated (path restriction, permissions, multi-tenant isolation, multi-node shared storage); examples aligned to the default prefix (#768).

✨ Enhancements

SDK

• Node.js / TypeScript SDK (preview) (#792): adds @cubesandbox/sdk aligned with the Python / Go surface; still under validation — use with caution in production.
• Python / Go set_timeout (#743, #850): E2B-aligned; CubeAPI / CubeMaster accept -1 (NEVER_TIMEOUT) and reject other negatives.
• Go SDK allowOut guard alignment (#802): AllowPublicTraffic=false is no longer treated as deny-all; matches CubeAPI (deny-all only when AllowInternetAccess=false or denyOut contains 0.0.0.0/0).

Networking & Egress

• CubeEgress credential injection on plain HTTP (#726): allows inject against HTTP-only upstreams. The security boundary is that sandbox code never sees the secret, not that egress→upstream must be TLS.
• CubeEgress transparent-proxy IP from sandbox CIDR (#851): no longer hard-codes 192.168.0.1; derives the first usable IP from CUBE_SANDBOX_NETWORK_CIDR so custom sandbox networks get correct TPROXY / OpenResty listen addresses.
• Minimum TTL for DNS-learned egress entries: clamp learned allow entries to ≥300s so short DNS TTLs do not cause reconnect denials.
• Skip policy re-check for established CubeEgress sessions: CubeVS skips egress policy re-evaluation for existing TCP sessions so DNS expiry does not break live connections; policy check folded into create_nat_session with per-session caching.
• Always replay default deny on replace: replace / flush always replays private / link-local default deny entries so create and replace policy shapes stay consistent.

Deployment & Installer

• CubeProxy pre-published multi-arch images (#849): one-click pulls TCR multi-arch images instead of building on-host; supports MIRROR=cn|int and airgap local-cache fallback.
• Component image release pipeline (#795): release-docker-images.yml pushes multi-arch component images to GHCR / TCR; bump-image.sh is the single source of truth for hard-coded tags.
• CubeMaster Dockerfile (#813, #824): unified Docker build args / context and ARG scoping fixes; CubeAPI Dockerfile switched to single-shot build with safety gates (#854).
• One-click dnsmasq fallback (#740): optional script-owned dnsmasq when systemd-resolved is absent and NetworkManager's dnsmasq plugin never spawns, restoring cube.app resolution.
• Anchored cubelet config patching (#776): sed replacements anchored at line start so updating CUBE_SANDBOX_NETWORK_CIDR cannot rewrite an empty cube_router_cidr.

Web UI / AgentHub / Other

• CubeAPI lifecycle snake_case (#772): accepts Python-style lifecycle.on_timeout / lifecycle.auto_resume, avoiding silent fallback to kill / no-resume.
• AgentHub OpenClaw bind=lan (#769): force gateway bind to lan so cube-proxy can reach it via tap IP (auto could resolve to loopback).
• ARM64 runtime hardening (#807): dirty-bitmap granularity uses host page size (fixes severely incomplete snapshots on 64 KB pages and 200% CPU on restore); aarch64 vCPU falls back to PMU-less init when the host lacks PMUv3.
• Dev-env QEMU 10.x (#713): explicit -drive if=none + -device virtio-blk-pci fixes empty-drive errors on QEMU 10.2.2+.

🐛 Bug Fixes

Lifecycle & Sandboxes

• Idempotent resume (#817): already-Running sandboxes return an "already in target state" signal (treated as success by CLM), distinct from truly non-resumable states.
• 404 on delete missing sandbox (#759): CubeAPI / CubeMaster map missing-sandbox deletes to NotFound.
• Stable sandbox list order (#762): sort by creation time descending with SandboxID tie-break so WebUI / SDK refreshes no longer reshuffle.
• Preserve template network rules & resource defaults (#581): keep egress rules when creating templates from images; retain the first CPU/memory validation error; request-side overrides win under first-match-wins.

Networking & Data Plane

• Safe TAP recycle (network-agent): do not return TAPs to the pool until cleanup and pool prep succeed; failed cleanup keeps residual policy off the reusable pool; clear policy / DNS allow state before reuse to prevent cross-sandbox leakage.
• Go SDK envd port (#821): envd RPCs (commands / files / filesystem / PTY) route to port 49983 instead of Jupyter 49999; only RunCode / /execute stays on Jupyter.

Other

• Example host-mount paths (#768): examples and docs use /data/shared/... to match the default allowlist.

📚 Documentation

• ARM64 support announcement blog (#866): bilingual InfoQ-style post on the joint Arm multi-arch effort.
• Pi Agent integration guide (#701): bilingual docs + runnable example (pause/resume, network policy, credential injection).
• Lifecycle / quota docs (#739): ARM64 install notes and lifecycle quota documentation.
• Persistent storage guide (#756): host-mount path restriction, permissions, multi-tenant isolation, multi-node shared storage.
• Roadmap (#731): roadmap added to README and docs site.
• v0.5.0 release materials (#770, #781): release blog and feature copy updates; Quickstart notes Multi-Arch image availability (#806).
• Dev skills & doc hygiene (#788, #789): Claude Code run-dev skill; i18n sync checks and change-driven doc audit rules.

⚙️ Engineering Improvements

• Platform-suffixed versions in matrix checks (#747).
• PVM guest build trigger tightened (#819): only on version tags.
• Image tag bumps: one-click / Terraform defaults synced through v0.5.1-rc* candidates (#826, #867).
• Python SDK version bump to 0.5.0 (#818).
• CubeAPI dead-code cleanup (#796) and other small engineering tidy-ups.

Note: Web Example Center (#615) was merged and immediately reverted (#778); it is not part of this release.

title: v0.5.1 — 2026.07.10

2026.07.10 Release v0.5.1

CubeSandbox 0.5.1 是一次面向生产落地的跟进发布，在 0.5.0 的 AutoPause / ARM64 / 集群部署基线上补齐关键能力与稳定性。本版本重点包括：cube-lifecycle-manager 独立控制面服务（从 CubeProxy sidecar 拆出，支持 CubeProxy 多副本扩展）、三值 timeout 语义重构（服务端默认 + NEVER_TIMEOUT / 立即超时 / TTL），以及 host-mount 路径白名单安全加固。同时修复 ARM64 64KB 页场景下的快照完整性问题，并显著提升出向策略与 TAP 回收的可靠性。共计 59 个提交，来自 18 位贡献者。

🎯 核心特性

cube-lifecycle-manager：AutoPause 协调器独立化

将原先内嵌在 CubeProxy 镜像中的 cube-proxy-sidecar 拆分为独立控制面服务 cube-lifecycle-manager（CLM），使 CubeProxy 可多副本水平扩展，而不再依赖单实例 sidecar。

• 独立部署：CLM 作为独立服务接入 cube-sandbox-control.target；一键安装与腾讯云 Terraform 部署均已纳入。
• Redis 服务发现：CubeProxy 各副本将 admin endpoint 注册到 Redis；CLM 通过注册表发现全部在线副本并协调 auto-pause / auto-resume，无需静态配置副本列表。
• 协议兼容：Wire protocol、Redis schema、SDK 行为保持不变；现有 AutoPause / AutoResume 语义不受影响。
• 腾讯云 Terraform (#814)：控制面新增 cube-lifecycle-manager Deployment；支持 TENCENTCLOUD_CUBE_PROXY_REPLICAS 多副本，以及 CLM 副本数 / discovery refresh / admin token 等配置项。

三值 Timeout 语义 + 服务端默认

统一沙箱 idle timeout 语义，与 E2B 对齐，并将「未设置」与「显式默认值」区分开——默认超时决策从 SDK / CubeAPI 下沉到 CubeMaster。

• SDK：Go / Python 的 CreateOptions.Timeout 改为可选指针；Create / Connect / Resume 不再自动填入硬编码默认值。暴露 NeverTimeout / NEVER_TIMEOUT sentinel。
• CubeAPI / CubeMaster：timeout 字段改为 Option / *int，透传「未设置」；EndAt 按三值语义计算（-1 → 无截止时间）。
• RPC 截止与 idle TTL 解耦：新增 create_timeout_insec（默认 300s）仅约束创建调度 RPC，不再与沙箱 idle TTL 混用。
• CLM sweeper：TimeoutSeconds < 0 跳过回收；== 0 立即回收；旧数据 nil 回退到 DefaultIdleTimeout。
• 运行时调整：Python / Go SDK 新增 set_timeout() / SetTimeout()，支持将运行中沙箱改为 NEVER_TIMEOUT (#743, #850)。Web UI 创建沙箱时可传入 timeout (#798)。

Host-Mount 路径白名单安全加固

此前 host-mount 接受任意绝对路径，沙箱可 bind-mount 宿主机任意目录。现改为可配置前缀白名单（默认 /data/shared/），并用 filepath.Clean 消除 .. 路径穿越；配置中显式禁止根路径 / (#756)。

配套更新持久化存储指南（路径限制、权限、多租户隔离、多节点共享存储），示例路径对齐默认前缀 (#768)。

✨ 功能增强

SDK

• Node.js / TypeScript SDK（预览） (#792)：新增 @cubesandbox/sdk，API 面与 Python / Go 对齐；尚在验证中，生产使用请谨慎。
• Python / Go set_timeout (#743, #850)：对齐 E2B API；CubeAPI / CubeMaster 接受 -1（NEVER_TIMEOUT），拒绝其他负值。
• Go SDK allowOut 校验对齐 (#802)：不再将 AllowPublicTraffic=false 误判为 deny-all；与 CubeAPI 一致，仅在 AllowInternetAccess=false 或 denyOut 含 0.0.0.0/0 时视为全拒绝。

网络与 Egress

• CubeEgress 明文 HTTP 凭据注入 (#726)：允许对纯 HTTP 上游注入凭据。安全边界是沙箱代码看不到密钥，而非要求 egress→upstream 必须 TLS。
• CubeEgress 透明代理 IP 随 CIDR 推导 (#851)：不再硬编码 192.168.0.1；从 CUBE_SANDBOX_NETWORK_CIDR 取网段首个可用 IP，自定义沙箱网段时 TPROXY / OpenResty 监听地址正确。
• DNS 学习条目最小 TTL：对 DNS 学到的 egress allow 条目施加最小 300s TTL，避免短 TTL 导致重连被误拒。
• 已建立会话跳过策略重检：CubeVS 对已存在的 CubeEgress TCP 会话跳过 egress 策略重检，避免 DNS 记录过期打断活跃连接；策略检查折叠进 create_nat_session，按会话缓存结果。
• 默认 deny 基线统一回放：replace / flush 路径始终回放私网 / link-local 默认 deny 条目，create 与 replace 策略形态一致。

部署与安装器

• CubeProxy 预发布多架构镜像 (#849)：一键部署改为从 TCR 拉取预构建 multi-arch 镜像，不再本机构建；支持 MIRROR=cn|int 与 airgap 本地缓存回退。
• 组件镜像发布流水线 (#795)：新增 release-docker-images.yml，向 GHCR / TCR 推送 multi-arch 组件镜像；bump-image.sh 统一管理硬编码镜像标签。
• CubeMaster Dockerfile (#813, #824)：统一 Docker build args / context，修复 ARG 作用域；CubeAPI Dockerfile 改为单次构建并加安全门禁 (#854)。
• 一键 DNS dnsmasq 回退 (#740)：无 systemd-resolved 且 NetworkManager dnsmasq 插件未拉起子进程时，可选由脚本自管 dnsmasq，避免 cube.app 解析失败。
• Cubelet 配置 patch 锚定 (#776)：sed 替换锚定行首，避免改 CUBE_SANDBOX_NETWORK_CIDR 时误改空的 cube_router_cidr。

Web UI / AgentHub / 其他

• CubeAPI lifecycle snake_case (#772)：接受 lifecycle.on_timeout / lifecycle.auto_resume 等 Python 风格字段名，避免静默落到 kill / 无 resume。
• AgentHub OpenClaw bind=lan (#769)：强制 gateway 绑定 lan，确保 cube-proxy 可通过 tap IP 访问，避免 auto 落到 loopback。
• ARM64 运行时加固 (#807)：dirty bitmap 粒度改用宿主机页大小（修复 64KB 页上快照严重不完整、恢复后 200% CPU）；aarch64 vCPU 在无 PMUv3 主机上自动回退无 PMU 初始化。
• 开发环境 QEMU 10.x (#713)：显式 -drive if=none + -device virtio-blk-pci，修复 QEMU 10.2.2+ 的空 drive 错误。

🐛 Bug 修复

生命周期与沙箱

• Resume 幂等 (#817)：沙箱已处于 Running 时返回可识别的「已在目标状态」信号（CLM 视为成功），不再与真正不可 resume 的状态混为同一错误。
• 删除不存在沙箱返回 404 (#759)：CubeAPI / CubeMaster 对缺失沙箱的 delete 映射为 NotFound。
• 沙箱列表稳定排序 (#762)：按创建时间降序 + SandboxID 打破平局，避免 WebUI / SDK 刷新时顺序跳动。
• 模板网络规则与资源默认值保留 (#581)：从镜像创建模板时保留 egress 规则；CPU/内存同时超限时保留首个校验错误；请求侧 override 在 first-match-wins 下优先生效。

网络与数据面

• TAP 回收安全（network-agent）：清理与池准备完成前不归还 TAP；失败清理路径不把带残留策略的 TAP 放回池；复用前清理策略 / DNS allow 状态，避免跨沙箱泄漏。
• Go SDK envd 端口 (#821)：envd RPC（commands / files / filesystem / PTY）改走 49983，不再误打到 Jupyter 端口 49999；仅 RunCode//execute 仍走 Jupyter。

其他

• 示例 host-mount 路径对齐 (#768)：示例与文档路径改为 /data/shared/...，匹配默认白名单。

📚 文档

• ARM64 支持公告博客 (#866)：中英文 InfoQ 风格发布稿，介绍与 Arm 联合推进的多架构能力。
• Pi Agent 集成指南 (#701)：中英文集成文档 + 可运行示例（pause/resume、网络策略、凭据注入）。
• 生命周期 / 配额文档 (#739)：补充 ARM64 安装说明与 lifecycle 配额相关文档。
• 持久化存储指南 (#756)：host-mount 路径限制、权限、多租户隔离、多节点共享存储。
• Roadmap (#731)：README 与文档站增加 roadmap。
• v0.5.0 发布相关 (#770, #781)：发布博客与特性描述更新；Quickstart 注明 Multi-Arch 镜像可用性 (#806)。
• 开发技能与文档规范 (#788, #789)：Claude Code run-dev skill；i18n 同步检查与变更驱动文档审计规则。

⚙️ 工程改进

• 版本矩阵允许平台后缀 (#747)：版本检查兼容带平台后缀的版本号。
• PVM guest 构建触发收紧 (#819)：仅在 version tag 时触发 pvm-guest 构建。
• 镜像标签 bump：发布候选过程中多次同步 one-click / Terraform 默认镜像至 v0.5.1-rc* (#826, #867)。
• Python SDK 版本 bump 至 0.5.0 (#818)。
• CubeAPI 死代码清理 (#796) 及其他小范围工程整理。

说明：Web Example Center（#615）曾合入后随即回滚（#778），不包含在本版本交付中。

title: v0.5.0 — 2026.07.03

2026.07.03 Release v0.5.0

CubeSandbox 0.5.0 introduces AutoPause/AutoResume, a platform-level sandbox lifecycle automation that transparently suspends idle sandboxes and resumes them on-demand on the next dataplane request. This release also delivers ARM64 (aarch64) native support across the entire stack — from hypervisor to CI/CD — a TencentCloud Terraform cluster deployer for production-grade one-click deployment, and network security hardening with per-sandbox traffic access tokens, CubeEgress fail-closed bootstrap, and policy-routing egress. Additional highlights include a pure-Go native rootfs export pipeline that bypasses Docker, skopeo, and umoci entirely, a snapshot runtime locking refactor to eliminate high-concurrency deadlocks, image uid/gid preservation fixes for non-root container images, E2B SDK alignment with complete filesystem and PTY APIs, and a one-click upgrade mode with three-way config merge. 116 commits from 26 contributors.

🎯 Major Features

AutoPause / AutoResume: Sandbox Lifecycle Automation

Sandboxes in agent workflows spend most of their time idle — waiting for user input, callbacks, or the next RL rollout cycle. AutoPause/AutoResume lets the platform automatically suspend idle sandboxes and instantly wake them on the next incoming request, releasing physical host resources during idle periods. This is implemented as a platform-side, per-sandbox capability with semantics aligned to the E2B lifecycle parameter.

• AutoPause mechanism: A sweeper in the new cube-proxy-sidecar (under CubeProxy/sidecar/) tracks sandbox activity via last_active timestamps reported by CubeProxy's log_phase.lua. When idle >= timeout_seconds, the sidecar triggers a pause through CubeMaster → Cubelet, which snapshots the full VM state (memory + filesystem) to /data/cubelet/root/pausevm/<sandbox>, then shuts down the MicroVM. A configurable BootstrapWarmup window prevents premature pausing during sidecar startup.
• AutoResume mechanism: When a dataplane request arrives for a paused sandbox, CubeProxy's sandbox_state.lua gate intercepts it and fires an internal sub-request to the sidecar's /internal/resume. The sidecar drives a resume RPC through CubeMaster → Cubelet → containerd, which restores the VM from the pause snapshot. The dataplane request blocks until resume completes (bound by nginx proxy_read_timeout). Concurrent resumes for the same sandbox are coalesced in-process (singleflight pattern); cross-replica coordination uses Redis SETNX locks.
• Configurable resource release ratio (#553): A node-level configuration host.quota.paused_resource_release_ratio (float [0, 1], default 0) controls how much CPU/memory quota paused sandboxes release back to the scheduler. At ratio 1.0, all quota is released for maximum node density; at ratio 0, paused sandboxes retain full quota (guaranteed resume). Before resuming, a local admission check verifies the node has capacity — if not, the resume is rejected with HTTP 409 and a precise capacity diagnostic.
• Traffic access token gating (#639): Sandboxes created with network.allow_public_traffic=false receive a per-sandbox traffic_access_token (UUID v4). CubeProxy enforces this token on every inbound request (both cold-path and cache-hit), returning HTTP 403 for missing or mismatched tokens. Token values are redacted from all logs. Accepts both e2b-traffic-access-token and cube-traffic-access-token headers.
• Kill-path lifecycle: Sandboxes with on_timeout="kill" go through an idle timeout kill path with task.Kill. New POST /cube/sandbox/timeout and POST /cube/sandbox/refresh APIs expose end_at for deterministic lifecycle management. The CubeProxy gate returns 410 Gone for killing/killed sandboxes.

New files: CubeProxy/sidecar/ (Go binary — sweeper, resumer, registry, stream consumer, last-active poller, Redis coordination); CubeProxy Lua modules (sandbox_state.lua, admin_phase.lua); CubeMaster lifecycle endpoints; Cubelet pause/resume RPCs.

ARM64 (aarch64) Native Support

CubeSandbox now runs natively on ARM64 hosts, spanning the hypervisor, guest agent, shim, networking (BPF), build system, CI/CD, and deployment tooling. The work was a deep collaboration between Arm engineering and the Cube project team, progressing from feasibility to formal enablement.

• Hypervisor port (4dc72757): The SysCtrl device (guest-to-host signaling for shutdown, reboot, vsock-ready) was rewritten from PIO (x86-only) to MMIO for ARM64, registered on the mmio_bus at LEGACY_SYS_CTRL_MAPPED_IO_START. KVM register access (get_one_reg) was updated for a changed upstream API signature. Seccomp rules were aligned for ARM64 syscall number differences (SYS_lstat vs SYS_fstatat/SYS_newfstatat). Live migration support remains x86_64-gated.
• Guest agent (cb5706a8): The RPC readiness signal changed from x86 ioperm() + PIO port write (port 0x680) to ARM64 /dev/mem mmap at physical address 0x0903_0000 (SysCtrl MMIO region) with ptr::write_volatile. Build target auto-detected from host arch.
• CubeShim (fe3044cf, 4feab884): Kernel command line adapted per architecture — console=ttyAMA0,115200 (ARM PL011 UART) vs console=hvc0 (virtio-console). x86-only mitigations (no_timer_check, noreplace-smp) gated to #[cfg(target_arch = "x86_64")]. Seccomp allow-lists aligned: SYS_mkdir → SYS_mkdirat on ARM64; added missing SYS_faccessat2 for glibc path resolution on ARM64.
• BPF / CubeNet (cb263f24): Hardcoded -target amd64 in BPF //go:generate directives replaced with -target $GOARCH. Per-architecture vmlinux.h headers (amd64 + arm64 BTF dumps). BPF object files regenerated at build time; prebuilt .o files removed from git. Requires clang ≥ 14 (added to builder image via apt.llvm.org).
• Multi-arch builds (c6bb3762, 475b4885): Dockerfile.builder parameterized with TARGETARCH for Go, protoc, and Rust toolchain downloads. CubeEgress, CubeAPI, and envd images support multi-arch manifest lists. A containerized make guest-kernel target supports both native and cross builds with architecture-specific kernel configs (kernel-oc9.x86_64.config, kernel-oc9.aarch64.config).
• CI/CD (#720): Builder image, VMLinux, and one-click release workflows all produce per-architecture artifacts. Release workflow split into release_amd64 and release_arm64 jobs running on native runners; both upload to the same GitHub Release.
• Deployment (cb52bc72): Dev environment (run_vm.sh) auto-detects architecture — ARM64 uses machine virt with UEFI firmware (qemu-efi-aarch64). Release bundle script packages per-architecture mkcert binaries.
• Known limitations (documented): PVM (nested KVM) is x86_64-only; ARM64 requires bare-metal with native KVM. Live migration is x86_64-only.

TencentCloud Terraform Cluster Deployer

A production-grade, one-click cluster deployment for TencentCloud driven entirely by Terraform IaC. From a single release bundle and create.sh entry point, the deployer provisions a full CubeSandbox cluster with managed control plane, HA middleware, and elastic compute nodes.

• Infrastructure provisioning (#629): Terraform provisions a private VPC (10.0.0.0/16) with per-zone subnets, NAT Gateway with EIP, security groups, and a bastion jumpserver. Managed cloud services are automatically created:
  • MySQL (TencentDB 8.0): Multi-AZ with semi-sync replication, 4 GB / 200 GB, application account cube with database-level privileges.
  • Redis (TencentDB 7.0): Standard master/replica architecture, configurable memory (default 1 GB), password-protected.
  • CFS (Cloud File Storage): NFS share for cube-master's shared persistent storage (/data/CubeMaster/storage), mounted ReadWriteMany across replicas. Optional — enables multi-replica HA mode.
  • TCR (Tencent Container Registry): Private registry with VPC peering, namespace per deployment, long-lived access token.
• TKE control plane (#629): Managed Kubernetes cluster (v1.34.1, GlobalRouter, containerd) with intranet-only apiserver. Four control-plane components deployed as Deployments with CLB Services:
  • cube-master: Shared CFS NFS volume for template/snapshot/runtime state. CubeEgress MITM CA (ECDSA P-256, Terraform-generated). Internal CLB on port 8089.
  • cube-api: Public CLB on port 3000, proxies to cube-master via cluster DNS.
  • cube-proxy: Public CLB on ports 80/443, with Redis and TLS Secrets.
  • cube-webui: Public CLB on port 80, nginx reverse-proxying to cube-api and cube-proxy.
• Configurable replicas (#658): cubemaster_replicas, cube_api_replicas, cube_proxy_replicas, cube_webui_replicas variables (default 1 for POC mode). When TENCENTCLOUD_USE_CFS=true, cube-master multi-replica HA is enabled with cubemaster_replicas driving both spec.replicas and scheduler concurrency apportionment.
• Elastic compute nodes: Configurable CVM instances (PVM or bare-metal) in private VPC, auto-scaling via TKE node pool. Default 1 node, configurable count and instance types.
• One-click upgrade mode (#538): install.sh --mode=upgrade detects existing installations, performs three-way .env config merge (new defaults + old customizations + explicit overrides), runs fail-fast preflight checks (disk space, semver compatibility, CIDR conflict), and backs up configuration before any destructive change. User customizations are preserved; secrets are redacted in the diff report but retained in the actual merged file.
• External MySQL/Redis (#514): One-click installer supports pointing at pre-existing external MySQL and Redis instances via CUBE_EXTERNAL_MYSQL_* / CUBE_EXTERNAL_REDIS_* variables. Local Docker containers are masked, and all components (CubeMaster, CubeAPI, CubeProxy) are configured to use the external endpoints.
• Other installer improvements: CUBE_PROXY_HOST_PORT deprecated, split into CUBE_PROXY_HTTP_PORT / CUBE_PROXY_HTTPS_PORT (#588). Manual SQL seed removed in favor of CubeMaster embedded migrations (#628). CubeEgress integrated into compute node startup (#707). Improved external dependency compatibility with shell-safe env persistence and redis-cli timeout detection (#673). Cubelet reporting interval and scheduler scoring configured for multi-node TencentCloud deployments (b8f22421). Image defaults updated to v0.5.0 tags (#719).

New files: deploy/one-click/terraform/tencentcloud/ (create.sh, destroy.sh, main.tf, variables.tf, tke-addons.tf, outputs.tf, lib-state-sync.sh, env.example); docs/guide/tencentcloud-terraform-deploy.md (EN + ZH).

Network Security Hardening

Three critical patches for sandbox network security: inbound access control, outbound fail-closed, and policy-routing egress.

• Per-sandbox traffic access token (#639): Described in AutoPause/AutoResume above. CubeProxy enforces traffic_access_token on every inbound request when AllowPublicTraffic=false, returning 403 for missing/bad tokens. Token values are never logged.
• CubeEgress fail-closed bootstrap (c5f811d8): During CubeEgress startup, before L7 policies are loaded from CubeMaster (bootstrap_status ≠ "ready"), the proxy now returns 403 for all non-audit traffic instead of the previous fail-open behavior. This eliminates the security gap where sandbox outbound traffic could bypass all host/SNI/method/path controls during a restart window.
• Route-aware egress / cube-router (7c514e9d): An optional cube-router kernel dummy device allows sandbox outbound traffic to enter the Linux host routing stack instead of being hard-redirected to the primary NIC. Traffic can leave through any routable device (eth0, eth1, GRE tunnels, VXLAN, WireGuard), enabling seamless integration with existing multi-NIC and VPN network infrastructure. Existing CubeEgress L7 policy, DNS allow-list, and port mapping are all preserved.
• BPF TCP checksum fix (7c2dd1ff): Fixed invalid TCP checksums on cross-node port-mapped sandbox replies. The snat_tcp() function was incorrectly using BPF_F_PSEUDO_HDR when only the TCP port had changed, causing checksum corruption on multi-node deployments.
• from_world cleanup (5b919466): Removed ineffective from_world TC filter attachment on the loopback interface, reducing unnecessary eBPF hook points.
• Host service access (48d080e6): Sandbox outbound traffic to the host's own IP is now redirected via BPF shortcut, enabling sandboxed code to reach host-local services.
• Network hardening guide (#663): New bilingual documentation covering default control-plane attack surface, binding strategies (private NIC vs firewall whitelisting), CubeAPI auth callback with path+method validation, and TLS/credential rotation guidance.

✨ Enhancements

SDK

• E2B filesystem API alignment (#678): Go and Python SDKs now implement the full E2B filesystem API surface: list, stat, exists, remove, rename, mkdir, and watch. Comprehensive integration tests included.
• Python SDK PTY APIs (250d248a): Complete PTY (pseudo-terminal) interface added to the Python SDK — create, connect, kill, send_stdin, resize — with streaming output via PtyHandle iterator. Speaks envd's Connect-JSON RPC directly; no dependency on e2b Python packages.
• Python SDK E2B network.rules transforms (#568): Compatibility with E2B's per-host {transform: {headers: {...}}} credential injection shape, translated into CubeEgress L7 action.inject rules. Drop-in replacement for codebases using E2B's per-host credential injection.
• Python SDK double-encoding fix (#572): Execution logs and errors are no longer double-encoded, fixing corrupted output display.

Performance

• Pure-Go native rootfs export (#558): A daemonless, pure-Go rootfs export pipeline that bypasses Docker, skopeo, and umoci entirely. Features concurrent prefetch, loop-mount streaming directly into ext4 block devices, and a "decompress-and-delete" strategy that significantly reduces peak memory and build time compared to the previous skopeo/umoci pipeline. Enabled by default.
• VirtIO block performance (#575): Enables VIRTIO_BLK_F_SEG_MAX (multi-segment requests) and VIRTIO_RING_F_INDIRECT_DESC (indirect descriptors) in the hypervisor's virtio-blk device, improving sequential write throughput from 2888 MiB/s to 3293 MiB/s (fio benchmark).

Template Management

• Image pull progress TUI (#580): Real-time pull progress tracking with Redis-backed persistence. New template watch and template build-watch CLI commands provide an interactive bubbletea TUI showing live metrics (download speed, per-layer completion, step-by-step checklist), with plain-text fallback on non-TTY terminals.
• Latest job ID in template list (#546): Template list and detail APIs now expose each template's latest create/rebuild job ID. The Web UI automatically opens build logs when viewing a template with an active (running/pending/building) job.
• Artifact resource leak fixes (#631): Introduces t_cube_artifact_node_placement table for node-level artifact tracking independent of replica lifecycle. Periodic artifact GC with MySQL GET_LOCK for HA coordination. Hardened cascade cleanup across CubeMaster, Cubelet, and CubeAPI. AgentHub snapshot cascade cleanup with path traversal protection.

Web UI

• Template creation overhaul (#675): New multi-step template creation form with image source selection, instance type configuration, network settings, and advanced options. Improved validation and field organization.

AgentHub

• LLM env-var fallback removal (#602): All AgentHub LLM secrets and settings now live exclusively in the database, encrypted with a per-installation CSPRNG-generated master key. Environment variable fallback paths are eliminated. The one-click upgrade script actively deletes obsolete env keys. decrypt_or_passthrough now fails closed for undecryptable payloads.
• Assistant state persistence (#582): Authentication, OpenClaw runtime state, template inheritance, and snapshot recovery behavior are now persisted in the database. Includes bcrypt-based auth, WeCom secret decryption, rate limiting on auth entrypoints. Enables backup/restore and safe cloning of digital assistants.

Deployment & Installer

• One-click upgrade mode (#538): Detailed in Terraform section above. --mode=upgrade with three-way env merge, pre-upgrade backup, and fail-fast preflights.
• External MySQL/Redis (#514): Detailed above. Support for pointing one-click installer at pre-existing external database instances.
• CUBE_PROXY port split (#588): CUBE_PROXY_HOST_PORT deprecated; CUBE_PROXY_HTTP_PORT (default 80) and CUBE_PROXY_HTTPS_PORT (default 443) provide separate HTTP/HTTPS control.
• Static builds (#583): cube-api, cubemaster, and cubemastercli are now fully static binaries (CGO_ENABLED=0 / musl target), eliminating host glibc dependency and preventing version-skew failures.
• Embedded migrations (#628): Manual SQL seed removed; CubeMaster embedded goose migrations own single-node seed rows. Eliminates mysql client dependency on control nodes.
• CubeEgress compute integration (#707): CubeEgress integrated into compute node startup/down scripts, extending egress policy enforcement to all nodes.
• resolvectl compatibility (#703): Tolerates missing resolvectl default-route on older systemd (pre-v240), preventing install failures on RHEL 8.3 and similar distributions.

Infrastructure

• Redis key unification (#609): All Redis keys centralized in pkg/base/rediskey with consistent naming. Read/write pool separation dropped in favor of a single pool, simplifying multi-node deployment configuration.
• Migration identity hardening (#620): Three-layer defense against silent migration skipping: 14-digit UTC timestamp prefixes for new migrations, out-of-order application support, and SHA-256 content fingerprinting with startup verification. CI enforces immutability of already-merged migration files.
• Node label management API (#633): POST /nodes/{id}/labels and DELETE /nodes/{id}/labels endpoints for admin-managed labels. Kubernetes-compatible naming (DNS1123 subdomain prefix), SELECT FOR UPDATE race protection, 64-label limit, system-reserved namespace protection (kubernetes.io, beta.kubernetes.io, cube.cloud.tencentcloud.com).
• envd version reporting (#650): Collected envd versions propagated as sandbox annotations, enabling E2B SDK feature gating against real runtime versions instead of a hardcoded constant.
• Configurable HTTP bind (#662): CUBEMASTER_HTTP_BIND makes the HTTP listen address configurable, supporting private-NIC binding for network security hardening.
• TencentCloud scheduler scoring (b8f22421): Multi-node scheduler scoring with real_time_weighted_average plugin balancing mvm_num, local_create_num, cpu_usage, and quota_mem_usage. priority_select_num dynamically capped at min(compute_node_count, 3).

🐛 Bug Fixes

These fixes address issues present in v0.4.0:

• High-concurrency rollback deadlock (#693): Snapshot runtime active binding refactored into a dedicated t_cube_snapshot_runtime_active table with sandbox-level and resource-level distributed locks. Eliminates MySQL 1213 deadlock errors.
• Image uid/gid squashing (#671, #608): Two complementary fixes for image ownership preservation:
  • Native export path (#671): Removed WithNoSameOwner() option, which was squashing all file uid/gid to the extracting user, breaking image ownership.
  • Template center (#608): umoci unpack --rootless now only passed when euid ≠ 0 (not when running as root). Docker-export fallback uses --same-owner --numeric-owner. Fixes Chromium profile write failures and CDP unreachability in browser sandboxes, and envd exec EACCES on /home/user for Python images.
• Hung hostdir mounts (#691): Hostdir bind and remount operations now run through a bounded 3-second timeout subprocess. Previously, stale NFS mounts or other hung filesystems would block sandbox creation indefinitely.
• CubeProxy envd streaming buffering (#647): Nginx response buffering disabled for envd server-streaming endpoints. Previously, nginx buffered early stream frames, breaking immediate-return semantics for background commands and watch streams.
• MSI-X table/PBA hardening (#619): Guest-triggered panics in the VMM's MSI-X table/PBA read/write paths replaced with graceful error handling. A malicious or buggy guest can no longer crash the VMM process via invalid MSI-X accesses.
• CubeProxy implementation detail leakage (#653): Removed X-Cube-Retcode response header and $cube_retcode access-log field that exposed internal failure-mode codes. Errors now return opaque HTTP status codes with uniform JSON bodies, preventing sandbox ID enumeration and infrastructure probing.
• Auth callback method forwarding (#315): X-Request-Method now forwarded to auth callbacks alongside X-Request-Path, enabling fine-grained (path + method) authorization. Previously, a read-only credential could access destructive endpoints on the same path.
• envd command env propagation (#566): Fixed create-time environment variables being dropped when starting envd via commands.run.
• Sandbox preview route (#570): Fixed missing /cube/sandbox/preview route handler that caused cubemastercli tpl render to silently fail.
• One-click upgrade bundle integrity (#597): Fixed missing scripts/common/ directory in upgrade bundles that broke preflight validation scripts for the upgrade feature (#538).
• Template creation Cube CA forwarding (#652): Fixed with_cube_ca parameter not being forwarded when creating templates, ensuring clients can control whether the CubeEgress root CA is baked into template rootfs.
• CubeEgress compute CA refresh (#614): CubeEgress on compute nodes now refreshes its MITM CA from CubeMaster, fixing CA mismatch after master rotation.
• Template info backfill (#594): Backfilled missing created_at and image_info fields in template detail responses.
• Snapshot delete job cleanup (#559): Cleaned orphaned job rows after snapshot deletion, preventing stale build job references.
• Cross-replica node sync (#542): Periodic reload goroutine started for nodemeta cross-replica synchronization, fixing stale node state in multi-replica CubeMaster deployments.
• BPF inner map BTF key/value (#595): CubeVS inner maps now created with BTF key/value, fixing BPF map compatibility on newer kernels.
• One-click install root enforce (#649): Configurable install root paths removed; install prefix safety assertion hardened to prevent accidental system directory wipes.
• One-click MIRROR persistence (#622): MIRROR env now persisted to .one-click.env for consistent image registry selection across restarts.
• One-click same-CIDR reinstall (#586): Distinguishes same-CIDR reinstall from CIDR change, uses systemd to stop services cleanly.
• One-click compute quickcheck race (#637): Post-start compute node checks now tolerant of transient startup races.
• One-click DATABASE_URL persistence (#611): DATABASE_URL now persisted for local MySQL in install and systemd start paths.
• Python SDK streaming body (377a99dc): Request bodies buffered before copying in IPOverrideTransport, fixing multipart upload failures.
• CubeProxy log cleanup (#593): Dead log fields and faulty-backend stubs removed from CubeProxy.
• TencentCloud deployer semver helpers (#587): semver_compare and version_lt functions added for correct upgrade decision logic.

📚 Documentation

• ARM64 deployment guides (64931ff2): All deployment guides (quickstart, bare-metal, dev environment, multi-node, self-build) updated in EN + ZH with architecture-specific instructions. ARM64 PVM limitation documented.
• Network hardening guide (#663): Bilingual operational security guide covering control-plane attack surface, binding strategies, auth callback configuration, and TLS/credential guidance.
• TencentCloud Terraform deploy guide (ae81121d): Full deployment guide (EN + ZH) for the Terraform cluster deployer.
• Snapshot/clone/rollback deep-dive (#680): Technical deep-dive blog post on snapshot, clone, and rollback mechanisms (EN + ZH).
• Sandbox logs guide (#692): New cubecli logs usage guide with examples.
• Multi-node scheduler scoring (#672): Guidance on configuring multi-node scheduler scoring for balanced workload distribution.
• Host mount permission fixes (#560): Documentation explaining host mount permission handling.
• v0.4.0 release blog posts (#585): Release announcement and agent-friendly-service posts (EN + ZH).
• Network deep-dive blog (#627): Technical deep-dive on CubeSandbox networking (EN + ZH).
• README improvements (#640, #666, #646): Product highlights, v0.4 showcase, benchmark report links, architecture diagram update, homepage tagline refinement.
• Documentation optimization (#665): Cross-documentation link fixes, sidebar navigation for snapshot-rollback-clone, localized docs flow preservation (#668, #664).
• Install guide links (#475, #466): Installation guide callouts in benchmark posts, troubleshooting links in install error messages.

⚙️ Engineering Improvements

• Multi-arch CI (#720): Builder image, VMLinux, and one-click release workflows all support amd64 + arm64 with per-architecture artifacts and multi-arch manifests.
• Python SDK publish workflow (#700): GitHub Actions workflow for PyPI publishing triggered by python-sdk-v* tags. Version cross-validation (tag vs pyproject.toml vs __init__.py), smart change detection to skip unchanged publishes, and twine check validation.
• Cubelet reporting default (#722): Reporting interval default changed to 1s for more responsive metrics.
• CI release workflow hardening (#724): --repo flag added to gh release commands for correct repository targeting.

title: v0.5.0 — 2026.07.03

2026.07.03 Release v0.5.0

CubeSandbox 0.5.0 带来了四大核心特性：AutoPause/AutoResume 沙箱生命周期自动化（闲置沙箱自动暂停并在请求到达时毫秒级唤醒）、ARM64 (aarch64) 全栈原生支持（从 hypervisor 到 CI/CD 的完整适配）、腾讯云 Terraform 一键集群部署（生产级 IaC 部署方案），以及网络安全性增强（入向流量令牌鉴权、CubeEgress 启动期 Fail-Closed、出向策略路由）。其他重要更新包括：纯 Go 原生 rootfs 导出管线（绕过 Docker/skopeo/umoci，显著降低内存与构建时间开销）、快照运行时锁重构（消除高并发回滚死锁）、镜像 uid/gid 保留修复（修复非 root 镜像权限问题）、E2B SDK 对齐（完整的文件系统与 PTY API），以及一键升级模式（三路配置合并）。共计 116 个提交，来自 26 位贡献者。

🎯 核心特性

AutoPause / AutoResume：沙箱生命周期自动化

Agent 工作流中的沙箱大部分时间处于闲置状态——等待用户输入、回调、或 RL 的下一轮 rollout。AutoPause/AutoResume 让平台自动暂停闲置沙箱，并在新请求到达时原地唤醒，将物理资源在闲置期间完全释放。这是一个平台侧承担、per-sandbox 粒度的能力，语义与 E2B 的 lifecycle 参数对齐。

• AutoPause 机制：新增的 cube-proxy-sidecar 组件内建 sweeper，通过 CubeProxy 的 log_phase.lua 上报的 last_active 时间戳跟踪沙箱活跃状态。当 idle >= timeout_seconds 时，sweeper 通过 CubeMaster → Cubelet 触发暂停：将 MicroVM 的完整状态（内存 + 文件系统）快照到 /data/cubelet/root/pausevm/<sandbox>，然后关闭沙箱。BootstrapWarmup 窗口可防止 sidecar 刚启动时的误暂停。
• AutoResume 机制：当数据面请求到达已暂停的沙箱时，CubeProxy 的 sandbox_state.lua 门控拦截请求，向 sidecar 的 /internal/resume 发起内部子请求。Sidecar 通过 CubeMaster → Cubelet → containerd 驱动恢复流程，从暂停快照中原地恢复 VM。数据面请求会阻塞等待恢复完成（受 nginx proxy_read_timeout 约束）。同沙箱的并发恢复请求在进程内合并（singleflight 模式）；跨副本协调通过 Redis SETNX 分布式锁。
• 可配置资源释放比例 (#553)：节点级配置 host.quota.paused_resource_release_ratio（float [0, 1]，默认 0）控制暂停沙箱向调度器释放多少 CPU/内存配额。设为 1.0 时，暂停资源全部释放，实现最大调度密度；设为 0 时，保留完整配额，确保恢复链路绝对可靠。恢复前会进行本地准入检查——若节点容量不足，返回 HTTP 409 并附带精确的容量诊断信息。
• 入向流量令牌门控 (#639)：以 network.allow_public_traffic=false 创建的沙箱会获得一个 per-sandbox 的 traffic_access_token（UUID v4）。CubeProxy 在每个入站请求（包括冷路径和缓存命中路径）强制校验此令牌，缺失或错误令牌返回 HTTP 403。令牌值在所有日志中均被脱敏。兼容 e2b-traffic-access-token 和 cube-traffic-access-token 两种请求头。
• Kill 路径：on_timeout="kill" 的沙箱走闲置超时 Kill 路径（task.Kill）。新增 POST /cube/sandbox/timeout 和 POST /cube/sandbox/refresh API，暴露 end_at 实现确定性的生命周期管理。CubeProxy 门控对 killing/killed 状态返回 410 Gone。

新增文件：CubeProxy/sidecar/（Go 二进制——sweeper、resumer、registry、stream consumer、last-active poller、Redis 协调）；CubeProxy Lua 模块（sandbox_state.lua、admin_phase.lua）；CubeMaster 生命周期端点；Cubelet pause/resume RPC。

ARM64 (aarch64) 全栈原生支持

CubeSandbox 现已支持在 ARM64 主机上全栈原生运行，覆盖 hypervisor、guest agent、shim、网络（BPF）、构建系统、CI/CD 和部署工具。这是 Arm 工程团队与 Cube 项目组的深度联合研发成果，项目状态已从可行性验证推进到正式 Enablement。

• Hypervisor 适配 (4dc72757)：SysCtrl 设备（guest 到 host 的信号通道：关机、重启、vsock-ready）从 PIO 端口 I/O（x86 专用）重写为 MMIO 内存映射 I/O，在 mmio_bus 的 LEGACY_SYS_CTRL_MAPPED_IO_START 地址注册。KVM 寄存器访问（get_one_reg）适配上游 API 变更。Seccomp 过滤规则按 ARM64 系统调用号差异对齐（SYS_lstat vs SYS_fstatat/SYS_newfstatat）。热迁移功能保持 x86_64 专属。
• Guest Agent (cb5706a8)：RPC 就绪信号从 x86 的 ioperm() + PIO 端口写入（端口 0x680）改为 ARM64 的 /dev/mem 在物理地址 0x0903_0000（SysCtrl MMIO 区域）处 mmap + ptr::write_volatile。构建目标自动检测宿主机架构。
• CubeShim (fe3044cf, 4feab884)：内核命令行按架构自适应——console=ttyAMA0,115200（ARM PL011 UART）vs console=hvc0（virtio-console）。x86 专用参数（no_timer_check、noreplace-smp）通过 #[cfg(target_arch = "x86_64")] 条件编译。Seccomp 白名单对齐：ARM64 上 SYS_mkdir → SYS_mkdirat；补充缺失的 SYS_faccessat2（ARM64 glibc 路径解析所用）。
• BPF / CubeNet (cb263f24)：BPF //go:generate 指令中的硬编码 -target amd64 替换为 -target $GOARCH。按架构提供 vmlinux.h（amd64 + arm64 BTF 导出）。BPF 目标文件改为构建时生成；预编译 .o 文件从 git 中移除。需要 clang ≥ 14（已通过 apt.llvm.org 加入构建镜像）。
• Multi-Arch 镜像构建 (c6bb3762, 475b4885)：Dockerfile.builder 通过 TARGETARCH 参数化 Go、protoc、Rust 工具链下载。CubeEgress、CubeAPI 和 envd 镜像支持 Multi-Arch Manifest List。容器化 make guest-kernel 目标支持本地和交叉构建，使用架构特定的内核配置（kernel-oc9.x86_64.config、kernel-oc9.aarch64.config）。
• CI/CD (#720)：Builder image、VMLinux、one-click release 工作流均产出分架构制品。Release 工作流拆分为 release_amd64 和 release_arm64 两个 Job，分别在原生 Runner 运行，上传到同一个 GitHub Release。
• 部署 (cb52bc72)：开发环境（run_vm.sh）自动检测架构——ARM64 使用 machine virt + UEFI 固件（qemu-efi-aarch64）。Release 打包脚本按架构选择合适的 mkcert 二进制。
• 已知限制（已在文档中标明）：PVM（嵌套 KVM）仅支持 x86_64；ARM64 需使用裸金属物理机原生 KVM。热迁移仅支持 x86_64。

腾讯云 Terraform 集群化部署

一套面向腾讯云的生产级、一键式 Terraform IaC 集群部署方案。只需一份 release bundle，执行 create.sh 作为唯一入口，即可自动拉起完整的 CubeSandbox 集群——包含受管控制面、高可用中间件和弹性计算节点。

• 基础设施自动编排 (#629)：Terraform 自动创建私有 VPC（10.0.0.0/16）及按可用区的子网、NAT 网关（含弹性公网 IP）、安全组、以及一台跳板机（jumpserver）。云上托管服务自动创建：
  • MySQL（TencentDB 8.0）：多可用区半同步复制，4GB 内存 / 200GB 磁盘，创建 cube 应用账号及数据库级权限。
  • Redis（TencentDB 7.0）：标准主从架构，可配置内存（默认 1GB），密码保护。
  • CFS（云文件存储）：NFS 共享文件系统，供 cube-master 多副本挂载共享持久化存储（/data/CubeMaster/storage），ReadWriteMany 模式。可选——开启后启用多副本高可用模式。
  • TCR（腾讯云容器镜像服务）：私有容器镜像仓库，VPC 内网链路打通，按部署创建命名空间，生成长期访问凭证。
• TKE 控制面 (#629)：托管 Kubernetes 集群（v1.34.1，GlobalRouter 网络，containerd 运行时），apiserver 仅限内网。四项控制面组件以 Deployment + CLB Service 形式部署：
  • cube-master：共享 CFS NFS 卷，CubeEgress 中间人 CA（ECDSA P-256，Terraform 自动生成），内网 CLB 端口 8089。
  • cube-api：公网 CLB 端口 3000，通过集群 DNS 代理到 cube-master。
  • cube-proxy：公网 CLB 端口 80/443，Redis 和 TLS 凭证以 Secret 注入。
  • cube-webui：公网 CLB 端口 80，nginx 反向代理到 cube-api 和 cube-proxy。
• 可配置副本数 (#658)：cubemaster_replicas、cube_api_replicas、cube_proxy_replicas、cube_webui_replicas 变量（POC 模式默认 1 副本）。当 TENCENTCLOUD_USE_CFS=true 时，cube-master 支持多副本高可用，副本数同时驱动 spec.replicas 和调度器并发分配。
• 弹性计算节点：私有 VPC 内可配置一台或多台 CVM 实例（PVM 或裸金属），通过 TKE 节点池弹性扩缩容。默认 1 节点，支持自定义数量和实例规格。
• 一键升级模式 (#538)：install.sh --mode=upgrade 自动检测已有安装，执行三路 .env 配置合并（新默认值 + 旧自定义值 + 显式覆盖值），fail-fast 预检（磁盘空间、语义化版本兼容性、CIDR 冲突），并在任何破坏性操作前备份配置。用户自定义修改被保留，密钥值在 diff 报告中脱敏但在实际合并文件中保留。
• 外部 MySQL/Redis 支持 (#514)：一键安装器支持通过 CUBE_EXTERNAL_MYSQL_* / CUBE_EXTERNAL_REDIS_* 变量接入已有的外部 MySQL 和 Redis 实例。本地 Docker 容器被 mask，所有组件（CubeMaster、CubeAPI、CubeProxy）使用外部端点。
• 其他安装器改进：废弃 CUBE_PROXY_HOST_PORT，拆分为 CUBE_PROXY_HTTP_PORT / CUBE_PROXY_HTTPS_PORT (#588)。移除手动 SQL 初始化，改用 CubeMaster 内嵌 goose migration (#628)。CubeEgress 集成到计算节点启动流程 (#707)。改进外部依赖兼容性（Shell 安全的 env 持久化、redis-cli 超时兼容检测）(#673)。腾讯云部署配置了 cubelet 上报间隔与多节点调度器评分 (b8f22421)。镜像默认值更新为 v0.5.0 标签 (#719)。

新增文件：deploy/one-click/terraform/tencentcloud/（create.sh、destroy.sh、main.tf、variables.tf、tke-addons.tf、outputs.tf、lib-state-sync.sh、env.example）；docs/guide/tencentcloud-terraform-deploy.md（中英文各一份）。

网络安全增强

入向、出向、数据面三个维度的关键网络安全补丁。

• Per-sandbox 流量访问令牌 (#639)：已在 AutoPause/AutoResume 章节详述。CubeProxy 在 AllowPublicTraffic=false 时对每个入向请求强制校验 traffic_access_token，缺失或错误返回 403。令牌值不会被记录到任何日志中。
• CubeEgress 启动期 Fail-Closed (c5f811d8)：在 CubeEgress 启动期间、L7 策略尚未从 CubeMaster 加载完毕时（bootstrap_status ≠ "ready"），CubeEgress 对所有非审计类流量返回 403，而非此前的 Fail-Open 放行行为。这消除了沙箱出向流量在 Egress 重启窗口内绕过所有域名/SNI/方法/路径控制的敞口。
• 策略路由 / cube-router (7c514e9d)：可选的 cube-router 内核 dummy 网卡允许沙箱出向流量走宿主机 Linux 路由栈，而非被硬性重定向到主网卡。流量可从任意可路由设备（eth0、eth1、GRE 隧道、VXLAN、WireGuard）发出，无缝对接现有网络基础设施。已有的 CubeEgress L7 策略、DNS 白名单和端口映射全部保留。
• BPF TCP 校验和修复 (7c2dd1ff)：修复跨节点端口映射沙箱回包 TCP 校验和错误。snat_tcp() 函数在仅 TCP 端口值变化的情况下错误使用了 BPF_F_PSEUDO_HDR 参数，导致多节点部署下校验和损坏。
• from_world 清理 (5b919466)：移除 loopback 接口上无效的 from_world TC filter 挂载，减少不必要的 eBPF 挂载点。
• 宿主机服务访问 (48d080e6)：沙箱到宿主机自身 IP 的出向流量现在通过 BPF 快捷路径转发，允许沙箱内代码访问宿主机上的本地服务。
• 网络安全加固指南 (#663)：中英文运维安全指南，覆盖控制面默认攻击面、绑定策略（私有网卡 vs 防火墙白名单）、CubeAPI 认证回调的 path+method 双重校验、以及 TLS/凭证轮换指引。

✨ 功能增强

SDK

• E2B 文件系统 API 对齐 (#678)：Go 和 Python SDK 现已实现完整的 E2B 文件系统 API：list、stat、exists、remove、rename、mkdir、watch。含全面集成测试。
• Python SDK PTY API (250d248a)：Python SDK 新增完整 PTY（伪终端）接口——create、connect、kill、send_stdin、resize，通过 PtyHandle 迭代器提供流式输出。直接通过 httpx 与 envd 的 Connect-JSON RPC 通信，不依赖 e2b Python 包。
• Python SDK E2B network.rules 转换 (#568)：兼容 E2B 的 per-host {transform: {headers: {...}}} 凭据注入格式，翻译为 CubeEgress L7 action.inject 规则。使用 E2B per-host 凭据注入的代码可零改动切换。
• Python SDK 双重编码修复 (#572)：修复执行日志和错误的双重编码问题。

性能

• 纯 Go 原生 rootfs 导出 (#558)：无守护进程、纯 Go 实现的 rootfs 导出管线，完全绕过 Docker、skopeo 和 umoci。核心优化包括并发预取、loop 挂载流式写入 ext4 块设备、逐层解压即删除策略，显著降低了峰值内存占用与构建时间开销。默认启用。
• VirtIO Block 性能 (#575)：在 Hypervisor 的 virtio-blk 设备中启用 VIRTIO_BLK_F_SEG_MAX（多段请求）和 VIRTIO_RING_F_INDIRECT_DESC（间接描述符），fio 基准测试中顺序写入吞吐从 2888 MiB/s 提升至 3293 MiB/s。

模板管理

• 镜像拉取进度 TUI (#580)：基于 Redis 持久化的实时拉取进度跟踪。新增 template watch 和 template build-watch CLI 命令，提供交互式 bubbletea TUI（显示下载速度、逐层完成度、步骤清单），非 TTY 终端自动降级为纯文本输出。
• 模板列表暴露最新 Job ID (#546)：模板列表和详情 API 暴露每个模板的最新 create/rebuild job ID。Web UI 在查看有活跃（running/pending/building）job 的模板时自动打开构建日志。
• 制品资源泄漏修复 (#631)：引入 t_cube_artifact_node_placement 表，独立于 Replica 生命周期跟踪节点级制品放置。周期性制品 GC，以 MySQL GET_LOCK 保证高可用协调。加固 CubeMaster、Cubelet、CubeAPI 级联清理链路。AgentHub 快照级联清理增加路径穿越保护。

Web UI

• 模板创建重构 (#675)：全新的多步骤模板创建表单，支持镜像源选择、实例规格配置、网络设置和高级选项。改进了表单校验和字段组织。

AgentHub

• LLM 环境变量回退移除 (#602)：所有 AgentHub LLM 密钥和设置现在仅存储在数据库中，使用按安装实例的 CSPRNG 生成主密钥加密。环境变量回退路径全部移除。一键升级脚本主动删除过时的环境变量密钥。decrypt_or_passthrough 对不可解密的负载采取 Fail-Closed 策略。
• 助理状态持久化 (#582)：认证信息、OpenClaw 运行时状态、模板继承关系和快照恢复行为持久化到数据库。包含 bcrypt 密码哈希、企微 Secret 解密、认证入口限流。支持数字助理的备份/恢复和安全克隆。

部署与安装器

• 一键升级模式 (#538)：已在集群部署章节详述。--mode=upgrade + 三路 env 合并 + 升级前备份 + fail-fast 预检。
• 外部 MySQL/Redis (#514)：已在集群部署章节详述。支持接入已有外部数据库实例。
• CUBE_PROXY 端口拆分 (#588)：CUBE_PROXY_HOST_PORT 废弃；拆分为 CUBE_PROXY_HTTP_PORT（默认 80）和 CUBE_PROXY_HTTPS_PORT（默认 443）。
• 静态编译 (#583)：cube-api、cubemaster 和 cubemastercli 现为完全静态二进制（Go CGO_ENABLED=0 / Rust musl 目标），消除宿主机 glibc 依赖和版本偏差风险。
• 内嵌 Migration (#628)：移除手动 SQL 初始化；CubeMaster 内嵌 goose migration 自动处理单节点种子数据。消除控制节点对 mysql 客户端的依赖。
• CubeEgress 计算节点集成 (#707)：CubeEgress 集成到计算节点启动和停止脚本，Egress 策略执行覆盖所有节点。
• resolvectl 兼容 (#703)：容忍旧版本 systemd（v240 以下）缺少 resolvectl default-route，防止 RHEL 8.3 等系统安装失败。

基础设施

• Redis Key 统一 (#609)：所有 Redis Key 集中在 pkg/base/rediskey 中，采用统一命名规范。移除读写/元数据连接池分离，简化为单连接池，降低多节点部署配置复杂度。
• Migration 身份固化 (#620)：三层防线防止 migration 静默跳过：新 migration 必须使用 14 位 UTC 时间戳前缀（而非整数序号），支持乱序应用（out-of-order），以及启动时 SHA-256 内容指纹校验。CI 强制禁止修改已合入的 migration 文件。
• 节点标签管理 API (#633)：POST /nodes/{id}/labels 和 DELETE /nodes/{id}/labels 端点用于管理员标签管理。K8s 兼容命名（DNS1123 子域名前缀），SELECT FOR UPDATE 竞争保护，每节点 64 标签上限，系统保留命名空间保护（kubernetes.io、beta.kubernetes.io、cube.cloud.tencentcloud.com）。
• envd 版本上报 (#650)：实际采集到的 envd 版本作为沙箱注解传播，使 E2B SDK 能根据真实运行时版本进行特性门控，替代硬编码的版本常量。
• 可配置 HTTP 监听地址 (#662)：CUBEMASTER_HTTP_BIND 使 HTTP 监听地址可配置，支持绑定到私有网卡以进行网络安全加固。
• 腾讯云调度器评分 (b8f22421)：多节点调度器评分配置 real_time_weighted_average 插件，平衡 mvm_num、local_create_num、cpu_usage、quota_mem_usage 权重。priority_select_num 动态上限为 min(compute_node_count, 3)。

🐛 Bug 修复

以下修复针对 v0.4.0 中存在的问题：

• 高并发回滚死锁修复 (#693)：快照运行时活跃绑定重构为独立的 t_cube_snapshot_runtime_active 表，引入沙箱级和资源级分布式锁，从根本上消除了 MySQL 1213 死锁错误。
• 镜像 uid/gid 保留修复 (#671、#608)：两个互补的镜像权限保留修复：
  • Native Export 路径 (#671)：移除 WithNoSameOwner() 选项——此前该选项会将所有文件的 uid/gid 压缩为提取用户，破坏镜像原始权限。
  • Template Center (#608)：umoci unpack --rootless 现在仅在 euid ≠ 0 时传递（root 身份运行时不再传递）。Docker-export 回退路径增加 --same-owner --numeric-owner。修复 Browser 沙箱中 Chromium profile 写入失败和 CDP 不可达、以及 Python 镜像 envd exec 因 /home/user 权限导致 EACCES 的问题。
• Hostdir 挂载超时保护 (#691)：Hostdir bind 和 remount 操作通过有界子进程执行，每步 3 秒超时。此前，卡住的 NFS 等宿主机挂载点会导致沙箱创建无限期阻塞。
• CubeProxy envd 流式缓冲修复 (#647)：对 envd 服务端流式端点禁用 nginx 响应缓冲。此前 nginx 会缓存早期的流帧，破坏后台命令和 Watch 流的即时返回语义。
• MSI-X Table/PBA 鲁棒性加固 (#619)：VMM 中 MSI-X table/PBA 读写路径上 guest 可触发的 panic 替换为优雅错误处理。恶意或有缺陷的 guest 不再能通过无效 MSI-X 访问导致 VMM 进程崩溃。
• CubeProxy 实现细节泄露修复 (#653)：移除暴露内部故障码的 X-Cube-Retcode 响应头和 $cube_retcode 访问日志字段。错误响应统一为不透明 HTTP 状态码 + 标准 JSON Body，防止通过区分错误码枚举沙箱 ID 或探测基础设施弱点。
• Auth Callback 方法转发 (#315)：X-Request-Method 现在转发到认证回调，实现（路径 + 方法）粒度的鉴权。此前，仅路径白名单无法区分同一路径的 GET 和 DELETE 操作，只读凭证可访问破坏性端点。
• CubeEgress 计算节点 CA 刷新 (#614)：计算节点上的 CubeEgress 现在从 CubeMaster 刷新中间人 CA，修复主节点 CA 轮换后的 CA 不匹配问题。
• 模板信息回填 (#594)：回填模板详情响应中缺失的 created_at 和 image_info 字段。
• 快照删除 Job 清理 (#559)：快照删除后清理孤儿 job 行，防止失效构建 job 引用。
• 跨副本节点状态同步 (#542)：启动 Nodemeta 定期重载协程，实现跨副本节点状态同步，修复多副本 CubeMaster 部署中节点状态过期问题。
• BPF 内层 Map BTF (#595)：CubeVS 内层 map 现在带 BTF key/value 创建，修复高版本内核上的 BPF map 兼容性。
• 一键安装根目录加固 (#649)：移除可配置的安装根路径；安装前缀安全性断言加强，防止误擦除系统目录。
• 一键安装 MIRROR 持久化 (#622)：MIRROR 环境变量持久化到 .one-click.env，确保重启后镜像仓库选择一致。
• 一键安装相同 CIDR 重装 (#586)：区分相同 CIDR 重装与 CIDR 变更场景，使用 systemd 优雅停止服务。
• 一键安装计算节点 Quickcheck 启动竞态 (#637)：计算节点启动后检查容错短暂启动竞态。
• 一键安装 DATABASE_URL 持久化 (#611)：DATABASE_URL 持久化到本地 MySQL 的安装和 systemd 启动路径。
• Python SDK 流式文件体 (377a99dc)：IPOverrideTransport 中请求体拷贝前先缓冲，修复 multipart 上传失败。
• CubeProxy 日志清理 (#593)：移除 CubeProxy 中的无效日志字段和失效后端桩代码。
• envd 命令环境变量传递修复 (#566)：修复通过 commands.run 启动 envd 时 create-time 环境变量丢失的问题。
• Sandbox Preview 路由修复 (#570)：修复缺失的 /cube/sandbox/preview 路由处理器，此前 cubemastercli tpl render 会静默失败。
• 一键升级 Bundle 完整性修复 (#597)：修复一键升级包中缺失 scripts/common/ 目录导致升级预检脚本不可用的问题。
• Template 创建 Cube CA 转发修复 (#652)：修复创建模板时 with_cube_ca 参数未正确转发的问题，确保客户端能够控制是否将 CubeEgress 根 CA 注入模板 rootfs。
• 腾讯云部署 semver 辅助函数 (#587)：增加 semver_compare 和 version_lt 函数，确保升级决策逻辑正确。

📚 文档

• ARM64 部署指南 (64931ff2)：所有部署指南（快速入门、裸金属、开发环境、多节点、自构建）更新中英文，增加架构特定说明，标注 ARM64 PVM 限制。
• 网络安全加固指南 (#663)：中英文运维安全指南，覆盖控制面攻击面、绑定策略、认证回调配置、TLS/凭证指引。
• 腾讯云 Terraform 部署指南 (ae81121d)：中英文完整 Terraform 集群部署指南。
• 快照/克隆/回滚深度解析 (#680)：中英文技术深度解析博客，介绍快照、克隆和回滚机制。
• 沙箱日志指南 (#692)：新增 cubecli logs 使用指南及示例。
• 多节点调度器评分指引 (#672)：配置多节点调度器评分以实现工作负载均衡分布的指引。
• Host Mount 权限修复 (#560)：Host Mount 权限处理说明文档。
• v0.4.0 发布博客 (#585)：中英文版本发布公告和 Agent 友好服务技术博客。
• 网络深度解析博客 (#627)：中英文 CubeSandbox 网络技术深度解析。
• README 优化 (#640、#666、#646)：产品亮点、v0.4 展示、基准测试报告链接、架构图更新、主页标语优化。
• 文档优化 (#665)：交叉文档链接修复、快照/回滚/克隆侧边栏导航、本地化文档流保持 (#668、#664)。
• 安装指南链接 (#475、#466)：基准测试博客中增加安装指南引导，安装错误消息中增加问题排查链接。

⚙️ 工程改进

• Multi-Arch CI (#720)：Builder image、VMLinux、one-click release 工作流均支持 amd64 + arm64，产生分架构制品和 Multi-Arch Manifest。
• Python SDK 发布工作流 (#700)：GitHub Actions 工作流，由 python-sdk-v* 标签触发 PyPI 发布。版本交叉校验（tag vs pyproject.toml vs __init__.py），智能变更检测（跳过无变化的发布），twine check 验证。
• Cubelet 上报默认间隔 (#722)：上报告间隔默认值改为 1s，提供更灵敏的指标。
• CI Release 工作流加固 (#724)：为 gh release 命令添加 --repo 参数，确保正确的仓库指向。

title: v0.4.0 — 2026.06.14

2026.06.14 Release v0.4.0

CubeSandbox 0.4.0 introduces CubeEgress, an OpenResty-based security proxy that brings credential injection, domain filtering, and access auditing to sandbox egress traffic. This release also delivers container log forwarding with a new cubecli logs command, a node component version matrix with cluster-wide visibility, template replica compatibility checking, a daemonless template image build pipeline, and significant network performance improvements (35% faster network P50). The builder base image has been downgraded to ubuntu:20.04, lowering the minimum glibc requirement from 2.34 to 2.31 for broader distribution compatibility. 58 commits from 15 contributors.

🎯 Major Features

CubeEgress: Security Proxy

CubeEgress is a new OpenResty-based egress gateway that sits in the sandbox outbound traffic path via TPROXY, enforcing L7 policy before requests leave the cluster. It consists of ~2,200 lines of Lua across 9 modules running on OpenResty/nginx, plus Go-side integration in CubeMaster (CA provisioning, policy push), network-agent (TPROXY iptables rules), and Cubelet (per-sandbox routing, protobuf egress rule model).

• Credential injection (#518): Per-sandbox secrets are attached to outbound requests at the proxy layer via EgressRule.inject — user code inside the sandbox never handles raw credentials. The CubeNetworkConfig protobuf message (formerly CubeVSContext) now carries L7 egress rules with match conditions (SNI, host, method, path, scheme) and actions (allow/deny, audit, inject). Credential material is redacted as ***REDACTED*** in CubeMaster safe-log output (#520).
• Domain filtering (#518): Policy-driven allow/deny lists gate which destinations a sandbox may reach, evaluated first-match-wins against the L7 request. DNS queries are permitted even when domain-based allow-out rules are set (38fe9977).
• Access auditing (#518): Structured JSON logs of every egress request with optional body redaction via a redactor Lua module, enabling downstream compliance review.
• Kernel 5.4 compatibility (38fe9977): The security proxy runs on kernel v5.4+, expanding deployment coverage.
• CubeVS fast-path hardening (#527): SYN-only packets are now rejected in the port-mapping BPF fast path, preventing guest-initiated connection attempts from bypassing egress policy.
• TAP TX offload (#505): TX checksum/TSO offload and tx-tcp-mangleid-segmentation are enabled on TAP devices so redirected packets skip GSO before reaching the guest.
• CubeEgress version reporting (9d76195e): CubeEgress participates in the node component version matrix with build-time version metadata injection, a /admin/v1/health endpoint extension, release manifest entries, and cubelet-side file-based collection.

New files: CubeEgress/ (20 files — Lua modules, nginx config, Dockerfile, iptables scripts, systemd units, CA generation); CubeMaster/pkg/service/httpservice/cube/ca_download.go; CubeMaster/pkg/templatecenter/cube_egress_ca/; CubeMaster/pkg/templatecenter/cube_egress_ca_bake.go; DB migration 0005_cube_egress.sql.

Container Log Forwarding

Container init-process stdout/stderr is now streamed from the agent to the shim via a dedicated vsock connection and appended to log files on the host. A new cubecli cubebox logs subcommand lets operators read these logs from outside the sandbox.

• Log streaming (#535): The shim injects a cube.container.log_forwarding=true annotation into the OCI spec, causing the agent to create stdout/stderr pipes (1 MiB buffer, O_NONBLOCK) for the init process. A dedicated vsock channel carries the log stream to the shim, which appends to /data/log/template/<id>/stdout|stderr during template builds and to ./stdout / ./stderr in the bundle directory for normal sandboxes. Log forwarding is cleanly cancelled before pause/snapshot/teardown, and pipe write fds are closed on process exit so readers receive EOF (#541). Exec I/O relay (FIFO-based) is kept separate from init log forwarding.
• cubecli cubebox logs (#528): New subcommand to read container stdout/stderr from /data/cubelet/state/io.containerd.runtime.v2.task/default/<id>/stdout|stderr. Supports --tail N, --head N, --all, and --stderr flags. Since log files live inside the cubelet mount namespace, the command re-execs itself via the existing C constructor in pkg/cubemnt/nsenter.c to safely enter the namespace before any Go code runs. Includes openNoFollow() path validation hardened against symlink-following attacks.

Node Component Version Matrix

A new version tracking infrastructure gives operators cluster-wide visibility of component versions across all nodes, with a dedicated Web UI page.

• Version collection and matrix (#500): Cubelet collects component versions (guest-image, cube-agent, kernel, plus control-plane components from the release manifest) and reports them to CubeMaster, which maintains a version matrix in the node_component_version table (DB migration 0004). The matrix groups nodes by reported version for each component, surfaces version skew, and exposes summary and detail APIs through CubeAPI.
• Standardized version injection (#493): All Go and Rust binaries now receive version, commit, and build-time metadata via ldflags / build.rs. A machine-readable release-manifest.json is generated in one-click release bundles so every artifact is traceable to the same release. The cubecli version and cubemastercli version output formats are unified across components.
• Web UI Versions page (#500, #481): A new Versions.tsx page (762 lines) with i18n support (en/zh) shows per-component version distribution across nodes. The sidebar and Settings About section now display the actual release tag (injected at build time as __APP_VERSION__) instead of hardcoded versions.

New files: CubeMaster/pkg/nodemeta/versionmatrix.go; web/src/pages/Versions.tsx; web/src/locales/en/versions.json, zh/versions.json; DB migration 0004_node_component_version.sql.

Template Replica Compatibility

Template replicas are now checked against node component versions, with stale/missing replicas surfaced in both the API and Web UI.

• Compatibility matrix and version binding (#510): The template compatibility system compares each template's bound component versions (guest-image, cube-agent, kernel) against what each node currently reports. Results are stored in template_versions (DB migration 0006) and exposed via /templates/compat (summary) and /templates/compat/{id} (per-template detail). Version binding management lets operators pin a template to specific component versions at creation time.
• Web UI (#545): The template detail page now shows per-replica compatibility badges, version delta between bound and current component versions, and a stale-replica warning banner with a rebuild trigger. New components: CompatBadge, CompatSection, CompatWarning, CompatNodeCard, VersionDeltaList.

New files: CubeMaster/pkg/templatecenter/compat.go; CubeMaster/pkg/service/httpservice/cube/template_compat.go; DB migration 0006_template_replica_compat.sql.

Template Image Build Pipeline Overhaul

The template image build pipeline has been rearchitected to support daemonless operation via skopeo/umoci, with a 72% reduction in peak disk usage and file-level content deduplication.

• Daemonless export path (#492, #506): When skopeo and umoci are available on the CubeMaster node, template images are pulled via skopeo copy into a local OCI layout and unpacked with umoci unpack --rootless, eliminating the Docker daemon requirement. Falls back to Docker for backward compatibility. The export strategy is chosen once at image resolution time so preparation and export stay consistent.
• Artifact management (#506): A new job runner orchestrates the full pipeline (image export → rootfs artifact build → distribution), with redo support that can resume from the last completed phase. File-level content fingerprints (SHA256) enable artifact deduplication across builds, and artifact cleanup is managed through a structured lifecycle. Redo operations now carry the correct template ID through working requests (#544).
• Disk usage optimization (#472): Peak disk usage during image-to-ext4 build is reduced from ~4.2× to ~1.2× image size through five complementary optimizations:
  1. Pipe-streamed export: Docker export stdout is connected directly to tar -xf stdin via a 1 MiB pipe (F_SETPIPE_SZ), eliminating the intermediate rootfs.tar file.
  2. Early workDir cleanup: The scratch workDir is removed immediately after the rootfs reaches the store directory, before ext4 creation begins.
  3. Precise ext4 sizing: Power-of-2 alignment is replaced with a triple-overhead model (fixed 256 MiB + 10% of data + 1 KiB per file), aligned to 256 MiB boundaries.
  4. Direct-to-storeDir export: On local fast filesystems (detected via statfs magic), the rootfs is exported directly into the store directory, skipping the workDir→storeDir relocate step. NFS/CIFS fall back to the relocate path to avoid cross-device copies.
  5. Disk-space pre-check: A fail-fast statfs check on the store directory parent ensures sufficient space before the build starts, with a configurable safety margin (CUBEMASTER_DISK_SPACE_SAFETY_MARGIN, default 1.5×). SHA256 computation uses a 4 MiB buffer to reduce read syscalls. A loop-mount streaming ext4 build phase (gated behind CUBEMASTER_LOOP_MOUNT_EXT4_ENABLED, default false) is also implemented with CAP_SYS_ADMIN detection.
• SDK alignment (#485): CubeAPI POST /templates and Python/Go SDKs now expose DNS, egress CIDRs, registry auth, command/args, network type, and node scope options, matching the full cubemastercli template create-from-image option set.

New files: CubeMaster/pkg/templatecenter/image/ (export, ext4, disk, command, ref, source, types, paths, util); CubeMaster/pkg/templatecenter/artifact_build.go, artifact_cleanup.go, distribution.go, fingerprint.go, image_job_runner.go, job_constants.go, job_dto.go.

Network Performance

• TAP fd acquisition optimization (#487): A three-tier GetTapFile strategy replaces the old single-path approach:

  • Fast path: When state.tap.File is already cached, return it immediately (0 syscalls).
  • Hot path: For pooled taps with a closed fd, reopen with just 2 syscalls (open + TUNSETIFF), skipping the expensive restoreTap flow (netlink lookup, LinkSetUp, SetMTU, TC filter attach, ARP entry).
  • Recovery path: Fall back to full restoreTap only when there is no in-memory state or the tap is held externally.

  The fdserver JSON response now includes the ifindex, allowing cubelet to skip its own netlink.LinkByName call — eliminating a serialization point during concurrent sandbox creation. Cubelet falls back to LinkByName only when ifindex is 0 (backward-compatible with older agents).

  A TOCTOU race between EnsureNetwork and ReleaseNetwork is fixed by replacing singleflight-style dedup with a per-sandbox creating guard channel registered in the same critical section as the state check. Includes a pprof debug server (--pprof-listen flag) and 390 lines of concurrency tests (6 functions, 64-goroutine stress test clean under -race).

  Benchmarks (BMI5, Xeon Platinum 8255C, kernel 6.6.119): Network P50 35.3→23.1ms (35% faster), Network P99 86.6→51.2ms (41% faster), Total P50 106.1→92.0ms (13% faster), Throughput 194.8→209.8 sandboxes/s (8% higher).

• BPF checksum optimization (#469): bpf_csum_diff() is replaced with bpf_{l3,l4}_csum_replace helpers in both from_world and from_cube BPF programs. Combined with the TAP TX offload work (#505), this enables TSO/UFO/CSUM offloads to be re-enabled on virtio-net TAPs (reverting #110), and the disableGRO() requirement on host NICs is dropped.

✨ Enhancements

Scheduling

• Configurable overcommit and Redis allocation bypass (#525): Two new scheduler configuration knobs: overcommit_ratio (default CPU=3, Mem=2) with optional per-instance-type overrides via overcommit_ratio_conf, and ignore_redis_allocation (default false) to treat Redis-recorded allocations as zero. Applied consistently across filter and score plugins, with non-positive ratios clamped back to defaults. Physical load guards (CPU utilization ceiling, real-time free memory) are intentionally preserved.

Affinity

• Custom node affinity selector (#504, #467): The com.nodeaffinity.selector annotation now accepts arbitrary NodeSelectorRequirements (In, NotIn, Exists, DoesNotExist, Gt, Lt) as a JSON array of {key, operator, values}. Node labels from registration are carried through Node.NodeLabels, merged into Labels() with an atomic.Pointer cache and InvalidateLabelsCache() for mutation safety. DoS hardening: max annotation size 4 KB, 10 selectors per request, 50 values per In/NotIn. Configurable allowed keys default to zone, cluster-id, cpu-type, memory-size, cpu-cores, instance-type. 872 lines of tests covering 47 cases.

Template Management

• tpl- prefix enforcement (#474): Template IDs are now always auto-generated with a tpl- prefix across all creation paths (API, CLI, Web UI, sandbox commit). User-specified IDs are accepted for backward compatibility but silently ignored — the server always returns an auto-generated tpl- prefixed ID as the authoritative template identifier. Validation rejects bare tpl- / snap- prefixes and non-conforming annotation prefixes.
• Builder image downgrade to ubuntu:20.04 (#468): The builder base image is changed from ubuntu:22.04 to ubuntu:20.04, lowering the minimum glibc requirement from 2.34 to 2.31. Affects Dockerfile.builder, one-click installer preflight checks, CI workflows, and documentation.

Web UI

• Template policy display (#486): The template detail page now shows environment variables, network type, internet access, DNS servers, allow-out rules, and deny-out rules parsed from createRequest. A dedicated "Network Policy" section includes per-rule copy buttons. A BoolBadge component is extracted as a shared UI primitive.
• CubeAPI container image (#513): A container build for the cube-api service produces a self-contained runtime image suitable for one-click and orchestrated deployments, with a lean build context.

SDK

• Python SDK v0.3.0 (#521): Bump to 0.3.0 with new APIs for security proxy configuration.

PVM

• Kernel LOCALVERSION rename (#511, #534): The PVM host and guest kernel LOCALVERSION is renamed to a clean descriptive scheme so the distribution base and host/guest role are obvious from uname -r. Deployment configs, user-facing guides, and blog references are updated to match.

🐛 Bug Fixes

These fixes address issues present in v0.3.1:

• Virtiofs config skipped when shareDirs is empty (#533): Cubelet no longer generates virtiofs configuration or annotations when no shared directories are specified, preventing broken config generation.
• DNS server IP automatically added to AllowOut (#526): When any DNS rule is configured, the DNS server IP is now added to AllowOut to ensure DNS resolution works through egress policy. Includes regression test coverage.
• Cubelog nil trace panic (#512): Background workers and detached job contexts that run without a request trace no longer panic on nil dereference — trace handling is now tolerant of a missing trace.
• Storage symlink resolution in host-dir cleanup (#530): cleanupHostDirVolumes now resolves base-path symlinks when walking sandbox directories, so bind mounts under paths like /data → /mnt/ssd/data are correctly identified and unmounted instead of leaking or having their backing directories wiped.
• Network plugin bootstrap warnings (#491): Cubelet startup no longer logs valid network configuration keys as "unknown TOML fields" — the existing config struct is now reused when reading bootstrap overrides.
• DNS not auto-allowed when internet is disabled (#490): When AllowInternetAccess=false, resolved DNS servers are no longer appended to allow_out, so the deny-all outbound policy consistently blocks DNS resolution. Fixes #408.
• Ripgrep dependency removed from one-click runtime (#496): The one-click install and startup path no longer requires or auto-installs ripgrep. Shell checks now use grep-based helpers.
• Virtiofs migration_on_error set to GuestError (#482): The native virtiofs server now uses MigrationOnError::GuestError instead of Abort. Per-inode failures during snapshot restore surface as guest FS errors (ENOENT/EIO) on the affected paths rather than tearing down the entire live migration.
• VMM virtio-fs queue fault tolerance (#464): process_queue_serial() no longer panics on malformed descriptors. Failures are recovered by writing an EIO FUSE error reply to the guest and continuing to serve the queue. A new device_memory view is added for device-backed memory regions (virtio-pmem, virtio-fs DAX, ivshmem/zshm BARs).
• Cgroup v2 manager creation (#488): The agent now uses the cgroup v2 creation path from cgroups-rs and attaches container processes through cgroup.procs, avoiding v1 controller name failures in unified cgroup mode. Process ID collection for cleanup and signals also reads from cgroup.procs.
• Node health expiry on stale heartbeat (#455): Node health is now derived from heartbeat freshness — stale heartbeats are correctly reported as unhealthy in nodemeta reads, localcache-backed reads, and scheduler prefilter. A shared helper centralizes the timeout rule across all three paths.
• SELinux context restore after one-click install (#471): File contexts under the install prefix are now restored before starting systemd services, fixing one-click installs on SELinux Enforcing hosts. Fixes #465.
• Glibc preflight pipefail race (#473): The ldd --version output is now fully captured before parsing, preventing strict-mode preflight checks from exiting on an expected SIGPIPE.
• Python SDK streaming request body read (377a99dc): Request bodies in IPOverrideTransport are now buffered before copying, so multipart uploads no longer fail with RequestNotRead.
• CLI help text corrections (#478): Fixed incorrect command names (e.g., cuebcli → cubecli), spelling mistakes, outdated deprecation hints, and truncated descriptions in both cubecli and cubemastercli.

📚 Documentation

• DEB install instructions (#532): Added apt (DEB) install instructions alongside existing yum (RPM) steps for Python SDK setup in the Quick Start guide.
• Benchmark blog env var fixes (#497): Fixed benchmark setup examples that mixed environment variables from different client stacks — E2B variables for e2b_code_interpreter examples, CUBE_API_URL + CubeProxy settings for CubeSandbox SDK examples.
• CNCF Landscape badge (#477): Added CNCF Landscape badge and footer note to README in both English and Chinese.
• Template ID documentation cleanup (#476): Removed all --template-id flags from create-from-image documentation and examples since template IDs are now auto-generated with tpl- prefix.
• Install guide links in benchmark posts (#475): Added installation guide callouts to the §2.1 Hardware section of all four benchmark blog posts (EN + ZH, bare-metal + PVM).
• Troubleshooting links (#466): Added GitHub issue #311 troubleshooting URL to XFS filesystem check error messages in install.sh, online-install.sh, and check-deps.sh. Updated install docs to use direct links to the Releases page.
• CODEOWNERS (#522): Added CubeEgress maintainer entry.

⚙️ Engineering Improvements

• Build system reorganization (#529): Per-target .PHONY declarations replace the single bulk list. A new clean-rust-target-dirs target removes target/ under each top-level Rust workspace. The all target is driven from a shared BINARIES list.
• Format check CI (#524): fmt targets are added to all component Makefiles (Go and Rust), with a new .github/workflows/fmt-check.yml CI workflow that runs format checking on PRs. The agent's fmt target automatically generates required files (version.rs, protocol .rs) before formatting.
• CI review-comment via stdin (#494): PR review comments are now passed via stdin (--body-file -) instead of temp files, keeping review content out of the checkout directory.
• CI auto-review comment reuse (#489): Automated review comments now update the bot's existing marked comment on repeated PR synchronizations instead of creating new top-level comments each time.
• Metric report jitter (#479): The Cubelet CLS metric report loop now adds random jitter (uniformly distributed between [t, 1.5t]) to prevent thundering herd issues when multiple agents start concurrently.

title: v0.4.0 — 2026.06.14

2026.06.14 发布 v0.4.0

CubeSandbox 0.4.0 引入了 CubeEgress，一个基于 OpenResty 的安全代理，为沙箱出站流量提供凭据注入、域名过滤和访问审计能力。本版本还带来了容器日志转发及配套的 cubecli logs 命令、节点组件版本矩阵（集群范围版本可见性）、模板副本兼容性检查、无守护进程的模板镜像构建管线，以及显著的网络性能提升（网络 P50 延迟降低 35%）。构建基础镜像已降级至 ubuntu:20.04，将最低 glibc 要求从 2.34 降低到 2.31，以覆盖更广泛的发行版。58 个 commits，15 位贡献者。

🎯 主要特性

CubeEgress：安全代理

CubeEgress 是一个全新的基于 OpenResty 的出站网关，通过 TPROXY 截获沙箱出站流量，在请求离开集群之前执行 L7 策略。它由运行在 OpenResty/nginx 上的 9 个 Lua 模块（约 2200 行代码）以及 Go 端的集成组成——CubeMaster（CA 颁发、策略下发）、network-agent（TPROXY iptables 规则）和 Cubelet（按沙箱路由、protobuf 出站规则模型）。

• 凭据注入（#518）：每个沙箱的密钥通过 EgressRule.inject 在代理层附加到出站请求中——沙箱内的用户代码永远不会接触到原始凭据。CubeNetworkConfig protobuf 消息（原 CubeVSContext）现在携带 L7 出站规则，包含匹配条件（SNI、host、method、path、scheme）和动作（allow/deny、audit、inject）。凭据信息在 CubeMaster 安全日志输出中被替换为 ***REDACTED***（#520）。
• 域名过滤（#518）：基于策略的 allow/deny 列表控制沙箱可访问的目标地址，按 L7 请求进行首次匹配即生效。即使设置了基于域名的 allow-out 规则，DNS 查询仍被允许（38fe9977）。
• 访问审计（#518）：每个出站请求的结构化 JSON 日志，支持通过 redactor Lua 模块进行可选的请求体脱敏，便于下游合规审查。
• Kernel 5.4 兼容（38fe9977）：安全代理可在 kernel 5.4+ 上运行，扩大了部署覆盖范围。
• CubeVS 快速路径加固（#527）：在端口映射的 BPF 快速路径中拒绝纯 SYN 包，防止客户发起的连接尝试绕过出站策略。
• TAP TX 卸载（#505）：在 TAP 设备上启用 TX checksum/TSO 卸载和 tx-tcp-mangleid-segmentation，使重定向的数据包在到达客户机之前无需进行 GSO。
• CubeEgress 版本上报（9d76195e）：CubeEgress 接入节点组件版本矩阵，具备构建时版本元数据注入、/admin/v1/health 端点扩展、发布清单条目和 cubelet 端基于文件的版本采集能力。

新增文件：CubeEgress/（20 个文件——Lua 模块、nginx 配置、Dockerfile、iptables 脚本、systemd 单元、CA 生成）；CubeMaster/pkg/service/httpservice/cube/ca_download.go；CubeMaster/pkg/templatecenter/cube_egress_ca/；CubeMaster/pkg/templatecenter/cube_egress_ca_bake.go；数据库迁移 0005_cube_egress.sql。

容器日志转发

容器 init 进程的 stdout/stderr 现在通过专用的 vsock 连接从 agent 流式传输到 shim，并追加到宿主机的日志文件中。新增的 cubecli cubebox logs 子命令允许运维人员从沙箱外部读取这些日志。

• 日志流式传输（#535）：shim 向 OCI 规范注入 cube.container.log_forwarding=true 注解，指示 agent 为 init 进程创建 stdout/stderr 管道（1 MiB 缓冲区，O_NONBLOCK）。专用的 vsock 通道将日志流传输到 shim，在模板构建期间写入 /data/log/template/<id>/stdout|stderr，普通沙箱写入 bundle 目录下的 ./stdout 和 ./stderr。日志转发在暂停/快照/销毁之前会被干净地取消，进程退出时管道的写端文件描述符被关闭以确保读取端收到 EOF（#541）。exec I/O 中继（基于 FIFO）与 init 日志转发保持分离。
• cubecli cubebox logs（#528）：新增子命令，用于从 /data/cubelet/state/io.containerd.runtime.v2.task/default/<id>/stdout|stderr 读取容器 stdout/stderr。支持 --tail N、--head N、--all 和 --stderr 选项。由于日志文件位于 cubelet 的挂载命名空间内，该命令通过 pkg/cubemnt/nsenter.c 中现有的 C 构造函数重新执行自身，在任何 Go 代码运行之前安全地进入该命名空间。包含 openNoFollow() 路径验证以防止符号链接跟随攻击。

节点组件版本矩阵

全新的版本追踪基础设施为运维人员提供了集群范围内所有节点组件版本的可见性，并配有专属的 Web UI 页面。

• 版本采集与矩阵（#500）：Cubelet 采集各组件版本（guest-image、cube-agent、kernel，以及来自发布清单的控制面组件），并上报给 CubeMaster。CubeMaster 在 node_component_version 表（数据库迁移 0004）中维护版本矩阵，按组件对报告同一版本的节点进行分组，暴露版本偏差，并通过 CubeAPI 对外提供汇总和详情接口。
• 统一的版本注入（#493）：所有 Go 和 Rust 二进制文件现在通过 ldflags / build.rs 接收 version、commit 和 build-time 元数据。一键部署发布包中生成机器可读的 release-manifest.json，确保每个构建产物都可追溯到同一发布版本。cubecli version 和 cubemastercli version 的输出格式在各组件间保持一致。
• Web UI 版本页面（#500, #481）：新增 Versions.tsx 页面（762 行），支持中英文国际化，展示各组件在节点间的版本分布。侧边栏和设置页的"关于"部分现在显示实际的发布标签（构建时注入为 __APP_VERSION__），而非硬编码的版本号。

新增文件：CubeMaster/pkg/nodemeta/versionmatrix.go；web/src/pages/Versions.tsx；web/src/locales/en/versions.json、zh/versions.json；数据库迁移 0004_node_component_version.sql。

模板副本兼容性

模板副本现在与节点组件版本进行对比检查，过时/缺失的副本会在 API 和 Web UI 中暴露出来。

• 兼容性矩阵与版本绑定（#510）：模板兼容性系统将每个模板绑定的组件版本（guest-image、cube-agent、kernel）与每个节点当前上报的版本进行比较。结果存储在 template_versions 表（数据库迁移 0006）中，通过 /templates/compat（汇总）和 /templates/compat/{id}（单个模板详情）接口对外暴露。版本绑定管理允许运维人员在创建时将模板固定到特定的组件版本。
• Web UI（#545）：模板详情页现在展示每个副本的兼容性标记、绑定版本与当前组件版本之间的版本差异，以及过时副本的警告横幅（含重建触发器）。新增组件：CompatBadge、CompatSection、CompatWarning、CompatNodeCard、VersionDeltaList。

新增文件：CubeMaster/pkg/templatecenter/compat.go；CubeMaster/pkg/service/httpservice/cube/template_compat.go；数据库迁移 0006_template_replica_compat.sql。

模板镜像构建管线重构

模板镜像构建管线经过重新架构，支持通过 skopeo/umoci 进行无守护进程操作，峰值磁盘使用量降低 72%，并具备文件级内容去重能力。

• 无守护进程导出路径（#492, #506）：当 CubeMaster 节点上可用 skopeo 和 umoci 时，模板镜像通过 skopeo copy 拉取到本地 OCI 布局，并用 umoci unpack --rootless 解包，完全消除对 Docker 守护进程的依赖。不可用时自动回退到 Docker 以保证向后兼容。导出策略在镜像解析时一次性选定，确保准备和导出阶段保持一致。

• 制品管理（#506）：新增 job runner 编排完整管线（镜像导出 → rootfs 制品构建 → 分发），支持 redo（重做）操作并可从中断的阶段恢复。文件级内容指纹（SHA256）实现制品跨构建去重，制品清理通过结构化的生命周期进行管理。Redo 操作现在通过 working request 携带正确的模板 ID（#544）。

• 磁盘使用优化（#472）：通过五项互补优化，将镜像到 ext4 构建过程中的峰值磁盘使用量从约 4.2 倍镜像大小降低到约 1.2 倍：

  1. 管道流式导出：Docker export 的标准输出通过 1 MiB 管道（F_SETPIPE_SZ）直接连接到 tar -xf 的标准输入，消除中间的 rootfs.tar 文件。
  2. 提前清理工作目录：rootfs 到达存储目录后立即删除临时工作目录，而非等到 ext4 创建完成之后。
  3. 精确的 ext4 空间估算：将 2 的幂次对齐替换为三重开销模型（固定 256 MiB + 数据的 10% + 每文件 1 KiB），按 256 MiB 边界对齐。
  4. 直接导出到存储目录：在本地快速文件系统上（通过 statfs magic 检测），rootfs 直接导出到存储目录，跳过 workDir→storeDir 的搬迁步骤。NFS/CIFS 回退到搬迁路径以避免跨设备复制。
  5. 磁盘空间预检查：构建开始前对存储目录父目录进行 statfs 检查，配合可配置的安全边界（CUBEMASTER_DISK_SPACE_SAFETY_MARGIN，默认 1.5 倍）。

  SHA256 计算使用 4 MiB 缓冲区以减少 read 系统调用。基于 loop-mount 的流式 ext4 构建阶段（由 CUBEMASTER_LOOP_MOUNT_EXT4_ENABLED 控制，默认关闭）也已实现，含 CAP_SYS_ADMIN 能力检测。

• SDK 对齐（#485）：CubeAPI POST /templates 以及 Python/Go SDK 现在支持 DNS、出口 CIDR、镜像仓库认证、command/args、网络类型和节点范围等选项，与 cubemastercli template create-from-image 的完整选项集保持一致。

新增文件：CubeMaster/pkg/templatecenter/image/（export、ext4、disk、command、ref、source、types、paths、util）；CubeMaster/pkg/templatecenter/artifact_build.go、artifact_cleanup.go、distribution.go、fingerprint.go、image_job_runner.go、job_constants.go、job_dto.go。

网络性能

• TAP fd 获取优化（#487）：三层的 GetTapFile 策略取代了旧的单一获取路径：

  • 快速路径：当 state.tap.File 已缓存时立即返回（0 次系统调用）。
  • 热路径：对于 fd 已关闭的池化 tap，仅需 2 次系统调用（open + TUNSETIFF）重新打开，跳过昂贵的 restoreTap 流程（netlink 查找、LinkSetUp、SetMTU、TC filter 挂载、ARP 条目）。
  • 恢复路径：仅当没有内存状态或 tap 被外部持有时，才回退到完整的 restoreTap。

  fdserver JSON 响应现在包含 ifindex，使 cubelet 可以跳过自身的 netlink.LinkByName 调用——消除了并发沙箱创建过程中的一个序列化点。当 ifindex 为 0 时 cubelet 回退到 LinkByName（与旧版 agent 向后兼容）。

  通过用注册在同一临界区内的 per-sandbox creating 守护通道替换 singleflight 风格的去重，修复了 EnsureNetwork 和 ReleaseNetwork 之间的 TOCTOU 竞态条件。包含 pprof 调试服务器（--pprof-listen 选项）和 390 行并发测试（6 个测试函数，64 协程压力测试通过 -race 检测）。

  基准测试（BMI5, Xeon Platinum 8255C, kernel 6.6.119）：网络 P50 35.3→23.1ms（提升 35%），网络 P99 86.6→51.2ms（提升 41%），总 P50 106.1→92.0ms（提升 13%），吞吐量 194.8→209.8 sandboxes/s（提升 8%）。

• BPF 校验和优化（#469）：在 from_world 和 from_cube 两个 BPF 程序中，将 bpf_csum_diff() 替换为 bpf_{l3,l4}_csum_replace 辅助函数。结合 TAP TX 卸载工作（#505），使 TSO/UFO/CSUM 卸载得以在 virtio-net TAP 上重新启用（回滚 #110），同时取消了对宿主机网卡的 disableGRO() 要求。

✨ 功能增强

调度

• 可配置的超卖比例和 Redis 分配旁路（#525）：新增两个调度器配置参数：overcommit_ratio（默认 CPU=3, Mem=2），支持通过 overcommit_ratio_conf 按实例类型覆盖；ignore_redis_allocation（默认 false），将 Redis 中记录的已分配资源视为零。在 filter 和 score 插件中一致生效，非正数的比例值会被重置为默认值。物理负载保护（CPU 利用率上限、实时空闲内存）被有意保留。

亲和性

• 自定义节点亲和性选择器（#504, #467）：com.nodeaffinity.selector 注解现在接受任意的 NodeSelectorRequirements（In、NotIn、Exists、DoesNotExist、Gt、Lt），以 JSON 数组 {key, operator, values} 的形式传入。节点注册标签通过 Node.NodeLabels 传递，合并到 Labels() 中，并使用 atomic.Pointer 缓存和 InvalidateLabelsCache() 确保变更安全。DoS 防护：最大注解大小 4 KB，每个请求最多 10 个选择器，每个 In/NotIn 最多 50 个值。可配置的允许键默认包括 zone、cluster-id、cpu-type、memory-size、cpu-cores、instance-type。872 行测试覆盖 47 个场景。

模板管理

• tpl- 前缀强制（#474）：所有创建路径（API、CLI、Web UI、沙箱提交）的模板 ID 现在统一自动生成 tpl- 前缀。为保持向后兼容，用户指定的 ID 仍然被接受但会被静默忽略——服务端始终返回自动生成的 tpl- 前缀 ID 作为权威模板标识符。验证逻辑拒绝裸的 tpl- / snap- 前缀以及不符合规范的注解前缀。
• 构建镜像降级至 ubuntu:20.04（#468）：构建基础镜像从 ubuntu:22.04 更换为 ubuntu:20.04，将最低 glibc 要求从 2.34 降至 2.31。影响 Dockerfile.builder、一键部署预检脚本、CI 工作流和文档。

Web UI

• 模板策略展示（#486）：模板详情页现在展示环境变量、网络类型、互联网访问权限、DNS 服务器、allow-out 规则和 deny-out 规则（从 createRequest 解析）。新增的"网络策略"区域包含每条规则的快捷复制按钮。BoolBadge 组件被提取为共享 UI 原语。
• CubeAPI 容器镜像（#513）：为 cube-api 服务提供容器构建，产出适合一键部署和编排部署的自包含运行时镜像，构建上下文精简。

SDK

• Python SDK v0.3.0（#521）：升级至 0.3.0，新增安全代理相关的 API。

PVM

• 内核 LOCALVERSION 重命名（#511, #534）：PVM 宿主机和客户机内核的 LOCALVERSION 被重命名为清晰、自描述的风格，使发行版基础和宿主机/客户机角色可通过 uname -r 一目了然。部署配置、用户指南和博客引用均已同步更新。

🐛 Bug 修复

以下修复针对 v0.3.1 中已存在的问题：

• shareDirs 为空时跳过 virtiofs 配置（#533）：当没有指定共享目录时，Cubelet 不再生成 virtiofs 配置或注解，防止产生无效的配置。
• 自动将 DNS 服务器 IP 加入 AllowOut（#526）：当配置了任何 DNS 规则时，DNS 服务器 IP 现在会被自动加入 AllowOut，确保 DNS 解析能够通过出站策略。包含回归测试覆盖。
• Cubelog nil trace panic（#512）：没有请求追踪上下文的后台 worker 和分离的 job 上下文不再因空指针解引用而 panic——trace 处理现在对缺失的 trace 具备容错能力。
• 存储清理时的符号链接解析（#530）：cleanupHostDirVolumes 现在遍历沙箱目录时会解析基础路径的符号链接，使得位于符号链接路径下（如 /data → /mnt/ssd/data）的 bind mount 能够被正确识别并卸载，避免泄漏或误删后端目录。
• 网络插件启动警告（#491）：Cubelet 启动时不再将合法的网络配置键记录为"未知 TOML 字段"——读取启动覆盖配置时现在复用现有的配置结构体。
• 禁用互联网时不自动放行 DNS（#490）：当 AllowInternetAccess=false 时，解析出的 DNS 服务器不再被追加到 allow_out，使 deny-all 出站策略能够一致地阻断 DNS 解析。修复 #408。
• 移除一键部署运行时对 ripgrep 的依赖（#496）：一键部署安装和启动路径不再要求或自动安装 ripgrep。Shell 检查已改用基于 grep 的辅助函数。
• Virtiofs migration_on_error 设为 GuestError（#482）：原生 virtiofs 服务器现在使用 MigrationOnError::GuestError 替代 Abort。快照恢复期间的单文件错误会以客户机 FS 错误（ENOENT/EIO）的形式体现在受影响的路径上，而不会中断整个热迁移。
• VMM virtio-fs 队列容错（#464）：process_queue_serial() 不再因畸形描述符而 panic。失败时通过向客户机回复 EIO FUSE 错误并继续处理队列来恢复。新增 device_memory 视图用于设备后端内存区域（virtio-pmem、virtio-fs DAX、ivshmem/zshm BAR）。
• Cgroup v2 管理器创建（#488）：Agent 现在使用 cgroups-rs 提供的 cgroup v2 创建路径，并通过 cgroup.procs 挂载容器进程，避免了在 unified cgroup 模式下使用 v1 控制器名称导致的失败。清理和信号发送的进程 ID 收集也从 cgroup.procs 读取。
• 心跳超时后节点健康过期（#455）：节点健康现在从心跳新鲜度中推导——过时的心跳在 nodemeta 读取、localcache 读取和调度器 prefilter 中都会被正确地报告为不健康。共享的辅助函数统一了这三条路径中的超时规则。
• 一键部署安装后恢复 SELinux 上下文（#471）：安装前缀下的文件上下文现在会在启动 systemd 服务之前恢复，修复了 SELinux Enforcing 主机上的一键部署安装问题。修复 #465。
• Glibc 预检 pipefail 竞态（#473）：ldd --version 的输出现在会在解析前完整捕获，避免严格模式下的预检因预期的 SIGPIPE 而退出。
• Python SDK 流式请求体读取（377a99dc）：IPOverrideTransport 中的请求体现在在复制前会被缓冲，使 multipart 上传不再因 RequestNotRead 而失败。
• CLI 帮助文本修正（#478）：修正了 cubecli 和 cubemastercli 中错误的命令名称（如 cuebcli → cubecli）、拼写错误、过时的弃用提示以及截断的描述文本。

📚 文档

• DEB 安装说明（#532）：在快速入门指南中新增 apt（DEB）安装说明，与现有的 yum（RPM）步骤并列。
• 基准测试博客环境变量修正（#497）：修复了混淆不同客户端栈环境变量的基准测试示例——e2b_code_interpreter 示例使用 E2B 变量，CubeSandbox SDK 示例使用 CUBE_API_URL + CubeProxy 设置。
• CNCF Landscape 徽章（#477）：在 README 中新增 CNCF Landscape 徽章和页脚说明（中英文双版）。
• 模板 ID 文档清理（#476）：从所有 create-from-image 文档和示例中移除 --template-id 选项，因为模板 ID 现在会自动生成 tpl- 前缀。
• 基准测试博文中的安装指南链接（#475）：在所有四篇基准测试博文（中英文、裸金属和 PVM）的 §2.1 硬件部分添加安装指南链接。
• 排障链接（#466）：在 install.sh、online-install.sh 和 check-deps.sh 的 XFS 文件系统检查错误消息中添加 GitHub issue #311 的排障链接。更新安装文档，使用指向 Releases 页面的直接链接。
• CODEOWNERS（#522）：新增 CubeEgress 维护者条目。

⚙️ 工程改进

• 构建系统重构（#529）：将原来单一的整体 .PHONY 声明按目标拆分。新增 clean-rust-target-dirs 目标，清理每个顶层 Rust 工作区下的 target/ 目录。all 目标现在通过共享的 BINARIES 列表驱动。
• 格式化检查 CI（#524）：为所有组件的 Makefile 添加 fmt 目标（Go 和 Rust），并新增 .github/workflows/fmt-check.yml CI 工作流在 PR 上运行格式化检查。Agent 的 fmt 目标会在格式化前自动生成必要的文件（version.rs、协议 .rs 文件）。
• CI 审查评论通过 stdin 传入（#494）：PR 审查评论现在通过 stdin（--body-file -）传递，而非临时文件，避免审查内容残留在 checkout 目录中。
• CI 自动审查评论复用（#489）：自动审查评论现在在重复的 PR 同步时更新 bot 已有的标记评论，而非每次都创建新的顶层评论。
• 指标上报抖动（#479）：Cubelet CLS 指标上报循环现在添加了随机抖动（在 [t, 1.5t] 范围内均匀分布），防止多个 agent 同时启动时产生惊群效应。

title: v0.3.1 — 2026.06.04

2026.06.04 Release v0.3.1

CubeSandbox 0.3.1 is a stabilization and hardening release following v0.3.0, focused on one-click installer robustness, network stability fixes, AgentHub refinements, and expanded documentation with real-world benchmark data. 14 commits from 7 contributors.

✨ Enhancements

One-Click Deployment

• Custom sandbox network CIDR (#451): Users can now specify CUBE_SANDBOX_NETWORK_CIDR at install time to avoid conflicts with existing host network subnets. Includes CIDR format validation, host interface/route overlap detection, and a bypass flag (CUBE_SANDBOX_NETWORK_CIDR_SKIP_CONFLICT_CHECK) for advanced scenarios. The chosen CIDR is persisted to .one-click.env after successful config patching.
• Systemd 255 ExecStart/ExecStop compatibility (#451): Prefixed all ExecStart, ExecStartPre, ExecStartPost, and ExecStop directives with /usr/bin/bash to avoid 203/EXEC errors from systemd-executor on OpenCloudOS 9.4+.
• glibc version preflight check (#457): The installer now checks glibc >= 2.34 before installation to fail fast on unsupported distributions (e.g., CentOS 7, Ubuntu 20.04), where cubelet/cubecli binaries would crash at runtime.
• PVM consistency pre-check (#456): When the kvm_pvm kernel module is loaded on the host, the installer verifies that CUBE_PVM_ENABLE=1 is set. Without this check, PVM hosts would silently install the wrong guest kernel (ordinary vmlinux instead of vmlinux-pvm), causing VM template creation to fail later with obscure errors. Configurable via ONE_CLICK_SKIP_PVM_CHECK=1.

AgentHub (Preview)

• Snapshot/rollback API routes (#426): Added snapshot creation and rollback endpoints to AgentHub, enabling the digital assistant console to manage sandbox checkpoints.
• Preview button & sandbox open logic (#426): The WebUI now includes a preview button alongside sandbox open functionality, with template store defaults corrected.
• Preview documentation (#426): Added AgentHub preview feature guides in both English and Chinese.

🐛 Bug Fixes

• Network-agent: fix existing sandbox network drop on restart (#442): When network-agent restarted, restoreTap() unconditionally tried to acquire the tap fd via TUNSETIFF, even when the TAP was still held by a running sandbox. With IFF_ONE_QUEUE, the kernel rejected the second open with EBUSY, the TAP was pushed into the abnormal pool, and the stale-cleanup branch removed its BPF map entry — silently dropping egress traffic. The fix skips getTapFd when tap.InUse is true and surfaces a clear error when no fd is available.
• Delay host DNS switchover until CoreDNS is ready (#452): On first install, the host resolv.conf was rewritten before CoreDNS was listening, causing a DNS deadlock. The installer now waits for CoreDNS to bind its port, preserves one upstream fallback resolver, and filters reserved nameserver addresses from upstream resolution paths.

Dev Environment

• Update default OpenCloudOS image to 9.6 (#447): The OpenCloudOS 9.4 qcow2 image at mirrors.tencent.com is no longer available and downloads fail. Bumped the default image URL in both prepare_image.sh and run_vm.sh to the latest 9.6-20260514.2 GenericCloud image.

📚 Documentation

• SA9.4XLARGE32 PVM benchmark report (EN + ZH) (#459): Full benchmark report on Tencent Cloud SA9.4XLARGE32 (AMD EPYC 9K65, 16 vCPU, 32 GiB RAM, 200 GiB Enhanced SSD, PVM kernel), covering cold-start latency, concurrency scaling (c=1/10/20), single-host density (~743 idle sandboxes at ~27-34 MB each), snapshot creation vs concurrency & dirty-page size, create-from-snapshot, rollback, clone, and pause/resume concurrency. Both Chinese and English versions are included.
• BMI5 bare-metal benchmark data (#450): Replaced all mock/placeholder data in the performance benchmark article (ZH + EN) with real measurements from a Tencent Cloud BMI5 bare-metal node. Refactored benchmark scripts to a single-tier CLI style for composable multi-tier sweeps, with TAP pool scaling instructions.
• v0.3.0 release blog post (#441): Added Chinese and English blog posts announcing the v0.3.0 release (snapshot/clone/rollback, AgentHub, Web UI, Go SDK). Reordered featured posts with v0.3.0 as top weight.
• trpc-agent-go use case (#446): Added a new use case documenting how trpc-agent-go leverages Cube Sandbox as a secure code execution backend, with sidebar entries in both EN and ZH documentation.
• Perf benchmark article fixes (#440): Fixed vmm.log path, added template creation command to section 2.2, and moved general conventions from section 3.1 to section 4.0 in both language versions.
• Disk space requirement update (#425): Updated minimum disk space for /data/cubelet from 300 GB to 50 GB, with a 200 GB recommendation for building multiple templates.
• Duplicate Quick Start links removed (#430): Cleaned up duplicate Quick Start links in the README, leaving only the top navigation bar entry.

👏 Contributors

7 contributors made this release possible:

@LoGin (jinlong), @ls (ls-ggg), @cherrycao, @chengjoey, @Hengqi Chen, @joeytao, @tinklone (maxlong)

title: v0.3.1 — 2026.06.04

2026.06.04 发布 v0.3.1

CubeSandbox 0.3.1 是 v0.3.0 之后的稳定性与加固版本，专注于一键安装脚本的健壮性增强、网络稳定性修复、AgentHub 功能完善，以及基于真实基准测试数据的文档扩展。14 个提交，7 位贡献者。

✨ 功能增强

一键部署

• 自定义沙箱网络 CIDR（#451）：用户现在可以在安装时通过 CUBE_SANDBOX_NETWORK_CIDR 指定沙箱网络 CIDR，以规避与宿主机现有网络子网的冲突。支持 CIDR 格式校验、宿主机接口/路由重叠检测，并提供绕过标志（CUBE_SANDBOX_NETWORK_CIDR_SKIP_CONFLICT_CHECK）用于高级场景。配置成功后会持久化到 .one-click.env。
• Systemd 255 ExecStart/ExecStop 兼容（#451）：为所有 ExecStart、ExecStartPre、ExecStartPost 和 ExecStop 指令添加 /usr/bin/bash 前缀，避免 OpenCloudOS 9.4+ 上 systemd-executor 导致的 203/EXEC 错误。
• glibc 版本预检（#457）：安装脚本现在会在安装前检查 glibc >= 2.34，在不支持的发行版（如 CentOS 7、Ubuntu 20.04）上提前失败，避免 cubelet/cubecli 二进制文件在运行时崩溃。
• PVM 一致性预检（#456）：当宿主机加载了 kvm_pvm 内核模块时，安装脚本会验证是否设置了 CUBE_PVM_ENABLE=1。如果没有此检查，PVM 宿主机将静默安装错误的 guest 内核（普通 vmlinux 而非 vmlinux-pvm），导致 VM 模板创建在后续阶段以难以排查的错误失败。可通过 ONE_CLICK_SKIP_PVM_CHECK=1 跳过。

AgentHub（Preview 预览版）

• 快照/回滚 API 路由（#426）：为 AgentHub 添加了快照创建和回滚端点，使数字助理控制台能够管理沙箱检查点。
• 预览按钮与沙箱打开逻辑（#426）：WebUI 现在包含预览按钮和沙箱打开功能，并修复了模板商店的默认值问题。
• 预览功能文档（#426）：新增中英文双语的 AgentHub 预览功能使用指南。

🐛 Bug 修复

• 修复 network-agent 重启导致现有沙箱网络中断（#442）：当 network-agent 重启时，restoreTap() 无条件尝试通过 TUNSETIFF 获取 TAP fd，即使该 TAP 仍被运行中的沙箱持有。由于 IFF_ONE_QUEUE，内核以 EBUSY 拒绝第二次打开，TAP 被推入异常池，清理分支将其 BPF 映射条目删除——导致出口流量被静默丢弃。修复方案：当 tap.InUse 为 true 时跳过 getTapFd，并在没有可用 fd 时向调用方返回明确错误。
• 延迟宿主机 DNS 切换至 CoreDNS 就绪后（#452）：首次安装时，在 CoreDNS 监听之前就改写了宿主机 resolv.conf，导致 DNS 死锁。安装脚本现在等待 CoreDNS 绑定端口，保留一个上游回退 DNS 服务器，并在上游解析路径中过滤预留的 nameserver 地址。

开发环境

• 更新默认 OpenCloudOS 镜像至 9.6（#447）：OpenCloudOS 9.4 qcow2 镜像在 mirrors.tencent.com 上已不再可用，下载失败。将 prepare_image.sh 和 run_vm.sh 中的默认镜像 URL 升级至最新的 9.6-20260514.2 GenericCloud 镜像。

📚 文档

• SA9.4XLARGE32 PVM 基准测试报告（中英文）（#459）：在腾讯云 SA9.4XLARGE32（AMD EPYC 9K65、16 vCPU、32 GiB 内存、200 GiB 增强型 SSD、PVM 内核）上的完整基准测试报告，涵盖冷启动延迟、并发扩展（c=1/10/20）、单机密度（约 743 个空闲沙箱，单个约 27-34 MB）、快照创建与并发及脏页大小的关系、从快照创建、回滚、克隆、暂停/恢复等并发性能。中英文两个版本均已包含。
• BMI5 裸金属基准测试数据（#450）：用来自腾讯云 BMI5 裸金属节点的真实实测数据替换性能基准测试文章（中英文）中的所有模拟/占位数据。重构压测脚本为单层 CLI 风格，以支持可组合的多层扫描，并添加 TAP 池扩容说明。
• v0.3.0 发布博客（#441）：新增中英文 v0.3.0 发布博文（快照/克隆/回滚、AgentHub、Web UI、Go SDK），并将精选文章排序重新调整，v0.3.0 权重最高。
• trpc-agent-go 用例（#446）：新增用例文档，介绍 trpc-agent-go 如何基于 Cube Sandbox 作为安全代码执行后端，中英文侧边栏均已添加条目。
• 性能基准文章修复（#440）：修复 vmm.log 路径，在 2.2 节添加模板创建命令，将通用约定从 3.1 节移至 4.0 节，中英文两个版本均已更新。
• 磁盘空间要求更新（#425）：将 /data/cubelet 的最低磁盘空间要求从 300 GB 降低至 50 GB，构建多个模板时建议 200 GB 及以上。
• 移除重复的快速开始链接（#430）：清理 README 中重复的快速开始链接入口，仅保留顶部导航栏。

👏 贡献者

7 位贡献者共同完成了此版本：

@LoGin (jinlong), @ls (ls-ggg), @cherrycao, @chengjoey, @Hengqi Chen, @joeytao, @tinklone (maxlong)

title: v0.3.0 — 2026.06.02

2026.06.02 Release v0.3.0

CubeSandbox 0.3.0 introduces CubeCoW, a Copy-on-Write snapshot engine that brings hundred-millisecond snapshot, clone, and rollback capabilities to AI Agent sandboxes. This release also adds the AgentHub digital assistant console (Preview), a Web UI for visual management, and the Go SDK. With 82 commits from 22 contributors, v0.3.0 is the largest release since open-sourcing.

🎯 Major Features

CubeCoW: Snapshot, Clone & Rollback

• CubeCoW Copy-on-Write snapshot engine (#360): A full-lifecycle CoW snapshot engine using reflink-based volume snapshots, providing efficient block-level snapshot operations for sandbox volume management. Create lightweight, space-efficient checkpoints at any moment.
• Soft-dirty incremental memory snapshots (#389): Per-cycle incremental memory snapshots via soft-dirty page tracking, dramatically reducing snapshot time and storage for repeated snapshot cycles. Only dirty pages are captured after the first full snapshot.
• Snapshot restore & vsock handling (#388): VSOCK connections are properly reset on snapshot restore, ensuring clean connection state after rollback.
• Snapshot I/O optimization (#400): Removed unnecessary sync_all() calls from all snapshot write paths, significantly reducing snapshot write latency without compromising data integrity.
• Demo suite & developer guide (#374): A complete demo suite and step-by-step guide covering snapshot, rollback, and clone workflows, with runnable examples.
• Host-mount pause snapshot restore fix: Fixed snapshot restore for sandboxes with paused host-mount filesystems.

AgentHub Digital Assistant Console (Preview)

• AgentHub API & UI (#420): A complete digital assistant console built on top of CubeSandbox. Includes:
  • AgentHub persistence layer and assistant lifecycle management
  • OpenClaw setup integration for AI agent orchestration
  • Snapshot timeline with visual checkpoint creation and rollback
  • Clone sandboxes into parallel exploration environments
  • Template actions for reusable assistant configurations
  • Model settings and WeCom notification configuration
  • Full i18n support (English & Chinese)

Web UI

• Management dashboard (#299): A browser-accessible Web UI for managing sandboxes, templates, and cluster nodes. Includes a template store for browsing and deploying pre-built sandbox images. No CLI needed for common operations.

🛠️ SDK

Python SDK (v0.2.1)

• Template creation API (#365): Create sandbox templates programmatically from Python, enabling end-to-end automation without shell commands.
• envd process API migration (#1676a0fc): Commands now run through the envd process API, improving reliability and consistency.
• Process exit edge-case handling (#a210dfc2): Fixed edge cases in envd process lifecycle management, preventing hung commands.
• Stderr coverage & file fallback hardening (#9e2c64ab): Improved error output capture and hardened file operation fallback paths.
• envd defaults & network policy alignment (#418): Aligned envd service defaults and network policy configuration with the server-side defaults.

Go SDK (New)

• Initial Go SDK release (#5de861ac, #3b5caf29): A complete Go SDK providing typed API bindings for sandbox lifecycle management, enabling Go applications to create, manage, and destroy sandboxes natively.

✨ Enhancements

Deployment

• Systemd-based one-click deployment (#331): The one-click installer now manages all services through systemd, providing proper service supervision, automatic restart on failure, and systemctl integration.
• Docker Compose container lifecycle (#386): Container lifecycle management migrated to Docker Compose, simplifying multi-container orchestration and improving restart behavior.
• Early pre-download checks (#288): The online installer now validates network connectivity and disk space before downloading, preventing mid-installation failures.
• Health check & diagnostic scripts (#305): New check.sh and collect-logs.sh scripts for one-click deployment health verification and log collection.
• Cgroup v2 CPU controller preflight check (#367): The installer detects missing cgroup v2 CPU controller support and provides actionable guidance before proceeding.
• Network-agent readiness wait (#304): The installer now waits for network-agent to be fully ready before proceeding, eliminating race conditions during initial setup.
• Docker bind-mount directory prevention (#417): Prevent Docker from auto-creating directories at bind-mount file paths, ensuring correct mount behavior.
• Guest image optimization (#347): Ext4 images are now shrunk after creation and the Dockerfile is optimized, reducing image size and pull time.

Infrastructure

• Centralized schema migration (#385): CubeMaster now uses goose for database schema migrations, enabling versioned, automated schema management across upgrades.
• Node resource reporting (#382): Cubelet now reports allocated node resources (CPU, memory, disk) to CubeMaster, enabling cluster-wide resource awareness.
• Path-based sandbox routing (#334): CubeProxy supports path-based sandbox routing and shared backend resolution, improving routing flexibility.
• Scheduler metrics (#326, #301): Cubelet exposes scheduler metrics as Prometheus gauges on /v1/metrics, enabling real-time monitoring of sandbox scheduling and resource utilization.

🐛 Bug Fixes

• Pause/resume state convergence (#404): Fixed pause/resume state drift on ttrpc errors and shim events, ensuring consistent sandbox lifecycle state.
• Shim readiness handshake (#398): Fixed the shim readiness handshake by not redirecting stdout (fd 1), preventing silent initialization failures.
• Network resource leak (#314): Resolved a network resource leak during sandbox creation that could exhaust available network interfaces over time.
• Host-mount cleanup (#333): Host-mount directories are now properly cleaned up after sandbox destruction, preventing disk space accumulation.
• Cloud Hypervisor disk API (#337): Fixed incorrect Cloud Hypervisor disk API endpoint usage that could cause disk operation failures.
• Template commit idempotency (#336): Enforced requestID uniqueness and added idempotent commit reuse, eliminating duplicate template commits from retried requests.
• Config parsing (#396): Fixed NodeStatusUpdateFrequency to use tomlext.Duration for correct TOML duration parsing.
• Input validation (#344): Added input validation at command-execution call sites to catch invalid parameters early.
• Concurrent DNS handling (#363): Tolerate concurrent DNS dummy link creation, preventing race-condition failures during parallel sandbox creation.
• PMEM boundary alignment (#351): Shrunk guest images are now aligned to pmem boundary, fixing boot failures on certain configurations.
• Quickcheck readiness (#349): Wait for quickcheck containers to be ready before proceeding, eliminating false-positive health check failures.
• Service binding security (#269): MySQL/Redis now bind to localhost by default, and CubeProxy uses host networking for improved network security.
• Service startup ordering (#346): cube-proxy.service is now ordered after cube-sandbox-dns.service, preventing DNS resolution failures at startup.
• Image digest handling (#303): Stripped canonical prefix from image digests in the template center, fixing image reference mismatches.
• Paused state reporting (#270): Fixed paused sandbox state in list responses, ensuring accurate sandbox status display.
• Build version injection (#327): Build version info is now properly injected via ldflags for cubelet and cubemaster binaries.

🔒 Security

• Prometheus upgrade (#328): Upgraded prometheus client to 0.14.0, dropping the vulnerable protobuf 2.28.0 dependency.
• reqwest upgrade (#323): Upgraded reqwest to 0.12 in CubeAPI, fixing the rustls-webpki CVE.
• libseccomp upgrade (#321): Upgraded libseccomp to 0.3.0, fixing GHSA-2r23-gqr7-wr4h.
• go-jose bump (#320): Bumped go-jose/v4 to the latest secure version.
• gRPC dependency bump (#316): Updated gRPC dependency in CubeMaster.

📚 Documentation

• Changelog restructure (#412, #416): Changelogs are now organized into per-version files with an index page for easier navigation. Fixed broken changelog links in README.
• Performance benchmark blog (#419): Published a detailed performance benchmark post with reproducible bench scripts, covering startup latency and resource overhead metrics.
• Blog system (#306, #340): Added a blog system with local search and maintainer guide. Published community posts including "From Serverless to Agent" and PVM deployment walkthroughs.
• Brand identity (#329): Added official logo and favicon to the documentation site.
• Troubleshooting guides (#313): New bilingual troubleshooting subpages for deployment and template creation issues.
• Docs cross-reference fixes (#372): Added missing .md extensions to cross-file documentation references.
• Example & tutorial fixes (#406, #407, #377): Fixed probe path in create-from-image tutorial, standardized placeholder API keys with e2b_ prefix, and corrected clone state documentation.

⚙️ Engineering Improvements

• Kernel source migration (#395): Migrated kernel source from Gitee to CNB with enhanced extraction logic.
• CI/CD hardening (#330, #335, #338, #393): Added docs build check workflow, fixed CR workflow, enabled auto-review for external PRs, added default shell configuration and artifact retrieval optimization.
• Deprecated API removal (#339): Removed deprecated rand.Seed calls across the codebase.
• Rust dependency refresh (#9f8df42f): Bumped crossbeam-channel from 0.5.13 to 0.5.15 in the hypervisor crate.

👏 Contributors

22 contributors made this release possible:

@fslongjin, @ls, @tinklone, @kami-lu, @chenggui53, @cherrycao, @Hengqi Chen, @NovaHe, @maxlong, @Yi Wang, @liciazhu, @Nemo, @Feng King, @Songqian Li, @Joohwan., @Stary, @xiongxz, @yangjie, @YangYuS8, @wangchenglong-hj, @John Eismeier, @dependabot[bot]

title: v0.3.0 — 2026.06.02

2026.06.02 发布 v0.3.0

CubeSandbox 0.3.0 引入了 CubeCoW Copy-on-Write 快照引擎，为 AI Agent 沙箱带来百毫秒级快照、克隆与回滚能力。本次发布还新增了 AgentHub 数字助理控制台（Preview 预览版）、Web UI 可视化管理界面，以及 Go SDK。82 个提交，22 位贡献者，这是开源以来规模最大的版本。

🎯 核心特性

CubeCoW：快照、克隆与回滚

• CubeCoW Copy-on-Write 快照引擎（#360）：基于 reflink 的卷快照实现全生命周期 CoW 快照管理，提供高效的块级快照操作。可在任意时刻创建轻量、节省空间的检查点。
• Soft-dirty 增量内存快照（#389）：基于 soft-dirty 页面追踪实现逐周期增量内存快照，仅捕获首次全量快照后的脏页，大幅降低重复快照周期的时间和存储开销。
• 快照恢复与 vsock 处理（#388）：快照恢复时正确重置 VSOCK 连接，确保回滚后连接状态干净。
• 快照 I/O 优化（#400）：从所有快照写路径中移除不必要的 sync_all() 调用，在不影响数据完整性的前提下显著降低快照写入延迟。
• 示例套件与开发者指南（#374）：完整的快照、回滚、克隆工作流示例与分步指南，包含可运行的代码。
• Host-mount 暂停快照恢复修复：修复了带有暂停 host-mount 文件系统的沙箱快照恢复问题。

AgentHub 数字助理控制台（Preview 预览版）

• AgentHub API 与 UI（#420）：基于 CubeSandbox 构建的完整数字助理控制台，包括：
  • AgentHub 持久化层与助手生命周期管理
  • OpenClaw 集成，支持 AI Agent 编排
  • 快照时间线，支持可视化检查点创建与回滚
  • 从任意快照克隆沙箱，创建并行探索环境
  • 模板操作，复用助手配置
  • 模型设置与企业微信通知配置
  • 完整的中英文国际化支持

Web UI

• 可视化管理界面（#299）：浏览器直接访问的 Web 管理界面，支持沙箱、模板、集群节点的可视化管理。内置模板商店，可浏览和部署预构建的沙箱镜像。日常操作无需命令行。

🛠️ SDK

Python SDK（v0.2.1）

• 模板创建 API（#365）：支持从 Python 代码程序化创建沙箱模板，实现端到端自动化，无需 shell 命令。
• envd 进程 API 迁移（#1676a0fc）：命令执行改为通过 envd 进程 API，提高可靠性与一致性。
• 进程退出边界处理（#a210dfc2）：修复 envd 进程生命周期管理中的边界情况，防止命令挂起。
• Stderr 覆盖与文件回退加固（#9e2c64ab）：改进错误输出捕获，加固文件操作回退路径。
• envd 默认值与网络策略对齐（#418）：将 envd 服务默认值和网络策略配置与服务端默认值对齐。

Go SDK（全新）

• Go SDK 首发（#5de861ac, #3b5caf29）：完整的 Go SDK，提供类型安全的 API 绑定，支持沙箱生命周期管理，让 Go 应用原生创建、管理和销毁沙箱。

✨ 功能增强

部署

• 一键部署迁移至 systemd（#331）：一键安装脚本现在通过 systemd 管理所有服务，提供正确的服务监控、故障自动重启和 systemctl 集成。
• Docker Compose 容器生命周期管理（#386）：容器生命周期管理迁移至 Docker Compose，简化多容器编排，改善重启行为。
• 安装前预下载检测（#288）：在线安装脚本在下载前验证网络连通性和磁盘空间，避免安装中途失败。
• 健康检查与诊断脚本（#305）：新增 check.sh 和 collect-logs.sh，用于一键部署的健康验证与日志收集。
• Cgroup v2 CPU 控制器预检（#367）：安装脚本检测 cgroup v2 CPU 控制器支持情况，缺失时在安装前给出明确指引。
• 网络代理就绪等待（#304）：安装脚本等待 network-agent 完全就绪后再继续，消除初始化期间的竞态条件。
• Docker 挂载目录防创建（#417）：防止 Docker 在 bind-mount 文件路径自动创建目录，确保正确的挂载行为。
• Guest 镜像优化（#347）：创建后自动压缩 ext4 镜像并优化 Dockerfile，减小镜像体积和拉取时间。

基础设施

• 集中化数据库迁移（#385）：CubeMaster 使用 goose 管理数据库 schema 迁移，支持版本化、自动化的 schema 升级。
• 节点资源上报（#382）：Cubelet 向 CubeMaster 上报已分配的节点资源（CPU、内存、磁盘），支持集群级资源感知。
• 基于路径的沙箱路由（#334）：CubeProxy 支持基于路径的沙箱路由和共享后端解析，提升路由灵活性。
• 调度器指标（#326, #301）：Cubelet 通过 /v1/metrics 暴露调度器 Prometheus 指标，支持沙箱调度与资源利用的实时监控。

🐛 Bug 修复

• 暂停/恢复状态一致性（#404）：修复 ttrpc 错误和 shim 事件导致的暂停/恢复状态漂移，确保沙箱生命周期状态一致。
• Shim 就绪握手（#398）：修复 shim 就绪握手因 stdout（fd 1）重定向而失效的问题，避免静默初始化失败。
• 网络资源泄漏（#314）：修复沙箱创建时的网络资源泄漏，防止长时间运行后可用网络接口耗尽。
• Host-mount 目录清理（#333）：沙箱销毁后正确清理 host-mount 目录，避免磁盘空间累积。
• Cloud Hypervisor 磁盘 API（#337）：修复 Cloud Hypervisor 磁盘 API 端点使用错误，避免磁盘操作失败。
• 模板提交幂等性（#336）：强制 requestID 唯一性并支持幂等提交复用，消除重试请求导致的重复模板提交。
• 配置解析（#396）：修复 NodeStatusUpdateFrequency 使用 tomlext.Duration 以确保 TOML 时长正确解析。
• 输入校验（#344）：在命令执行调用点增加输入校验，提前捕获无效参数。
• 并发 DNS 处理（#363）：容忍并发 DNS dummy 接口创建，消除并行沙箱创建期间的竞态故障。
• PMEM 边界对齐（#351）：压缩后的 guest 镜像与 pmem 边界对齐，修复特定配置下的启动失败。
• 快速检查就绪（#349）：等待 quickcheck 容器就绪后再继续，消除误报的健康检查失败。
• 服务绑定安全（#269）：MySQL/Redis 默认绑定 localhost，CubeProxy 改用 host 网络模式，提升网络安全。
• 服务启动顺序（#346）：cube-proxy.service 排在 cube-sandbox-dns.service 之后启动，避免 DNS 解析失败。
• 镜像摘要处理（#303）：在模板中心中剥离镜像摘要的规范前缀，修复镜像引用不匹配问题。
• 暂停状态报告（#270）：修复沙箱列表响应中的暂停状态显示，确保沙箱状态准确。
• 版本信息注入（#327）：通过 ldflags 正确注入 cubelet 和 cubemaster 的构建版本信息。

🔒 安全

• Prometheus 升级（#328）：升级 prometheus 客户端至 0.14.0，移除有漏洞的 protobuf 2.28.0 依赖。
• reqwest 升级（#323）：CubeAPI 升级 reqwest 至 0.12，修复 rustls-webpki 相关 CVE。
• libseccomp 升级（#321）：升级 libseccomp 至 0.3.0，修复 GHSA-2r23-gqr7-wr4h。
• go-jose 版本提升（#320）：提升 go-jose/v4 至最新安全版本。
• gRPC 依赖更新（#316）：更新 CubeMaster 中的 gRPC 依赖。

📚 文档

• 更新日志重构（#412, #416）：更新日志按版本拆分文件并建立索引页，导航更清晰。修复 README 中失效的 changelog 链接。
• 性能基准博客（#419）：发布详细的性能基准测试文章，附可复现的压测脚本，涵盖启动延迟和资源开销指标。
• 博客系统（#306, #340）：新增博客系统，支持本地搜索和维护者指南。发布「从 Serverless 到 Agent」、PVM 部署指南等社区文章。
• 品牌标识（#329）：文档站点新增官方 Logo 和 favicon。
• 故障排查指南（#313）：新增中英文双语的部署和模板创建故障排查子页面。
• 文档交叉引用修复（#372）：修复文档交叉引用中缺失的 .md 扩展名。
• 示例与教程修复（#406, #407, #377）：修复 create-from-image 教程中的探针路径，将占位 API key 统一为 e2b_ 前缀，更正克隆状态文档说明。

⚙️ 工程优化

• 内核源码迁移（#395）：将内核源码从 Gitee 迁移至 CNB，并增强解压逻辑。
• CI/CD 加固（#330, #335, #338, #393）：新增文档构建检查工作流，修复 CR 工作流，启用外部 PR 自动审查，添加默认 shell 配置并优化制品获取。
• 废弃 API 移除（#339）：移除代码库中的废弃 rand.Seed 调用。
• Rust 依赖刷新（#9f8df42f）：在 hypervisor crate 中将 crossbeam-channel 从 0.5.13 升级至 0.5.15。

👏 贡献者

22 位贡献者共同完成了此版本：

@fslongjin, @ls, @tinklone, @kami-lu, @chenggui53, @cherrycao, @Hengqi Chen, @NovaHe, @maxlong, @Yi Wang, @liciazhu, @Nemo, @Feng King, @Songqian Li, @Joohwan., @Stary, @xiongxz, @yangjie, @YangYuS8, @wangchenglong-hj, @John Eismeier, @dependabot[bot]

title: v0.2.2 — 2026.05.18

2026.05.18 Release v0.2.2

🛡️ Security Fixes

• hypervisor: vmm-sys-util bumped to 0.12.1 (CVE-2023-50711, GHSA-875g-mfp6-g7f9): FamStructWrapper::deserialize failed to verify header length against the flexible-array length, allowing out-of-bounds memory access from safe Rust code. Now pinned to the workspace version shared by all other hypervisor crates.
• agent / hypervisor: bytes and env_logger security bumps as part of the same dependency-refresh pass.
• Reverted time crate bump (CVE-2026-25727): CubeSandbox only uses Rfc3339 for outbound timestamp formatting and never parses untrusted Rfc2822 input — the affected attack vector is not reachable. The upgrade was rolled back pending an MSRV bump and will be tracked separately.

🛠️ Critical Fixes

• Fixed duplicate template-image job creation (CubeMaster): A request_id column with a unique index on (request_id, operation) makes job submissions idempotent, preventing duplicate build jobs from concurrent or retried API calls.
• Fixed cubecli exec nil-deref panic on stdin EOF: StdinCloser.Read triggered a nil-pointer dereference at stdin EOF, silently aborting the exec lifecycle. Fixed using errors.Is(err, io.EOF) for proper error-wrapping compatibility; shim logs now emit the expected paired exec lifecycle entries.
• Fixed ext4 artifact runtime file materialization for PVM templates: RefreshArtifactRuntimeFiles, validateArtifactRuntimeFilesPresent, and ensureArtifactRuntimeFiles are simplified to handle only kernel files; copyKernelFileAtomically is renamed to CopyFileAtomically for reuse outside the package.

✨ Enhancements

• E2B-compatible default exposed port: Default sandbox exposed port changed to 49983 to match the E2B sandbox protocol. CubeMaster is now the single source of truth — hardcoded defaults removed from Cubelet and network-agent.
• cubelet: configurable cmdTimeout via storage plugin TOML config: A new optional cmd_timeout field replaces the hardcoded 3 s default, letting operators raise the limit for multi-GiB ext4 operations without recompiling. Default behavior is unchanged when the field is absent.
• cubelet: richer diagnostics on newExt4RawByReflinkCopy failures: Error messages now include elapsed time, file sizes, and free space — e.g. [step=N/4 cmd="…" elapsed=…ms target=size=… base=size=… free=…B].
• Deploy: sync CubeMaster custom ports from .env: cubemaster.yaml now uses __CUBE_SANDBOX_MYSQL_PORT__ / __CUBE_SANDBOX_REDIS_PORT__ placeholders substituted by install.sh, enabling non-default MySQL/Redis ports without manual YAML edits.

⚙️ Engineering Improvements

• cubecli: removed dead listmd command: The unreachable listmd subcommand and its 128-line implementation are deleted.

🤖 CI / DevOps

• Claude-powered code review and issue triage automation: Five AI reviewer agents (code quality, performance, security, test coverage, documentation) added under .agents/agents/. Automated workflows handle PR review, duplicate issue detection, and issue label triage. Helper scripts gh.sh and edit-issue-labels.sh added under scripts/.

📚 Documentation

• Chinese translation of CONTRIBUTING.md: CONTRIBUTING_zh.md added as a full Chinese translation of the contribution guide.
• Community doc PR requirements relaxed: Both CONTRIBUTING.md and CONTRIBUTING_zh.md now allow single-language submissions; bilingual docs are optional.
• Network port allocation ranges documented: docs/architecture/network.md (EN & ZH) now documents the three port-range buckets: 10000–19999 (network-agent), 20000–29999 (CubeProxy), 30000–65535 (CubeVS SNAT).
• Community docs sections added: New bilingual troubleshooting, use-cases, and integrations sections added to VitePress; a CI workflow enforces bilingual parity.
• Domain update: CNAME switched from docs.cubesandbox.ai to cubesandbox.com.
• Fixed browser-sandbox example: Added missing load_dotenv() call and python-dotenv dependency.
• WeChat group QR code refreshed.

title: v0.2.2 — 2026.05.18

2026.05.18 发布 v0.2.2

🛡️ 安全修复

• hypervisor: vmm-sys-util 升级至 0.12.1（CVE-2023-50711, GHSA-875g-mfp6-g7f9）：FamStructWrapper::deserialize 未验证 header 长度与柔性数组长度是否匹配，可导致 safe Rust 代码触发越界内存访问。现已固定为 hypervisor workspace 所有 crate 共享的版本。
• agent / hypervisor: bytes 和 env_logger 安全依赖升级，作为同批依赖刷新的一部分。
• 回滚 time crate 升级（CVE-2026-25727）：CubeSandbox 仅使用 Rfc3339 进行时间戳格式化输出，从不对不可信输入执行 Rfc2822 解析，攻击面不可达。该升级已回滚，待 MSRV 就绪后单独跟进处理。

🛠️ 关键修复

• 修复 CubeMaster 模板镜像任务重复创建问题：在 template_image_job 表新增 request_id 字段并添加 (request_id, operation) 唯一索引，使任务提交具备幂等性，彻底消除并发或重试 API 调用引发的重复构建任务。
• 修复 cubecli exec 在 stdin EOF 时的 nil 指针 panic：StdinCloser.Read 在 stdin 到达 EOF 时触发 nil 指针解引用，导致 exec 生命周期被静默中断。修复后改用 errors.Is(err, io.EOF) 进行正确的错误包装比对，shim 日志现可正常输出成对的 exec 生命周期记录。
• 修复 PVM 模板的 ext4 artifact 运行时文件物化问题：简化 RefreshArtifactRuntimeFiles、validateArtifactRuntimeFilesPresent 和 ensureArtifactRuntimeFiles，使其仅处理内核文件；将 copyKernelFileAtomically 重命名为 CopyFileAtomically，支持在包外复用。

✨ 功能增强

• E2B 兼容默认暴露端口：默认沙箱暴露端口由 8080/32000 改为 49983，与 E2B 沙箱协议对齐。CubeMaster 成为默认端口的唯一权威来源，Cubelet 和 network-agent 中的硬编码默认值已移除。
• Cubelet 存储插件支持配置 cmdTimeout：在存储插件 TOML 配置中新增可选 cmd_timeout 字段，替代原有硬编码的 3 秒超时，允许运维人员在高并发负载下提高大文件 ext4 操作的超时限制，无需重新编译。字段缺省时行为不变。
• Cubelet newExt4RawByReflinkCopy 错误诊断增强：错误信息现在包含操作耗时、目标/基础文件大小及可用磁盘空间，格式为 [step=N/4 cmd="…" elapsed=…ms target=size=… base=size=… free=…B]。
• 部署脚本支持从 .env 同步 CubeMaster 自定义端口：cubemaster.yaml 引入 __CUBE_SANDBOX_MYSQL_PORT__ / __CUBE_SANDBOX_REDIS_PORT__ 占位符，由 install.sh 从 .env 文件自动替换，无需手动修改 YAML。

⚙️ 工程改进

• cubecli: 移除废弃的 listmd 命令：删除无法访问的 listmd 子命令及其 128 行实现代码。

🤖 CI / DevOps

• Claude 驱动的 AI 代码审查与 issue 分类自动化：在 .agents/agents/ 下引入五个 AI 审查 Agent（代码质量、性能、安全、测试覆盖率、文档准确性）。自动化工作流负责 PR 代码审查、重复 issue 检测和 issue 标签分类。新增 scripts/gh.sh 和 scripts/edit-issue-labels.sh 辅助脚本。

📚 文档更新

• 新增 CONTRIBUTING_zh.md：CONTRIBUTING.md 的完整中文翻译版本。
• 社区文档 PR 要求放宽：CONTRIBUTING.md 和 CONTRIBUTING_zh.md 均改为支持单语种提交，双语文档为可选项。
• 计算节点端口分配范围文档化：docs/architecture/network.md（中英文）新增三段端口范围说明：10000–19999（network-agent）、20000–29999（CubeProxy 沙箱访问）、30000–65535（CubeVS SNAT）。
• 新增社区文档章节：VitePress 新增双语故障排查、用例和集成三个章节，并配置 CI 工作流强制执行双语一致性检查。
• 域名更新：CNAME 从 docs.cubesandbox.ai 切换至 cubesandbox.com。
• 修复 browser-sandbox 示例：新增缺失的 load_dotenv() 调用和 python-dotenv 依赖，确保 .env 变量在脚本运行前正确加载。
• 微信群二维码更新。

title: v0.2.1 — 2026.05.14

2026.05.14 Release v0.2.1

🌟 Major New Features

• Official Python SDK (cubesandbox v0.1.0): A first-party Python SDK shipped under sdk/python/, fully aligned with the CubeAPI OpenAPI spec. Covers full sandbox lifecycle (create/connect/pause/kill/list/health), code execution with streaming stdout/stderr, filesystem access, direct-connect transport, and network policy. Includes 12 worked examples, a concurrency benchmark, and 76/76 tests passing.

🚀 Performance

• Skip SHA256 on every Cubelet startup: Split SyncKernelFile into EnsureKernelFilePresent (copy-if-missing, fast path) and RefreshKernelFile (force-refresh with verification), removing the expensive per-boot SHA256 comparison. Normal startup latency drops significantly on hosts with many templates.
• Skip redundant docker pull in CubeMaster: Source image pulls are now bypassed when the image already exists locally, removing unnecessary registry round-trips during template builds.

🛡️ Security Fixes

• shim: protobuf bumped 3.4.0 → 3.7.2 (RUSTSEC, stack overflow on crafted unknown fields). Co-upgrades containerd-shim-protos, containerd-shim, and nix.
• cubeapi / agent / shim / hypervisor: rand 0.8.5 → 0.8.6 (GHSA-cq8v-f236-94qc, soundness issue with ThreadRng reseeding).
• CubeVS: golang.org/x/net → v0.38.0, golang.org/x/sys → v0.38.0.
• network-agent: google.golang.org/grpc → 1.79.3.
• CubeAPI/examples: pygments → 2.20.0.

🛠️ Critical Fixes

• Fixed Seccomp swallowing all syscalls: Seccomp initialization now sets DefaultAction = ActAllow; an empty syscall list short-circuits as a no-op instead of silently blocking everything.
• Fixed shim stderr being routed through stdout: The Exec stream-forwarding path was incorrectly calling the stdout read method for stderr; stderr is now properly captured and forwarded.
• Fixed CubeProxy workers sharing the same PRNG seed: OpenResty workers now seed the RNG per-worker in init_worker with (ngx.now() * 1000 + ngx.worker.id()), preventing synchronized cache-expiration stampedes.
• Fixed dev-env sync overwriting cube-shim symlinks: cube-runtime and containerd-shim-cube-rs are now written to ${TOOLBOX_ROOT}/cube-shim/bin, preserving the toolbox symlink layout.
• Fixed Dockerfile breakage on HTTPS-only mirrors: ca-certificates is now installed before apt sources are swapped to internal mirrors.

✨ Enhancements

• cubemastercli tpl watch — phase-oriented output: Replaced the old multi-line full-status dump with concise [N/7] PHASE progress lines plus a terminal summary; much friendlier in CI logs.
• IPAM — comprehensive optimization and reliability overhaul (Cubelet + network-agent): Validation rewritten on net/netip; IP ↔ index conversions via encoding/binary.BigEndian; bounds checks, safety limits, and nil guards added; reserved-address semantics documented; comprehensive table-driven and concurrency tests.

⚙️ Engineering Improvements

• Examples reorganized into standalone top-level directories: Moved from CubeAPI/examples/ to top-level examples/, with dedicated host-mount and network-policy directories (each with its own README); comments translated to English.
• cube-bench promoted to examples/cube-bench: Now a standalone Go module with its own Makefile.
• Go toolchain alignment: CubeVS and network-agent upgraded to Go 1.24.8.
• cubecli internationalization: Remaining Chinese usage strings in benchrun.go translated to English.
• Docker build context cleanup: Makefile builder-image now builds from ./docker instead of the repo root.
• Alpine mirror swap: APK repositories switched from dl-cdn.alpinelinux.org to mirrors.tencent.com.

🤖 CI / DevOps

• DCO check workflow: A dedicated PR gate now blocks merges if any non-merge commit is missing a valid Signed-off-by trailer.
• GitHub ARC (Actions Runner Controller) support: Self-hosted ARC runners wired up for kernel/package build workflows.
• No more duplicate PR checks: push triggers on several workflows now scoped to master only; PR validation runs exclusively via pull_request — halving CI cost.
• sync-to-cnb: Uses the CNB_GIT_PASSWORD secret.

📚 Documentation

• Deployment guide reworked: PVM and bare-metal are now presented as the preferred deployment paths.
• PVM rapid-deploy on OpenCloudOS 9: New step-by-step section added to pvm-deploy.md.
• "About us" page: English and Chinese versions added, with corresponding VitePress navigation.
• X (Twitter) link added to project READMEs.
• Docs polish: Python import paths and architecture-diagram spacing corrected.
• WeChat / assistant QR codes refreshed in README_zh.md.

title: v0.2.1 — 2026.05.14

2026.05.14 发布 v0.2.1

🌟 重大新功能

• 官方 Python SDK (cubesandbox v0.1.0)：随仓库发布的第一方 Python SDK，位于 sdk/python/，与 CubeAPI OpenAPI 规范完全对齐。覆盖沙箱全生命周期管理（创建/连接/暂停/销毁/列表/健康检查）、代码执行（流式 stdout/stderr）、文件系统访问、直连传输及网络策略配置。附带 12 个完整示例、并发性能基准测试，76/76 测试全部通过。

🚀 性能优化

• 跳过 Cubelet 每次启动时的 SHA256 校验：将 SyncKernelFile 拆分为 EnsureKernelFilePresent（按需拷贝，快速路径）和 RefreshKernelFile（强制刷新并校验），消除每次启动的高开销 SHA256 比对。在模板数量较多的主机上，正常启动延迟显著降低。
• 跳过 CubeMaster 冗余的 docker pull：当源镜像已存在于本地时，跳过镜像拉取，消除模板构建时不必要的镜像仓库往返请求。

🛡️ 安全修复

• shim: protobuf 3.4.0 → 3.7.2（RUSTSEC，恶意构造的未知字段可导致栈溢出）。同步升级 containerd-shim-protos、containerd-shim 和 nix。
• cubeapi / agent / shim / hypervisor: rand 0.8.5 → 0.8.6（GHSA-cq8v-f236-94qc，修复 ThreadRng 重新播种时的健全性问题）。
• CubeVS: golang.org/x/net → v0.38.0, golang.org/x/sys → v0.38.0。
• network-agent: google.golang.org/grpc → 1.79.3。
• CubeAPI/examples: pygments → 2.20.0。

🛠️ 关键修复

• 修复 Seccomp 静默拦截所有系统调用：Seccomp 初始化现在设置 DefaultAction = ActAllow，空系统调用列表直接短路为空操作，而非静默阻止所有调用。
• 修复 shim stderr 被错误路由到 stdout：Exec 流转发路径中 stderr 错误调用了 stdout 的读取方法；现在 stderr 可被正确捕获并转发。
• 修复 CubeProxy 多 Worker 共享相同 PRNG 种子：OpenResty Worker 现在在 init_worker 中以 (ngx.now() * 1000 + ngx.worker.id()) 为每个 Worker 独立播种，避免缓存 TTL 抖动失效和同步缓存过期风暴。
• 修复开发环境同步覆盖 cube-shim 软链接：cube-runtime 和 containerd-shim-cube-rs 现在写入 ${TOOLBOX_ROOT}/cube-shim/bin，保留工具箱软链接布局。
• 修复 HTTPS-only 镜像源导致 Dockerfile 构建失败：在切换 APT 源至内部镜像之前先安装 ca-certificates，避免 TLS 证书缺失导致引导失败。

✨ 功能增强

• cubemastercli tpl watch — 阶段性进度输出：将原有的多行全量状态刷新替换为简洁的 [N/7] PHASE 进度行加终端摘要；在 CI 日志中更加友好。
• IPAM — 全面优化与可靠性改进（Cubelet + network-agent）：基于 net/netip 重写校验逻辑；通过 encoding/binary.BigEndian 简化 IP 与索引互转；为 Allocate / Release / Assign 添加边界检查和安全性限制；所有 IPAM 方法增加 nil 防护；明确文档化保留地址语义；新增全面的表驱动测试和并发测试。

⚙️ 工程改进

• 示例重组为独立顶级目录：从 CubeAPI/examples/ 迁移至顶层 examples/，新增独立的 host-mount 和 network-policy 目录（各自附带 README）；注释翻译为英文。
• cube-bench 提升为 examples/cube-bench：现为独立 Go 模块，带自己的 Makefile。
• Go 工具链对齐：CubeVS 和 network-agent 升级至 Go 1.24.8，与 Cubelet / CubeMaster 保持一致。
• cubecli 国际化：benchrun.go 中残余的中文使用说明翻译为英文。
• Docker 构建上下文清理：Makefile 构建器镜像现在从 ./docker 构建，而非仓库根目录。
• Alpine 镜像源切换：APK 仓库从 dl-cdn.alpinelinux.org 切换至 mirrors.tencent.com。

🤖 CI / DevOps

• DCO 检查工作流：新增专用 PR 门禁，当任何非合并提交缺少有效 Signed-off-by 签名时阻断合入。
• GitHub ARC (Actions Runner Controller) 支持：自托管 ARC 运行器已接入内核/包构建工作流。
• 消除重复 PR 检查：多个工作流的 push 触发器现在仅限 master 分支；PR 验证仅通过 pull_request 事件运行 — CI 成本减半。
• sync-to-cnb：改用 CNB_GIT_PASSWORD 密钥。

📚 文档更新

• 部署指南重写：PVM 和裸金属现为首选部署路径。
• OpenCloudOS 9 上 PVM 快速部署：pvm-deploy.md 新增分步操作章节。
• "关于我们"页面：新增中英文版本，并配置 VitePress 导航。
• 项目 README 新增 X (Twitter) 链接。
• 文档细节修正：修正 Python 导入路径和架构图间距。
• README_zh.md 更新微信/助手二维码。

title: v0.2.0 — 2026.05.07

2026.05.07 Release v0.2.0

🌟 Major New Features

• Web Management Console (Dashboard): A brand-new visual management UI with cluster overview, node and sandbox status, template management, and API key management; new CubeAPI web endpoints added to back the Dashboard.

• PVM Deployment Mode: Powered by PVM (Pagetable-based Virtual Machine), ordinary cloud servers can now run CubeSandbox without bare-metal or nested virtualization. Tencent Cloud has deployed and validated PVM instances at scale in production, with improvements open-sourced in the OpenCloudOS kernel.

✨ Enhancements

• Custom DNS for template creation: cubemastercli template gains a --dns flag, allowing a custom DNS server address to be specified when creating a template image.

🛠️ Critical Fixes

• Fixed disk QoS (blk_qos) having no effect: Cubelet was reading the QoS annotation with the wrong key, silently ignoring IOPS/bandwidth limits; limits now apply as configured.

• Fixed host-mount requests being silently dropped: CubeAPI wrote the annotation with key host-mount while CubeMaster read with hostdir-mount; the mismatch caused all host directory mounts to be ignored. Keys are now aligned and host-mount works correctly.

• Fixed Cubelet mount namespace not receiving host mount events: Cubelet created its mount namespace in private mode, blocking propagation of subsequent host mounts; changed to slave mode so host mount events propagate one-way into the Cubelet namespace without affecting the host.

• Fixed DeadGC permanently freezing paused sandboxes: scanDeadContainer issued a state() call to the shim while the sandbox held its mutex (during pausing/paused), causing a 5 s timeout, Cubelet marking the sandbox UNKNOWN, and CubeMaster giving up on resume. DeadGC now skips sandboxes in pausing/paused states.

🌐 Networking

• Disabled virtio-net TAP offloads (TSO/UFO/CSUM): The hypervisor previously advertised hardware offload features to the guest; CHECKSUM_PARTIAL packets emitted by the guest could cause network errors or even disable tx-checksumming on the host NIC, affecting other tenants. The hypervisor no longer advertises these features; the guest handles checksumming and segmentation itself.

⚙️ Engineering Improvements

• Cubelet CLI logging standardization: Migrated legacy myPrint output in cubecli sub-commands (cubebox, network, storage, volume, etc.) to structured logging.
• Dead code removal: Removed the unused AppId field from CubeMaster affinityutil tests.

📚 Documentation Updates

• New PVM Deployment guide (Chinese & English): full walkthrough covering PVM host kernel installation, GRUB configuration, module loading, and verification.
• Quick Start updated: ordinary cloud servers can now be used via PVM — no bare-metal required.
• Updated code-sandbox-quickstart example README (Chinese & English).

title: v0.2.0 — 2026.05.07

2026.05.07 发布 v0.2.0

🌟 重大新功能

• 新增 Web 管理控制台（Dashboard）：全新可视化管理界面，支持集群概览、节点与沙箱状态查看、模板管理、API 密钥管理等核心功能；同步新增 CubeAPI Web 端点为 Dashboard 提供数据支撑。

• 新增 PVM 部署模式：借助 PVM（Pagetable-based Virtual Machine），普通云服务器无需裸金属，也无需嵌套虚拟化，即可完整运行 CubeSandbox。腾讯云已在生产环境大规模部署并验证，相关改进已开源至 OpenCloudOS 内核。

✨ 功能增强

• CubeMaster 模板创建支持自定义 DNS：cubemastercli template 命令新增 --dns 参数，支持在创建模板镜像时指定 DNS 服务器地址。

🛠️ 关键修复

• 修复磁盘 QoS（blk_qos）配置完全失效问题：Cubelet 读取 QoS annotation 时使用了错误的 key，导致沙箱磁盘 IOPS/带宽限速静默不生效；修复后配置按预期生效。

• 修复 Host Mount 请求被静默丢弃问题：CubeAPI 写入 host-mount annotation 时 key 与 CubeMaster 读取时的 hostdir-mount 不一致，导致所有宿主机目录挂载请求被忽略；修复后两侧 key 对齐，功能恢复正常。

• 修复 Cubelet 挂载命名空间无法接收宿主机 mount 事件：Cubelet 以私有模式创建挂载命名空间，导致宿主机后续挂载无法传播至 Cubelet；修复后改为 slave 模式，宿主机挂载事件单向传播，沙箱 host-mount 功能完整可用。

• 修复 DeadGC 误判 pause 中的沙箱导致其永久冻结：scanDeadContainer 在沙箱处于 pausing/paused 状态时向 shim 发起 state 查询，因 shim 持有互斥锁而超时，Cubelet 将状态标记为 UNKNOWN，沙箱无法恢复；修复后 DeadGC 主动跳过此类沙箱。

🌐 网络改进

• 禁用 virtio-net TAP 网络卸载（TSO/UFO/CSUM）：此前 hypervisor 向 guest 通告了多项网络硬件卸载能力，guest 发出的 CHECKSUM_PARTIAL 包在宿主机 NIC 不支持对应卸载时会导致网络异常，甚至影响同宿主机其他流量；修复后 hypervisor 不再通告这些能力，guest 自行处理 checksum 与分段。

⚙️ 工程改进

• Cubelet CLI 日志标准化：将 cubecli 各子命令中遗留的 myPrint 自定义输出统一迁移为标准结构化日志。
• 废弃代码清理：移除 CubeMaster affinityutil 测试中不再使用的 AppId 字段。

📚 文档更新

• 新增 PVM 部署指南（中英双语）：包含 PVM host kernel 下载安装、GRUB 配置、模块加载及验证的完整流程。
• 优化快速入门：说明普通云服务器可通过 PVM 部署，无需裸金属。
• 更新 code-sandbox-quickstart 示例 README（中英双语）。