# CubeHypervisor and Its Relation to RustVMM: A Technical Deep Dive

> Explore CubeHypervisor and its link to RustVMM. Discover how CubeHypervisor manages KVM MicroVMs within CubeSandbox, leveraging RustVMM for virtualization.

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

---

**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/main/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/main/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/main/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

```rust
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/main/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

```rust
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/main/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

```rust
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeShim/shim/src/config/hypervisor.rs)** – Holds the JSON-serializable configuration structures passed to `CubeHypervisor::new`.

- **[`hypervisor/arch/src/x86_64/smbios.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.