github.com/TencentCloud/CubeSandbox

---

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.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.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.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.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.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.1.2 — 2026.04.27

2026.04.27 Release v0.1.2

🛠️ Critical Fixes

• Fixed the issue where CubeMaster returned a 5xx error instead of a 4xx error when the sandbox template does not exist.
• Fixed the missing SSL RootCA certificate issue during one-click deployment in v0.1.1.
• Fixed the cube proxy image build failure during deployment in v0.1.1.

---

title: v0.1.1 — 2026.04.24

2026.04.24 Release v0.1.1

🛠️ Critical Fixes

• Fixed the issue where the latest vmlinux was not used during template reconstruction, improving the stability of the sandbox environment.
• Updated the one-click installation script to support non-eth0 network interfaces, resolving stability issues with CubeProxy CA certificates.
• Disabled GRO on the primary network interface during initialization to enhance network stability.
• Fixed incorrect error handling when the target was not found during template cleanup, ensuring proper error returns.

✨ New Features

• Added the cubebox destroy command, enabling sandbox deletion via the CLI.
• Added integration examples for the OpenAI Agents SDK (including a code interpreter).

📚 Documentation Updates

• Rewrote the HTTPS and domain configuration documentation, adding explanations for wildcard DNS records.

⚙️ Engineering Improvements

• Implemented a parallel CI build pipeline for multiple components to optimize build efficiency.
• Added support for automatic synchronization of GitHub Release assets to cnb.cool/CubeSandbox/CubeSandbox.

---

title: v0.1.0 — 2026.04.20

2026.04.20 Release v0.1.0

Initial open-source release of Cube Sandbox

Instant, Concurrent, Secure & Lightweight Sandbox for AI Agents.

Core Highlights

Cube Sandbox is a high-performance, out-of-the-box secure sandbox service built on RustVMM and KVM. It supports both single-node deployment and can be easily scaled to a multi-node cluster. It is compatible with the E2B SDK, capable of creating a hardware-isolated sandbox environment with full service capabilities in under 60ms, while maintaining less than 5MB memory overhead.

• Blazing-fast cold start: built on resource pool pre-provisioning and snapshot cloning technology, average end-to-end cold start time for a fully serviceable sandbox is < 60ms.

• High-density deployment on a single node: extreme memory reuse via CoW technology combined with a Rust-rebuilt, aggressively trimmed runtime keeps per-instance memory overhead below 5MB — run thousands of Agents on a single machine.

• True kernel-level isolation: each Agent runs with its own dedicated Guest OS kernel, eliminating container escape risks and enabling safe execution of any LLM-generated code.

• Zero-cost migration (E2B drop-in replacement): natively compatible with the E2B SDK interface. Just swap one URL environment variable — no business logic changes needed.

• Network security: CubeVS, powered by eBPF, enforces strict inter-sandbox network isolation at the kernel level with fine-grained egress traffic filtering policies.

Production-ready

Cube Sandbox has been validated at scale in Tencent Cloud production environments, proven stable and reliable — before this day it ever existed as open source, it had already quietly run behind real AI Agent workloads, serving real users, at production load.

In real production deployments, a single physical machine can spin up tens of thousands of sandboxes within minutes.

We open-source it today not as a prototype, but as production-hardened infrastructure that has already stood the test of real-world scale.

A Note to Every Contributor — Past, Present, and Future

Before this code was ever public, it was already doing its job: spinning up sandboxes in milliseconds, isolating Agent workloads at the kernel level, and holding up under real production load at Tencent Cloud. None of that happened by accident.

Today we open the door. The high-performance Agent infrastructure you shaped now belongs to the world — to every developer who believes that safe, instant, and lightweight code execution should be open and self-hostable.

To those who contributed before this day: you built the foundation. To those who will contribute after: you are what turns a foundation into an ecosystem.

Open source shines because of you!