Memory Overhead of a CubeSandbox Instance: Host Resource Requirements Explained

A CubeSandbox instance consumes approximately 30–50 MiB of fixed hypervisor overhead in addition to the explicitly allocated guest RAM, resulting in a total host memory footprint of Guest RAM plus roughly 40 MiB.

When provisioning lightweight virtual machines with TencentCloud/CubeSandbox, understanding the precise memory overhead of a CubeSandbox instance is critical for capacity planning. Each sandbox runs as a Cloud Hypervisor VM on the host, consuming not only the memory you allocate to the guest operating system but also additional resources for the hypervisor process itself.

Memory Components of a CubeSandbox VM

Guest RAM Allocation

The primary memory consumer is the Guest RAM, which you explicitly configure using the --memory size=<size> parameter. This value represents exactly what the guest virtual machine sees as available memory. For example, specifying --memory size=2G reserves precisely 2 GiB of host memory for the guest, as documented in hypervisor/docs/memory.md.

Hypervisor Overhead

Beyond the guest allocation, the Cloud Hypervisor process maintains internal structures for kernel management, device models, page tables, virtio devices, and temporary I/O buffers. According to the profiling documentation in hypervisor/docs/profiling.md, this overhead remains deliberately minimal to achieve "lower overhead" operation. The fixed cost per instance typically falls between 30 MiB and 50 MiB, regardless of how large or small you configure the guest memory.

Calculating Total Host Memory Usage

The total host memory footprint follows a predictable formula:

Total Host Memory ≈ Guest RAM + 30‑50 MiB

For a concrete example, a sandbox configured with --memory size=2G occupies approximately 2 GiB plus 40 MiB of overhead, totaling roughly 2.04 GiB. This represents only a few percent extra beyond the guest memory you requested.

Why Hypervisor Overhead Matters for Multi-Tenant Deployments

While 40 MiB seems insignificant for single instances, the per-instance overhead accumulates rapidly when running dozens of sandboxes on a single host. Understanding that each CubeSandbox VM requires this fixed additional allocation prevents out-of-memory failures during dense multi-tenant deployments. The memory configuration guide confirms that this overhead supports VM management, snapshot/restore operations, and I/O handling without scaling with guest memory size.

Summary

• CubeSandbox instances run as Cloud Hypervisor VMs with two distinct memory components
• Guest RAM matches exactly the value specified via --memory size=<size>
• Hypervisor overhead adds a fixed 30–50 MiB per instance for internal structures and device management
• Total host memory consumption follows the formula: Guest RAM + ~40 MiB
• Source documentation in hypervisor/docs/memory.md and hypervisor/docs/profiling.md validates these measurements

Frequently Asked Questions

What is the fixed memory overhead per CubeSandbox instance?

Each CubeSandbox instance incurs approximately 30–50 MiB of hypervisor overhead beyond the allocated guest RAM. This covers the Cloud Hypervisor process itself, including kernel structures, virtio devices, and bookkeeping overhead required for VM operation.

How does the hypervisor overhead compare to the guest RAM?

The hypervisor overhead remains constant regardless of guest memory size. While guest RAM scales from megabytes to gigabytes based on your --memory size configuration, the Cloud Hypervisor overhead stays fixed at roughly 40 MiB, representing a negligible percentage for larger VMs but a more significant proportion for tiny sandboxes.

Where is the memory overhead documented in the CubeSandbox repository?

The memory configuration parameters are documented in hypervisor/docs/memory.md, which explains guest RAM allocation and acknowledges additional host memory usage for hypervisor structures. The "lower overhead" design philosophy is specifically mentioned in hypervisor/docs/profiling.md in the context of minimizing resource consumption.

Does the overhead increase with larger guest memory allocations?

No. The hypervisor overhead is independent of guest RAM size. Whether you allocate 512 MiB or 16 GiB to a sandbox, the Cloud Hypervisor process maintains the same approximately 30–50 MiB footprint for page tables, device models, and management structures.

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