How to Deploy CubeSandbox on Cloud VMs (PVM) vs Bare Metal: A Complete Guide

CubeSandbox deploys on cloud VMs using the PVM (Pagetable-based Virtual Machine) kernel extension to provide KVM-like isolation without requiring /dev/kvm, while bare-metal deployments use native KVM directly.

Deploying CubeSandbox on cloud VMs (PVM) vs bare metal requires understanding two distinct isolation mechanisms for running sandboxed workloads. The TencentCloud/CubeSandbox repository supports both Pagetable-based Virtual Machines (PVM) for nested virtualization on ordinary cloud servers and standard KVM for dedicated physical hardware. This guide walks through the exact deployment workflows, kernel requirements, and architectural differences based on the official source documentation.

Understanding PVM vs Bare-Metal Architecture

PVM (Pagetable-based Virtual Machine)

PVM is a page-table-based nested-virtualization layer built on top of KVM that does not require the host to expose /dev/kvm. After installing a special PVM host kernel, the kernel supplies a virtual KVM device (kvm_pvm) that the Cube Sandbox guest kernel uses. This allows the sandbox to run inside a Micro-VM even on ordinary cloud VMs where nested virtualization is disabled, such as Tencent Cloud CVM instances.

Bare-Metal Deployment

Bare-metal deployments rely on a standard Linux kernel with native KVM support. The host must expose /dev/kvm directly, allowing CubeSandbox to launch Micro-VMs without additional kernel modifications. This approach works on physical servers, dedicated bare-metal hosts, or cloud VMs that already enable nested virtualization.

Deploying CubeSandbox on PVM (Cloud VMs)

PVM deployment requires installing a custom host kernel before running the CubeSandbox installer. According to docs/zh/guide/pvm-deploy.md, the process is strictly x86_64-only.

Prerequisites

You need a root-privileged x86_64 Linux server running any distribution, though OpenCloudOS 9 is recommended. The host does not need /dev/kvm available.

Install the PVM Host Kernel

Download the PVM kernel RPM or DEB from the CubeSandbox releases page. Install the package using rpm -ivh or dpkg -i, then set the new kernel as the default boot entry using grubby (RPM) or by editing /etc/default/grub (DEB).

Run the helper script deploy/pvm/grub/host_grub_config.sh to add required kernel parameters, then reboot. Verify the kernel version contains the string opencloudos9.cubesandbox.pvm.host as shown in docs/zh/guide/pvm-deploy.md lines 40-45.

Load the PVM KVM module and ensure it persists across reboots:

modprobe kvm_pvm
echo "kvm_pvm" > /etc/modules-load.d/kvm-pvm.conf

Install CubeSandbox with PVM Enabled

Run the one-click installer with the CUBE_PVM_ENABLE=1 environment variable. This tells the installer to copy the PVM guest kernel (vmlinux-pvm) over the regular guest kernel, as implemented in docs/zh/guide/pvm-deploy.md lines 62-66:

CUBE_PVM_ENABLE=1 curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | bash

If using a .env file, ensure CUBE_PVM_ENABLE=1 is set there, as variables from the file override environment settings according to docs/zh/guide/pvm-deploy.md lines 102-110.

Validate the PVM Environment

Verify that CUBE_PVM_ENABLE=1 appears in the runtime configuration and that the kvm_pvm module is loaded. Once validated, proceed with normal CubeSandbox usage including template creation and sandbox execution.

Deploying CubeSandbox on Bare Metal

Bare-metal deployment follows a streamlined workflow that requires native KVM support but no kernel modifications.

Prerequisites

You need a root-privileged Linux machine (x86_64 or aarch64) with /dev/kvm available and Docker installed, as documented in docs/zh/guide/bare-metal-deploy.md lines 11-18.

Install CubeSandbox

For x86_64 hosts, run the one-click online installer:

curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | MIRROR=cn bash

For ARM64 hosts, download the ARM64 release tarball, extract it, and execute ./install.sh. The installer automatically detects the architecture as described in docs/zh/guide/bare-metal-deploy.md lines 39-58:

