CubeSandbox Memory Overhead per Sandbox Instance: Baseline, Benchmarks, and Configuration

CubeSandbox maintains less than 5 MiB of static memory overhead per sandbox instance through kernel sharing and Copy-on-Write, with real-world amortized costs ranging from 21–26 MiB for typical 2 GiB templates.

TencentCloud/CubeSandbox is engineered to minimize resource consumption through aggressive page sharing and lazy allocation strategies. Understanding the exact memory overhead per sandbox instance is critical for capacity planning when hosting thousands of isolated workloads on a single node.

Baseline Static Overhead

According to the README.md in the TencentCloud/CubeSandbox repository, the platform guarantees less than 5 MiB of memory overhead per sandbox instance at idle. This figure represents the "static" cost that persists even when a sandbox allocates no user memory pages. The implementation achieves this through kernel sharing and Copy-on-Write (CoW) semantics, ensuring that immutable system pages are referenced rather than duplicated across instances.

Kernel Sharing Mechanisms

The sub-5 MiB baseline relies on two architectural decisions implemented in the hypervisor layer. First, the kernel image is shared across all sandboxes on a host, eliminating redundant code segment allocations. Second, CoW paging ensures that memory pages are only materialized when written to, keeping the per-instance footprint minimal until actual data mutation occurs.

Real-World Amortized Memory Costs

While the theoretical baseline is under 5 MiB, production deployments exhibit higher practical overhead once the kernel and CoW mechanisms initialize. According to docs/blog/posts/2026-06-01-cubesandbox-perf-benchmark.md (lines 39–42), creating a sandbox from a 2 GiB template results in approximately 21–26 MiB of actual memory growth per instance on the host process.

This measured overhead remains significantly below the full template size because pages are allocated on-demand rather than eagerly. The 21–26 MiB range accounts for the VM structure, process tables, and initial page tables required to maintain the sandbox state.

Configuration-Driven Overhead Parameters

The Cubelet component exposes tunable parameters for memory accounting in Cubelet/config/config.toml (lines 56–59). The configuration defines a base VM memory overhead of 42 MiB plus a coefficient-based component calculated as 64 × CPU-milli. These values inform the resource scheduler's calculations when requesting memory from the underlying hypervisor.

Operators can inspect these settings to predict total node consumption using the formula: total_overhead = 42 MiB + (0.064 MiB × CPU_milliseconds). This accounting ensures that the scheduler reserves sufficient headroom for VM bookkeeping structures beyond the guest-visible allocation.

SDK Implementation and Memory Limits

When provisioning sandboxes through the official SDKs, the memory_mb parameter specifies the guest-visible allocation, while the platform automatically adds the overhead described above. The Python SDK handles this through the CubesandboxClient.create_sandbox() method:

from cubesandbox import CubesandboxClient

client = CubesandboxClient(api_key="your-key", api_url="http://localhost:3000")
sandbox = client.create_sandbox(template_id="tpl-xyz", memory_mb=2048)
print(f"Sandbox {sandbox.id} started, using {sandbox.memory_mb} MiB")

Similarly, the Go SDK provides visibility into actual consumption through the GetSandbox method:

client := cubesandbox.NewClient("http://localhost:3000", "your-key")
sb, _ := client.GetSandbox(context.Background(), "sandbox-id")
fmt.Printf("Sandbox uses %.2f GiB (%.0f MiB)\n",
    float64(sb.MemoryMB)/1024, sb.MemoryMB)

These implementations demonstrate how the memory_mb field maps to guest configuration while the runtime overhead remains transparent to the user workload.

Summary

• CubeSandbox maintains a static memory overhead of less than 5 MiB per instance through kernel sharing and Copy-on-Write semantics as documented in README.md (lines 44–45).
• Real-world benchmarks show 21–26 MiB of amortized overhead when instantiating 2 GiB templates, accounting for VM management structures.
• The Cubelet configuration (Cubelet/config/config.toml lines 56–59) defines a 42 MiB base overhead plus a 64-byte-per-CPU-milli coefficient for resource scheduling calculations.
• SDKs automatically handle overhead allocation; users specify guest memory via memory_mb parameters in Python's create_sandbox() or Go's GetSandbox() methods.

Frequently Asked Questions

What is the minimum memory overhead for an idle CubeSandbox instance?

The absolute minimum static overhead is less than 5 MiB per sandbox instance. This figure, documented in the repository's README.md (lines 44–45), represents the cost of process tables and shared kernel references when no user pages have been touched.

How does Copy-on-Write affect memory usage in CubeSandbox?

Copy-on-Write (CoW) allows multiple sandboxes to share identical memory pages until a write occurs. This mechanism ensures that the initial memory overhead per sandbox instance remains under 5 MiB, with pages only materializing when modified by the guest workload.

Why does the Cubelet configuration specify 42 MiB base overhead?

The 42 MiB base VM memory overhead defined in Cubelet/config/config.toml (lines 56–59) represents the conservative accounting value used by the scheduler to reserve space for hypervisor structures, device emulation, and metadata beyond the theoretical minimum, ensuring stable operation under load.

How does CPU allocation impact memory overhead in CubeSandbox?

The configuration applies a coefficient of 64 × CPU-milli, meaning each millicore allocated adds 64 bytes to the overhead calculation. This accounts for scheduling data structures and interrupt handling tables that scale with processing capacity rather than guest memory size.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}