# How to Configure containerd to Use CubeSandbox: Complete Integration Guide

> Integrate CubeSandbox with containerd. Learn how to configure containerd to use CubeSandbox by installing CubeShim, registering the custom runtime, and updating Cubelet for enhanced container security.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: how-to-guide
- Published: 2026-07-05

---

**Configure containerd to use CubeSandbox by installing the CubeShim binary, registering the `io.containerd.cube.v2` runtime type in containerd's configuration, and updating Cubelet to request the `cube` runtime class.**

CubeSandbox is a Micro-VM-based sandbox runtime developed by TencentCloud that integrates with containerd through a custom Shim v2 implementation. This guide walks you through the exact configuration steps required to route container workloads through the CubeShim binary, enabling KVM-backed sandbox execution alongside standard containers.

## Understanding the CubeShim Architecture

CubeSandbox integrates with containerd via **CubeShim**, a custom shim binary named `containerd-shim-cube-rs` that implements the containerd Shim v2 API. This shim exposes the lifecycle of a Micro-VM-based sandbox to containerd, managing the transition from container specification to KVM virtual machine execution.

The communication flow follows this path: **Cubelet** ↔ **containerd** ↔ **CubeShim** ↔ **CubeHypervisor** ↔ **guest VM**. When containerd receives a request for the `cube` runtime, it spawns the shim process, which then prepares the root filesystem, memory file, and kernel before launching the VM via the CubeHypervisor. The architecture is documented in [`/docs/zh/architecture/overview.md`](https://github.com/TencentCloud/CubeSandbox/blob/main//docs/zh/architecture/overview.md) within the TencentCloud/CubeSandbox repository.

## Step-by-Step Configuration Guide

### Step 1: Install the CubeShim Binary

The CubeShim binary (`containerd-shim-cube-rs`) is built as part of the one-click release deployment. By default, the installer places the binary at `/usr/local/services/cubetoolbox/cube-shim/bin/containerd-shim-cube-rs` and creates a symbolic link in `/usr/local/bin` to ensure containerd can locate the executable.

According to the installation script at [`deploy/one-click/install.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/deploy/one-click/install.sh), this setup happens automatically during the one-click installation process. Verify the binary exists and is accessible in your system path:

```bash
ls -la /usr/local/bin/containerd-shim-cube-rs
ls -la /usr/local/services/cubetoolbox/cube-shim/bin/containerd-shim-cube-rs

```

### Step 2: Register the Cube Runtime in containerd

You must register the CubeSandbox runtime in containerd's configuration file, typically located at [`/etc/containerd/config.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main//etc/containerd/config.toml). This registration tells containerd how to locate and spawn the shim when a workload requests the `cube` runtime.

Add the following runtime configuration to your containerd config file:

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

```

The `runtime_type` value `io.containerd.cube.v2` corresponds to the shim's registration name as defined in the CubeShim source code ([`CubeShim/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeShim/README.md)). After updating the configuration, restart containerd to apply the changes:

```bash
sudo systemctl restart containerd

```

### Step 3: Configure Cubelet to Use the Runtime

Cubelet must be configured to request the `cube` runtime when creating sandboxes. In the Cubelet configuration file ([`Cubelet/config/config.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/config/config.toml)), set the `runtime_type` to [`io.containerd.cube.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/io.containerd.cube.rs) and ensure the shim configuration path points to the on-disk configuration file:

```toml

# Cubelet/config/config.toml

runtime_type = "io.containerd.cube.rs"

```

The [`config-cube.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main/config-cube.toml) file (located at [`deploy/one-click/config-cube.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main/deploy/one-click/config-cube.toml)) contains default paths for the shim binary, guest kernel, and guest image. Ensure this configuration file exists at the path referenced by Cubelet, as it provides the CubeShim with essential parameters for VM initialization.

## Verification and Testing

Once configured, verify that containerd recognizes the CubeSandbox runtime:

```bash

# Check registered runtimes

containerd info | grep cube

```

You should see `io.containerd.cube.v2` in the output, confirming the shim is properly registered.

To launch a sandbox using the CubeSandbox runtime, create a pod specification with the `runtimeClassName` set to `cube`:

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: cubesandbox-demo
spec:
  runtimeClassName: cube
  containers:
  - name: demo
    image: alpine:latest
    command: ["sleep", "3600"]

```

Apply the configuration:

```bash
kubectl apply -f pod.yaml

```

You can verify the shim is running by inspecting the process list:

```bash
pgrep -a containerd-shim-cube-rs

```

The output should show the shim process with arguments including `--runtime io.containerd.cube.v2` and the sandbox ID.

## Summary

- **CubeShim** (`containerd-shim-cube-rs`) is the custom Shim v2 implementation that bridges containerd and CubeSandbox's Micro-VM architecture.
- Install the binary at `/usr/local/services/cubetoolbox/cube-shim/bin/containerd-shim-cube-rs` with a symlink to `/usr/local/bin`.
- Register the runtime in [`/etc/containerd/config.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main//etc/containerd/config.toml) using `runtime_type = "io.containerd.cube.v2"`.
- Configure Cubelet in [`Cubelet/config/config.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/config/config.toml) to use [`io.containerd.cube.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/io.containerd.cube.rs) and reference [`config-cube.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main/config-cube.toml) for VM parameters.
- Use `runtimeClassName: cube` in pod specifications to trigger Micro-VM sandbox execution.

## Frequently Asked Questions

### What is the exact runtime type name for CubeSandbox in containerd?

The runtime type name registered in containerd's configuration is **`io.containerd.cube.v2`**. This value must be specified as the `runtime_type` in [`/etc/containerd/config.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main//etc/containerd/config.toml) under the `runtimes.cube` section. Note that Cubelet uses a slightly different internal reference ([`io.containerd.cube.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/io.containerd.cube.rs)), but containerd itself recognizes the `.v2` suffix for Shim v2 API compatibility.

### Where does the CubeShim binary get installed by default?

The default installation path is **`/usr/local/services/cubetoolbox/cube-shim/bin/containerd-shim-cube-rs`**. The one-click installer ([`deploy/one-click/install.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/deploy/one-click/install.sh)) creates a symbolic link at `/usr/local/bin/containerd-shim-cube-rs` to ensure containerd can locate the binary without requiring modifications to the system PATH.

### How does Cubelet communicate with CubeShim through containerd?

Cubelet sends sandbox creation requests to containerd, which then spawns the `containerd-shim-cube-rs` process as the runtime handler. The shim implements the ttrpc API to communicate with the **cube-agent** running inside the guest VM via a vsock channel. This flow is documented in the architecture overview at [`docs/zh/architecture/overview.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/zh/architecture/overview.md).

### Can I run CubeSandbox alongside standard runc containers?

Yes, CubeSandbox is designed to run alongside standard container runtimes like **runc**. By using Kubernetes RuntimeClasses or Docker's `--runtime` flag, you can specify which workloads use the `cube` runtime versus the default runtime. This allows hybrid deployments where some pods run as Micro-VMs while others run as traditional containers on the same node.