wget "<arm64-tarball-url>"
tar -xzf cube-sandbox-one-click-<version>-arm64.tar.gz
cd cube-sandbox-one-click-<version>-arm64
./install.sh

Post-Install Configuration

The installer automatically sets up the CubeMaster, Cubelet, network-agent, CubeShim, MySQL, Redis, and CubeProxy services. No extra kernel work is required because the host already supplies native KVM.

Create a Sandbox Template

Use cubemastercli to create templates using the same commands as PVM deployments. The underlying guest kernel differs automatically based on the host type:

cubemastercli template create --name <template-name> --image <image-path>

Key Architectural Differences

Kernel Layer: PVM requires an extra host kernel (opencloudos9.cubesandbox.pvm.host) that implements shadow-paging mechanisms, while bare-metal uses the stock kernel with native KVM.

Device Exposure: PVM creates a virtual KVM device (kvm_pvm) inside the host kernel, removing the need for /dev/kvm. Bare-metal relies on the physical /dev/kvm character device.

Supported Architectures: PVM is x86_64-only; ARM64 must run on bare-metal or cloud VMs that already expose native KVM, as noted in docs/zh/guide/pvm-deploy.md lines 28-31.

Deployment Code Examples

The following examples demonstrate the installation differences between PVM and bare-metal:

# ---------- PVM Deployment ----------

# Install PVM kernel (RPM example)

wget "<kernel-rpm-url>"
rpm -ivh --oldpackage kernel-*.rpm
grubby --set-default-index=<index>
reboot
modprobe kvm_pvm

# Install CubeSandbox with PVM enabled

CUBE_PVM_ENABLE=1 curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | bash

# ---------- Bare-Metal Deployment ----------

# Direct one-click install (x86_64)

curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | MIRROR=cn bash

# ARM64 manual install

wget "<arm64-tarball-url>"
tar -xzf cube-sandbox-one-click-<version>-arm64.tar.gz
cd cube-sandbox-one-click-<version>-arm64
./install.sh

Application code using the Python SDK remains identical across both deployment types:

import os
from e2b_code_interpreter import Sandbox

with Sandbox.create(template=os.getenv("CUBE_TEMPLATE_ID")) as sandbox:
    result = sandbox.run_code("print('Hello from Cube Sandbox')")
    print(result)

Summary

• PVM deployment requires installing a custom kernel (opencloudos9.cubesandbox.pvm.host) and loading the kvm_pvm module to enable virtualization without /dev/kvm.
• Bare-metal deployment uses native KVM directly and works on both x86_64 and ARM64 architectures.
• Set CUBE_PVM_ENABLE=1 when installing on cloud VMs to activate the PVM guest kernel.
• ARM64 servers must use bare-metal deployment as PVM does not support the ARM architecture.
• Both deployment types use the same cubemastercli commands and Python SDK after installation.

Frequently Asked Questions

What is the difference between PVM and bare-metal deployment in CubeSandbox?

PVM (Pagetable-based Virtual Machine) is a nested virtualization layer that runs on cloud VMs without requiring /dev/kvm access, using a special host kernel and the kvm_pvm module. Bare-metal deployment relies on the host's native KVM support through /dev/kvm and requires no kernel modifications.

Can I run CubeSandbox on ARM64 cloud instances?

No. According to docs/zh/guide/pvm-deploy.md, PVM is strictly x86_64-only. ARM64 deployments must run on bare-metal servers or cloud VMs that already expose native KVM via /dev/kvm, using the ARM64 release tarball and manual installation process.

Why does PVM deployment require a special kernel?

The PVM host kernel implements a shadow-paging mechanism that creates a virtual KVM device (kvm_pvm) inside the host kernel. This allows CubeSandbox to provide KVM-like isolation on cloud servers where nested virtualization is disabled, without exposing the physical /dev/kvm device to the host.

Do I need to modify my application code when switching between PVM and bare-metal?

No. The Python SDK and cubemastercli commands work identically on both host types. Only the installation process and environment configuration differ—specifically, setting CUBE_PVM_ENABLE=1 for PVM deployments and ensuring the correct kernel is installed.

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