How to Install CubeSandbox on Linux: A Complete Setup Guide

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 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. 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:

# 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:

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. 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:

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:

# 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, 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:

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 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 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.

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