# How to Install CubeSandbox on Linux: A Complete Setup Guide

> Install CubeSandbox on Linux with our guide. Learn to prepare your KVM host, set up XFS, and run the one-click installer for a complete control and data plane stack.

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

---

**Install CubeSandbox by preparing a Linux host with KVM and an XFS filesystem, optionally installing the PVM host kernel for cloud environments, and executing the one-click installer from [`deploy/one-click/online-install.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/deploy/one-click/online-install.sh) that deploys the complete control plane and data plane stack.**

CubeSandbox is a high-performance, hardware-isolated sandbox service for AI agents, developed by TencentCloud. The installation process involves three distinct phases: host preparation, kernel configuration (if required), and automated service deployment via the official installer script. This guide walks through each phase using the exact implementation details found in the repository source code.

## Prerequisites

### System Requirements

Before you install CubeSandbox, ensure your host meets the following specifications:

- **Operating System**: Linux distribution with `glibc ≥ 2.31` (Ubuntu 20.04+, Debian 11+, or OpenCloudOS 9)
- **Memory**: At least **8 GB RAM**
- **Filesystem**: XFS filesystem mounted at `/data/cubelet` (required for the **CubeCoW** storage engine, which uses XFS reflinks for O(1) snapshot operations)
- **Virtualization**: Access to `/dev/kvm` (or capability to install the PVM host kernel)

## Installation Steps

### Step 1 – Prepare the Host Environment

The CubeSandbox installer validates your environment against strict requirements defined in [`deploy/one-click/online-install.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/deploy/one-click/online-install.sh). First, verify that your system runs a compatible Linux distribution with `glibc ≥ 2.31`. Next, ensure an XFS partition is mounted at `/data/cubelet`, as the **Cubelet** component relies on this path for volume management and snapshot operations via **CubeCoW**.

If running on bare metal or a VM with exposed KVM, ensure the `kvm` module is loaded. Cloud VMs lacking `/dev/kvm` require the PVM host kernel installation described in the next step.

### Step 2 – Install the PVM Host Kernel (Cloud VMs)

If your cloud provider does not expose `/dev/kvm`, you must install the custom PVM host kernel to enable nested virtualization.

Download the appropriate kernel package from the GitHub Releases page (e.g., `kernel-*opencloudos9.cubesandbox.pvm.host*.x86_64.rpm` for RPM-based systems or the corresponding DEB package).

Install the package using your system’s package manager:

```bash

# For RPM-based systems

rpm -ivh kernel-*opencloudos9.cubesandbox.pvm.host*.x86_64.rpm

# For DEB-based systems

dpkg -i kernel-*cubesandbox.pvm.host*.deb

```

Set the new kernel as the default boot entry using `grubby` (RPM) or by editing `/etc/default/grub` (DEB), then reboot the system. After reboot, verify the installation by checking that `uname -r` contains `opencloudos9.cubesandbox.pvm.host` and that the `kvm_pvm` module is loaded:

```bash
uname -r | grep opencloudos9.cubesandbox.pvm.host
lsmod | grep kvm

```

### Step 3 – Run the One-Click Installer

