CubeSandbox Memory Overhead Per Instance: A Technical Breakdown

Each CubeSandbox instance incurs approximately 30–50 MiB of hypervisor overhead on top of the allocated guest RAM, making the total host memory footprint roughly Guest RAM + 40 MiB.

CubeSandbox, TencentCloud's lightweight virtualization solution built on Cloud Hypervisor, isolates workloads using VM-based sandboxes. Understanding the CubeSandbox memory overhead per instance is essential for accurately sizing hosts when running multiple isolated environments, as the accumulated fixed costs impact total available capacity.

How CubeSandbox Allocates Host Memory

According to the TencentCloud/CubeSandbox source code, a CubeSandbox instance runs a Cloud Hypervisor VM that consumes host memory through two distinct components: the explicitly configured guest RAM and the fixed hypervisor overhead.

Guest RAM Allocation

The dominant memory consumer is the guest RAM, which you configure using the --memory size=<size> option. This allocation is exact—specifying --memory size=1G reserves exactly 1 GiB of host memory for the virtual machine. This value represents the majority of the total memory footprint and scales linearly with your workload requirements.

Hypervisor Overhead

The second component consists of the hypervisor overhead required by the Cloud Hypervisor process itself. As documented in hypervisor/docs/memory.md, this overhead covers:

• Kernel and device model structures
• Page tables and bookkeeping structures
• Virtio devices and temporary buffers
• VM management, snapshot, and restore infrastructure

This memory usage is independent of guest RAM size and typically consumes 30–50 MiB per instance.

Calculating Total Memory Footprint

The total host memory consumption follows a predictable additive formula:

Total host memory ≈ Guest RAM + 30-50 MiB

For example, configuring a sandbox with --memory size=2G results in approximately 2 GiB + 40 MiB of actual host memory usage.

# Launch a CubeSandbox instance

./cubesandbox --memory size=2G --cpus boot=2

# Expected host memory consumption: ~2.04 GiB total

Capacity Planning for Multi-Instance Deployments

When running dozens of CubeSandbox instances on a single host, the per-instance overhead accumulates linearly. Because each VM requires an extra ~40 MiB beyond its allocated guest RAM, a host running 100 instances needs approximately 4 GiB of additional memory to accommodate hypervisor structures.

The profiling documentation in hypervisor/docs/profiling.md references this "lower overhead" design, confirming that the Cloud Hypervisor implementation deliberately minimizes memory usage for VM management, I/O handling, and snapshot/restore operations to maximize the resources available for guest workloads.

Summary

• CubeSandbox instances consume 30–50 MiB of fixed hypervisor overhead per VM
• Total host memory equals configured guest RAM plus approximately 40 MiB of management structures
• The overhead remains constant regardless of guest memory size, enabling predictable capacity calculations
• Implementation details are documented in hypervisor/docs/memory.md and hypervisor/docs/profiling.md

Frequently Asked Questions

Is CubeSandbox's memory overhead fixed regardless of VM size?

Yes. The hypervisor overhead remains relatively constant at 30–50 MiB per instance whether you allocate 512 MiB or 64 GiB of guest RAM. This fixed overhead model simplifies memory capacity planning compared to solutions where overhead scales proportionally with allocated memory.

How does CubeSandbox overhead compare to traditional QEMU/KVM?

CubeSandbox achieves significantly lower overhead through its Cloud Hypervisor implementation. While traditional QEMU instances often consume hundreds of megabytes of host memory for device emulation and management structures, CubeSandbox maintains overhead to a few dozen megabytes through optimized virtio device handling and streamlined kernel structures.

Where is the memory configuration documented?

The memory allocation parameters and hypervisor requirements are documented in hypervisor/docs/memory.md within the TencentCloud/CubeSandbox repository. This file explains the --memory size=<size> parameter and describes how additional host memory is used for internal hypervisor structures.

Does the hypervisor overhead increase under heavy I/O load?

The base overhead of 30–50 MiB covers static structures and basic virtio device management. While temporary buffers may fluctuate slightly during intense I/O operations, the design documented in hypervisor/docs/profiling.md emphasizes maintaining consistently low overhead, ensuring that memory usage remains predictable during snapshot, restore, and I/O handling operations.

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