# CubeShim: Implementing the containerd Shim v2 Interface in Cube Sandbox

> Discover CubeShim, the Rust-based containerd shim that translates container commands into MicroVM operations for Cube Sandbox. Explore this key component for efficient container management.

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

---

**CubeShim is the Rust-based containerd shim component that implements the Shim v2 API, translating high-level container lifecycle commands into MicroVM operations for the Cube Sandbox runtime.**

CubeShim serves as the critical bridge between containerd and Cube Sandbox's virtualization layer. Distributed as the binary `containerd-shim-cube-rs`, it exposes the standard Shim v2 gRPC/ttrpc interface while internally managing KVM MicroVM lifecycle through the CubeHypervisor. This architecture allows containerd to treat MicroVMs as standard containers without awareness of the underlying virtualization complexity.

## Architectural Role of CubeShim

CubeShim occupies the middle layer in the Cube Sandbox architecture, sitting between the containerd control plane and the in-VM agent process.

### Control Plane Integration

Containerd issues standard container lifecycle commands—**Create**, **Start**, **Exec**, **Kill**, and **Delete**—through the Shim v2 API. CubeShim receives these commands as the registered runtime handler, appearing to containerd as a standard container runtime while actually orchestrating MicroVMs.

### Shim Layer Implementation

The **CubeShim** binary (`containerd-shim-cube-rs`) implements the actual Shim v2 gRPC/ttrpc interface defined in [`CubeShim/shim/src/service/mod.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeShim/shim/src/service/mod.rs). The `Service` struct in this module receives containerd requests and translates them into actions on the KVM MicroVM. This implementation hides all VM-level details from containerd, presenting a unified container interface.

### VM Communication Bridge

Inside the MicroVM, the `cube-agent` process executes the actual container workload. CubeShim communicates with this agent over **ttrpc** (via vsock), forwarding commands from containerd and returning execution results. This communication flow follows the path `Cubelet → CubeShim → CubeHypervisor` as documented in the architecture overview at [`docs/architecture/overview.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/architecture/overview.md) (lines 25‑27).

## How CubeShim Implements the Shim v2 API

The implementation follows a strict lifecycle from process launch through request handling.

### Process Launch and Runtime Registration

When containerd creates a new sandbox with the `cube` runtime, it spawns the binary `containerd-shim-cube-rs`. The entry point in [`CubeShim/shim/src/main.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeShim/shim/src/main.rs) initializes the Tokio runtime and registers CubeShim as the runtime [`io.containerd.cube.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/io.containerd.cube.rs):

```rust
// CubeShim/shim/src/main.rs
runtime.block_on(shim_run::<Service>("io.containerd.cube.rs", Some(c)));

```

Containerd configuration maps this runtime to the shim binary in [`/etc/containerd/config.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main//etc/containerd/config.toml):

```toml
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.cube]
  runtime_type = "io.containerd.cube.v2"

```

### Service Implementation

The core Shim v2 logic resides in [`CubeShim/shim/src/service/mod.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeShim/shim/src/service/mod.rs) and [`CubeShim/shim/src/service/srv.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeShim/shim/src/service/srv.rs). The `Service` struct implements the required RPC methods, receiving containerd calls and forwarding them to the in-VM `cube-agent`:

```rust
// Conceptual implementation based on CubeShim/shim/src/service/srv.rs
impl Service {
    async fn create(&self, req: CreateTaskRequest) -> Result<CreateTaskResponse> {
        // Forward request to Cubelet to launch VM
        let vm_id = self.vm_manager.launch_vm(req).await?;
        // Wait for vsock handshake from cube-agent
        self.vsock.wait_for_agent(vm_id).await?;
        // Respond to containerd
        Ok(CreateTaskResponse { pid: vm_id.pid, .. })
    }
}

```

### VM Lifecycle Orchestration

For a **Create** request, CubeShim coordinates with Cubelet to launch a MicroVM, passing the rootfs, memory file, and kernel parameters. After the VM boots and establishes the vsock channel, CubeShim reports the sandbox as *running* to containerd. Subsequent operations like `Exec`, `Kill`, and `Delete` are proxied to the `cube-agent` inside the MicroVM.

### State Reporting and Event Emission

CubeShim emits lifecycle events and status changes using the Shim v2 event model, enabling containerd to monitor sandbox health and handle container exits. This includes forwarding exit codes from the in-VM process back to the containerd control plane.

## Advanced Features

CubeShim provides additional capabilities beyond basic container lifecycle management.

### Auto-Pause and Snapshot Support

The shim supports in-place snapshotting of the MicroVM through the snapshot management code in `CubeShim/shim/src/snapshot/`. This enables the auto-pause/resume mechanism used by Cubelet to freeze idle workloads and restore them on demand. The helper binary in [`CubeShim/cube-runtime/src/main.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeShim/cube-runtime/src/main.rs) performs the actual snapshot/restore operations on the VM.