Execute the online installer script located at [`deploy/one-click/online-install.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/deploy/one-click/online-install.sh). The script performs pre-flight checks for glibc version, root privileges, required binaries, KVM availability, memory capacity, and XFS filesystem presence before downloading the binary bundle.

Run the installer as root, enabling PVM mode if you installed the custom kernel:

```bash
curl -sL https://github.com/tencentcloud/CubeSandbox/raw/master/deploy/one-click/online-install.sh \
  | CUBE_PVM_ENABLE=1 bash

```

The installer automatically starts the following services: **CubeMaster**, **Cubelet**, **CubeShim**, **CubeHypervisor**, **CubeEgress**, **CubeProxy**, plus supporting MySQL and Redis containers. It also generates the default TLS root CA using `mkcert` and configures the `cube.app` domain for sandbox access.

## Verify the Installation

Confirm successful deployment by checking the API health endpoint and web interface:

```bash

# Verify API is listening on port 3000

curl -s http://localhost:3000/health | jq .

# Verify the web UI on port 12088

curl -I http://localhost:12088

# List running infrastructure containers

docker ps

```

A successful response indicates that the **CubeAPI** (Rust/Axum), **CubeMaster** (Go), and node-level **Cubelet** (Go) are operational.

## Architecture Overview

Understanding the component architecture explains why the installer configures specific services. CubeSandbox separates the **control plane** from the **data plane**:

- **Control Plane**: **CubeAPI** exposes an E2B-compatible REST API, while **CubeMaster** schedules sandboxes and publishes lifecycle events to Redis
- **Data Plane**: **Cubelet** pulls images via containerd and manages **CubeCoW** (Rust) for storage snapshots; **CubeShim** (Rust) bridges containerd’s Shim v2 to **CubeHypervisor** (RustVMM + KVM); **CubeEgress** (OpenResty) enforces Layer 7 egress policies

This architecture requires the coordinated startup sequence performed by [`online-install.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/online-install.sh), ensuring the XFS-based storage layer at `/data/cubelet` is ready before the Cubelet service attempts to initialize **CubeCoW** pools.

## Deploy Your First Sandbox

After installation, use the Python SDK (available via `pip install cubesandbox` and located in `sdk/python`) to create a template and launch a sandbox:

```python
import cubesandbox

client = cubesandbox.Client(base_url="http://localhost:3000")

# Create a template from a standard Python image

template = client.create_template(
    name="python-3.11",
    image="docker.io/library/python:3.11-slim"
)

# Launch a sandbox instance

sandbox = client.create_sandbox(template_id=template.id)
print(f"Sandbox accessible at https://{sandbox.id}.cube.app")

```

The SDK communicates with your local **CubeAPI** instance to orchestrate sandbox creation through the control plane.

## Summary

- **Prepare the host** with Linux (glibc ≥ 2.31), 8GB RAM, and XFS mounted at `/data/cubelet` for the CubeCoW engine
- **Install the PVM kernel** only if `/dev/kvm` is unavailable, using packages from GitHub Releases and verifying with `uname -r` and `lsmod`
- **Execute the installer** from [`deploy/one-click/online-install.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/deploy/one-click/online-install.sh) to deploy CubeMaster, Cubelet, CubeHypervisor, and supporting services
- **Verify deployment** via `curl http://localhost:3000/health` and access the web UI at port 12088

## Frequently Asked Questions

### What are the minimum system requirements to install CubeSandbox?

You need a Linux host running `glibc ≥ 2.31` (Ubuntu 20.04+, Debian 11+, or OpenCloudOS 9), at least 8GB of RAM, and an XFS filesystem mounted at `/data/cubelet`. The XFS requirement is mandatory because the CubeCoW storage engine relies on XFS reflinks for instantaneous snapshot operations.

### Do I need to install a custom kernel to run CubeSandbox?

Only if your environment lacks access to `/dev/kvm`, which is common in cloud VMs. In such cases, download and install the PVM host kernel from the GitHub Releases page (packages named `kernel-*opencloudos9.cubesandbox.pvm.host*`), configure your bootloader, and verify the `kvm_pvm` module loads after reboot.

### Which services does the one-click installer start?

The [`online-install.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/online-install.sh) script starts the complete CubeSandbox stack: **CubeMaster**, **Cubelet**, **CubeShim**, **CubeHypervisor**, **CubeEgress**, **CubeProxy**, plus infrastructure containers for MySQL and Redis. It also initializes the TLS root CA and configures the `cube.app` domain for sandbox networking.

### How do I verify that CubeSandbox installed correctly?

Check the API health endpoint with `curl http://localhost:3000/health` and verify the web UI responds on port 12088. Additionally, run `docker ps` to confirm that MySQL, Redis, and CubeSandbox service containers are running. The `kvm` or `kvm_pvm` kernel module should also appear in `lsmod` output.