v0.5.1

[fslongjin]

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 (feat(terraform): add TencentCloud lifecycle manager deployment #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.

Value	Meaning
Omitted (None / nil)	Cluster default_timeout_insec; if unset or ≤0 → never timeout
NEVER_TIMEOUT (-1)	Never reclaim on idle
0	Immediate timeout (reclaimed on the first idle sweep)
N > 0	Idle TTL = N seconds

• 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 (feat: add Python SDK set_timeout() with NEVER_TIMEOUT (-1) support #743, feat(sdk/go): add SetTimeout() to Go SDK #850). Web UI can pass timeout on sandbox create (fix(webui): allow passing timeout when creating a sandbox #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) (feat(sdk): add official Node.js / TypeScript SDK #792): adds @cubesandbox/sdk aligned with the Python / Go surface; still under validation — use with caution in production.
• Python / Go set_timeout (feat: add Python SDK set_timeout() with NEVER_TIMEOUT (-1) support #743, feat(sdk/go): add SetTimeout() to Go SDK #850): E2B-aligned; CubeAPI / CubeMaster accept -1 (NEVER_TIMEOUT) and reject other negatives.
• Go SDK allowOut guard alignment (fix(sdk/go): align allowOut domain guard with CubeAPI #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 (CubeEgress: Allow 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 (fix(cube-egress): derive 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 (feat(cube-proxy): migrate from local build to 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 (feat: add release Docker image workflow and bump-image version tooling #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 (feat: unify Docker build args and add CubeMaster Dockerfile #813, fix: unify Docker build context and fix ARG scoping #824): unified Docker build args / context and ARG scoping fixes; CubeAPI Dockerfile switched to single-shot build with safety gates (fix(build): switch CubeAPI Dockerfile to single-shot build with safety gates #854).
• One-click dnsmasq fallback (fix(one-click): route host DNS via a script-owned 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 (fix(deploy): anchor 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 (fix(cubeapi): accept snake_case lifecycle fields #772): accepts Python-style lifecycle.on_timeout / lifecycle.auto_resume, avoiding silent fallback to kill / no-resume.
• AgentHub OpenClaw bind=lan (fix(agenthub): force OpenClaw gateway bind to "lan" mode #769): force gateway bind to lan so cube-proxy can reach it via tap IP (auto could resolve to loopback).
• ARM64 runtime hardening (cube on arm64: add more aarch64 arch support #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 (dev-env: use explicit drive/device split for QEMU 10.x compatibility #713): explicit -drive if=none + -device virtio-blk-pci fixes empty-drive errors on QEMU 10.2.2+.

🐛 Bug Fixes

Lifecycle & Sandboxes

• Idempotent resume (cubelet: Make resume idempotent when sandbox already running #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 (fix(cubeapi): return 404 when deleting missing sandbox #759): CubeAPI / CubeMaster map missing-sandbox deletes to NotFound.
• Stable sandbox list order (fix(CubeMaster): stably sort sandbox list to stop reordering on refresh #762): sort by creation time descending with SandboxID tie-break so WebUI / SDK refreshes no longer reshuffle.
• Preserve template network rules & resource defaults (fix(CubeMaster): preserve template network rules and 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 (fix(sdk): route Go SDK envd RPCs to the envd port (49983) #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 (fix(examples): align host-mount example paths with default allowed prefix #768): examples and docs use /data/shared/... to match the default allowlist.

📚 Documentation

• ARM64 support announcement blog (docs(blog): add Cube Sandbox Arm support announcement blog posts #866): bilingual InfoQ-style post on the joint Arm multi-arch effort.
• Pi Agent integration guide (Docs/pi agent integration #701): bilingual docs + runnable example (pause/resume, network policy, credential injection).
• Lifecycle / quota docs (docs: add ARM64 install guide and lifecycle quota docs #739): ARM64 install notes and lifecycle quota documentation.
• Persistent storage guide (security(cubemaster): restrict host-mount paths to configurable allowed prefixes #756): host-mount path restriction, permissions, multi-tenant isolation, multi-node shared storage.
• Roadmap (docs: add roadmap to README and docs site (en + zh) #731): roadmap added to README and docs site.
• v0.5.0 release materials (docs(blog): add v0.5.0 release post (zh + en) #770, docs: add v0.5.0 release news and update feature descriptions #781): release blog and feature copy updates; Quickstart notes Multi-Arch image availability (docs(guide): note Multi-Arch image availability in quickstart #806).
• Dev skills & doc hygiene (docs: add run-dev development skill for Claude Code #788, docs(agents): add i18n sync check and change-driven doc audit rules #789): Claude Code run-dev skill; i18n sync checks and change-driven doc audit rules.

⚙️ Engineering Improvements

• Platform-suffixed versions in matrix checks (Allow platform-suffixed versions in version matrix checks #747).
• PVM guest build trigger tightened (fix(ci): restrict pvm-guest build trigger to version tags only #819): only on version tags.
• Image tag bumps: one-click / Terraform defaults synced through v0.5.1-rc* candidates (chore: bump image tag from v0.5.1-rc1 to v0.5.1-rc3 #826, chore: bump image tag from v0.5.1-rc3 to v0.5.1-rc5 #867).
• Python SDK version bump to 0.5.0 (chore: bump Python SDK version to 0.5.0 #818).
• CubeAPI dead-code cleanup (chore(cubeapi): remove dead code to clear compiler warnings #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.

---

This discussion was created from the release v0.5.1.