### I/O Forwarding

Standard input, output, and error streams, along with Unix signals, are proxied between the host and the container process inside the MicroVM. This ensures that interactive containers and signal handling behave identically to native containerd runtimes.

## Code Examples

### Registering CubeShim with containerd

Configure containerd to use CubeShim by adding the runtime configuration:

```toml

# /etc/containerd/config.toml

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.cube]
  runtime_type = "io.containerd.cube.v2"

```

Containerd will invoke `containerd-shim-cube-rs` whenever a pod specifies `runtime: cube`, as documented in [`CubeShim/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeShim/README.md) (lines 79‑87).

### Launching a Sandbox via containerd

```bash
ctr run --rm --runtime=cube \
    docker.io/library/ubuntu:latest my-sandbox /bin/bash

```

This triggers the entry point in [`main.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/main.rs), which initializes the Shim v2 service.

### Communicating with the In-VM Agent

CubeShim uses the `ttrpc` crate (as declared in [`CubeShim/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeShim/README.md)) to communicate with `cube-agent` over vsock:

```rust
let client = ttrpc::client::Client::new("/run/vhost/vsock");
let agent = cube_agent::AgentClient::new(client);
let exec_resp = agent.exec(ExecRequest { 
    cmd: "/bin/ls".into(), 
    .. 
}).await?;

```

## Summary

- **CubeShim** implements the containerd Shim v2 interface as a Rust-based shim binary (`containerd-shim-cube-rs`).
- The `Service` struct in [`CubeShim/shim/src/service/mod.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeShim/shim/src/service/mod.rs) handles the gRPC/ttrpc interface for container lifecycle operations.
- CubeShim registers as the runtime [`io.containerd.cube.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/io.containerd.cube.rs) and translates containerd commands into MicroVM operations via the CubeHypervisor.
- Communication with the in-VM workload occurs through **ttrpc** over vsock to the `cube-agent`.
- The implementation supports **auto-pause/resume** through in-place VM snapshotting and provides full I/O forwarding between host and MicroVM.

## Frequently Asked Questions

### What is the binary name of CubeShim?

The compiled CubeShim binary is named `containerd-shim-cube-rs`. This executable serves as the entry point that containerd spawns when creating new sandboxes with the Cube runtime, as defined in [`CubeShim/shim/src/main.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeShim/shim/src/main.rs).

### How does CubeShim communicate with containers inside the MicroVM?

CubeShim communicates with the in-VM `cube-agent` process using **ttrpc** (a lightweight RPC framework) over a vsock channel. This allows the shim to forward commands like `Exec` and `Kill` from containerd to the actual container process running inside the KVM MicroVM.

### What runtime name does CubeShim register with containerd?

CubeShim registers itself as the runtime [`io.containerd.cube.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/io.containerd.cube.rs) in the [`main.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/main.rs) entry point. Containerd administrators configure this runtime in [`config.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main/config.toml) to route container operations to the CubeShim binary.

### How does CubeShim handle VM snapshots?

CubeShim implements auto-pause/resume functionality through in-place snapshotting managed by the code in `CubeShim/shim/src/snapshot/`. When Cubelet requests a pause, CubeShim coordinates with the CubeHypervisor to snapshot the MicroVM state, enabling fast restoration when the workload resumes.