v0.3.1

[fslongjin]

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 (feat(one-click): support cubevs CIDR via env var with conflict detection #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 (feat(one-click): support cubevs CIDR via env var with conflict detection #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 (feat(one-click): add glibc version preflight check to fail fast on unsupported distros #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 (feat(one-click): add PVM consistency pre-check to install scripts #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 (feat(agenthub): refine digital assistant preview support #426): Added snapshot creation and rollback endpoints to AgentHub, enabling the digital assistant console to manage sandbox checkpoints.
• Preview button & sandbox open logic (feat(agenthub): refine digital assistant preview support #426): The WebUI now includes a preview button alongside sandbox open functionality, with template store defaults corrected.
• Preview documentation (feat(agenthub): refine digital assistant preview support #426): Added AgentHub preview feature guides in both English and Chinese.

🐛 Bug Fixes

• Network-agent: fix existing sandbox network drop on restart (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 (fix(one-click): 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 (fix(dev-env): update default OpenCloudOS image to 9.6-20260514.2 (9.4 download fails) #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) (docs(pvm): add SA9.4XLARGE32 PVM benchmark report (Chinese + English) #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 (docs(perf): fill benchmark tables with real BMI5 test 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 (docs(blog): add v0.3.0 snapshot/clone/rollback post and reorder featured list #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 (docs(usercases): trpc-agent-go: A Secure Code Execution Backend Powered by Cube Sandbox #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 (docs: fix and improve perf benchmark article (zh + en) #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 (docs: update minimum disk space requirements from 300GB to 50GB #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 (docs: remove duplicate Quick Start links in README #430): Cleaned up duplicate Quick Start links in the README, leaving only the top navigation bar entry.

New Contributors

• @husttsq made their first contribution in fix(dev-env): update default OpenCloudOS image to 9.6-20260514.2 (9.4 download fails) #447
• @chengjoey made their first contribution in docs(usercases): trpc-agent-go: A Secure Code Execution Backend Powered by Cube Sandbox #446

Full Changelog: v0.3.0...v0.3.1

---

This discussion was created from the release v0.3.1.