CubeHypervisor and Its Relation to RustVMM: A Technical Deep Dive

CubeHypervisor is a high-level wrapper that adapts the RustVMM (Cloud Hypervisor) library to manage KVM-based MicroVMs within CubeSandbox, delegating low-level virtualization tasks to the RustVMM while providing container-runtime-compatible lifecycle APIs.

CubeHypervisor serves as the virtualization core of CubeSandbox, TencentCloud's sandboxed container runtime. Built atop the RustVMM framework (specifically the Cloud Hypervisor implementation), it bridges the gap between lightweight container orchestration and hardware-assisted virtualization, enabling sub‑60 ms boot times and memory footprints under 5 MiB per sandbox. This article examines the architectural relationship between CubeHypervisor and RustVMM, demonstrating how the wrapper pattern isolates sandbox-specific logic from low-level KVM operations.

What Is CubeHypervisor?

CubeHypervisor is a façade component that owns and operates KVM-based MicroVMs isolating each sandbox instance. Defined in [CubeShim/shim/src/hypervisor/cube_hypervisor.rs](https://github.com/TencentCloud/CubeSandbox/blob/master/CubeShim/shim/src/hypervisor/cube_hypervisor.rs), the CubeHypervisor struct holds a Vmm instance and exposes methods like new, create, start, and shutdown that align with container runtime conventions.

Unlike a monolithic hypervisor, CubeHypervisor acts as a thin adapter. It translates high-level sandbox lifecycle operations into low-level VM management commands understood by the underlying RustVMM implementation. This design allows CubeSandbox to treat MicroVMs as ephemeral compute units—similar to container processes—while retaining the security boundaries of full hardware virtualization.

Understanding RustVMM in CubeSandbox

RustVMM refers to the library implementation residing in [hypervisor/vmm/src/lib.rs](https://github.com/TencentCloud/CubeSandbox/blob/master/hypervisor/vmm/src/lib.rs) that provides direct KVM abstractions. The Vmm struct in this file creates and manages the Vm (the actual KVM VM instance), drives the vCPU event loop, and handles device hot-plug operations.

The RustVMM layer handles:

• Guest memory mapping and address space initialization
• Seccomp filtering for sandbox security
• CPU hot-plug and virtualization extensions
• Device model management (virtio-net, virtio-blk, etc.)
• VM lifecycle transitions (create, boot, pause, resume, shutdown)

According to the CubeSandbox source code, the Vmm implementation constructs the VM and applies seccomp filters before spawning the VMM thread that runs the event loop.

How CubeHypervisor Wraps RustVMM

The relationship follows a wrapper pattern where CubeHypervisor instantiates and configures the RustVMM Vmm while adding CubeSandbox-specific orchestration.

Initialization Flow

When a sandbox starts, the CubeShim invokes CubeHypervisor::new, which internally constructs a Vmm with the selected hypervisor implementation (currently KVM). This method configures the logger, loads the hypervisor configuration from JSON, and prepares the VMM thread. The initialization sequence demonstrates the dependency: CubeHypervisor cannot function without the RustVMM foundation, but it abstracts the complexity away from the shim layer.

Thread Management

CubeHypervisor calls start_vmm_thread (defined in [hypervisor/vmm/src/lib.rs](https://github.com/TencentCloud/CubeSandbox/blob/master/hypervisor/vmm/src/lib.rs)) to spawn the actual VMM execution context. This function accepts parameters including the version string, optional HTTP API socket path, seccomp action policy, and sandbox identifier. The thread creation delegates directly to RustVMM's control loop, which manages KVM file descriptors and vCPU state.

Lifecycle Delegation

All heavy virtualization operations pass through to RustVMM. For example, when CubeHypervisor receives a request to boot a VM, it invokes vmm.create_vm() followed by vm.boot(), where create_vm and boot are methods implemented in the RustVMM layer. CubeHypervisor adds only sandbox-wide shutdown coordination, metrics collection, and integration with the CubeVS network stack.

Code Examples

The following snippets illustrate the delegation pattern from CubeHypervisor to RustVMM.

Instantiating CubeHypervisor

use cube_hypervisor::CubeHypervisor;
use cube_hypervisor::config::HypervisorConfig;

// Load configuration from sandbox template
let hyp_cfg = HypervisorConfig::from_file("config/hypervisor.json")?;

// Initialize shared logger
let logger = slog::Logger::root(slog::Discard, slog::o!());

// Create hypervisor instance (internally constructs RustVMM Vmm)
let cube_hypervisor = CubeHypervisor::new(hyp_cfg, logger)?;

This initialization corresponds to the implementation in [CubeShim/shim/src/hypervisor/cube_hypervisor.rs](https://github.com/TencentCloud/CubeSandbox/blob/master/CubeShim/shim/src/hypervisor/cube_hypervisor.rs), where CubeHypervisor::new builds the underlying Vmm and prepares the execution environment.

Spawning the VMM Thread

let vmm_version = "cube-hypervisor-0.5".to_string();
let http_path = None;           // Optional HTTP API socket
let seccomp_action = SeccompAction::Allow; // Or custom filter
let sandbox_id = "sandbox-123".to_string();

let vmm_handle = cube_hypervisor.start_vmm_thread(
    vmm_version,
    &http_path,
    None,
    seccomp_action,
    sandbox_id,
)?;

The start_vmm_thread method delegates to [hypervisor/vmm/src/lib.rs](https://github.com/TencentCloud/CubeSandbox/blob/master/hypervisor/vmm/src/lib.rs), which creates the Vmm object, applies seccomp filters, and spawns the VMM thread.

Booting the MicroVM

let vm_cfg = vm::VmConfig::load("config/vm.json")?;
let vm = vmm.create_vm(vm_cfg)?;   // RustVMM creates KVM VM
vm.boot()?;                         // Starts guest execution

Here, create_vm and boot are methods on the RustVMM Vmm struct, demonstrating how CubeHypervisor relies on the underlying library for actual virtualization operations.

Key Source Files and Components

Understanding the codebase requires familiarity with these specific files:

• hypervisor/vmm/src/lib.rs – Implements the Vmm struct, VM lifecycle management, seccomp filtering, and the VMM thread control loop.

• CubeShim/shim/src/hypervisor/cube_hypervisor.rs – Defines the CubeHypervisor struct, which wraps the RustVMM Vmm and exposes container-runtime-friendly APIs.

• hypervisor/vmm/src/vm.rs – Contains the low-level Vm struct that wraps KVM file descriptors and manages guest memory and vCPUs.

• CubeShim/shim/src/config/hypervisor.rs – Holds the JSON-serializable configuration structures passed to CubeHypervisor::new.

• hypervisor/arch/src/x86_64/smbios.rs – Injects "Cube Hypervisor" branding into the VM's SMBIOS tables, identifying the hypervisor to the guest OS.

• docs/architecture/overview.md – Documents the data-plane stack and illustrates the relationship between CubeHypervisor and RustVMM components.

Summary

• CubeHypervisor is a high-level wrapper in the CubeShim that exposes container-like APIs for MicroVM management.
• RustVMM provides the low-level KVM virtualization logic in hypervisor/vmm/src/lib.rs, handling memory, vCPUs, and devices.
• CubeHypervisor instantiates the RustVMM Vmm via CubeHypervisor::new and delegates heavy operations to RustVMM methods like create_vm and boot.
• The wrapper pattern enables CubeSandbox to combine RustVMM's performance and security with sandbox-specific orchestration such as network integration and lifecycle management.
• All KVM interactions, seccomp filtering, and hardware abstraction occur within the RustVMM layer, while CubeHypervisor manages the shim-specific context.

Frequently Asked Questions

How does CubeHypervisor differ from RustVMM?

CubeHypervisor is an orchestration layer that adapts RustVMM to container runtime requirements. While RustVMM handles low-level KVM operations such as vCPU scheduling and memory mapping, CubeHypervisor manages sandbox lifecycle events, configuration loading, and integration with CubeSandbox's networking stack. Think of CubeHypervisor as the API surface and RustVMM as the virtualization engine.

Can CubeHypervisor work with hypervisors other than KVM?

Currently, the implementation in hypervisor/vmm/src/lib.rs uses the Hypervisor trait abstraction that could theoretically support other backends, but the CubeSandbox codebase specifically configures the KVM implementation. The CubeHypervisor::new method instantiates a KVM-backed Vmm by default, as evidenced by the seccomp policies and device models targeting Linux KVM.

What configuration does CubeHypervisor pass to RustVMM?

CubeHypervisor passes a HypervisorConfig structure (defined in CubeShim/shim/src/config/hypervisor.rs) containing VM parameters such as memory size, vCPU count, virtio device configurations, and seccomp policies. This configuration is loaded from JSON templates and fed into the RustVMM Vmm during initialization via start_vmm_thread.

Where is the "Cube Hypervisor" branding visible to guests?

The branding appears in the SMBIOS tables of the guest VM. The file hypervisor/arch/src/x86_64/smbios.rs injects the vendor string "Cube Hypervisor" into the system firmware tables, allowing operating systems running inside the MicroVM to identify the underlying virtualization platform.

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