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

> Discover CubeSandbox memory overhead per sandbox instance. Learn about baseline, benchmarks, and configuration for efficient resource management, achieving <5 MiB static overhead.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: performance
- Published: 2026-07-10

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```python
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:

```go
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.