Bare-Metal / Physical Machine Deployment
Use case: You already have an x86_64 or aarch64 (ARM64) Linux machine with KVM support (
/dev/kvmavailable), such as a physical machine, bare-metal server, or a cloud VM with nested virtualization enabled.If you're on an ordinary cloud VM without
/dev/kvm, you don't need bare-metal — use PVM to enable KVM on standard cloud VMs, see Quick Start.
Production Use
If you plan to use Cube Sandbox in a production environment, please refer to the Network Hardening guide to secure your deployment before exposing services to untrusted networks.
Prerequisites
- x86_64 or aarch64 (ARM64) Linux machine
/dev/kvmpresent and read/writable (ls -la /dev/kvm)- Root access
- Docker installed and running
- Internet access (for downloading release packages and Docker images)
- RAM ≥ 8 GB, free disk ≥ 50 GB
Run all commands as root
Every command in this guide must be executed as root. Switch to root first:
sudo su rootStep 1: Install
x86_64 (AMD64)
Run as root:
curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | MIRROR=cn bashARM64 (aarch64) Hosts
online-install.sh ARM64 support coming soon
The online-install.sh one-command installer currently auto-discovers x86_64 packages only. ARM64 support in online-install.sh will be available in an upcoming release. For now, ARM64 users should follow the manual steps below.
Step 1: Go to the release page for your region, find the latest release that includes ARM64 assets, and download the cube-sandbox-one-click-*-arm64.tar.gz package:
| Platform | Release Page |
|---|---|
| GitHub | TencentCloud/CubeSandbox/releases |
| CNB (China) | CubeSandbox/CubeSandbox/-/releases |
Step 2: Extract and run the installer:
# Replace <version> with the actual version you downloaded (e.g. v0.5.0-rc3)
tar -xzf cube-sandbox-one-click-<version>-arm64.tar.gz
cd cube-sandbox-one-click-<version>-arm64
chmod +x install.sh
./install.shWhat gets installed
- E2B-compatible REST API listening on port
3000 - CubeMaster, Cubelet with embedded network runtime, and CubeShim running as host processes
- MySQL and Redis managed via Docker Compose
- CubeProxy providing TLS (mkcert) and CoreDNS domain routing (
cube.app)
ARM64 hosts without a guest PMU
On some aarch64 hosts — older kernels, nested-virtualization setups, or certain ARM cores — KVM does not expose a guest PMUv3. MicroVMs still boot on these hosts; the hypervisor initializes the vCPU without a PMU and the guest simply sees no hardware performance counters. No action is needed.
Step 2: Create a Template
After installation, create a code interpreter template using a pre-built image:
cubemastercli tpl create-from-image \
--image cube-sandbox-cn.tencentcloudcr.com/cube-sandbox/sandbox-code:latest \
--writable-layer-size 1G \
--expose-port 49999 \
--expose-port 49983 \
--probe 49999Registry note: For users in China, use
cube-sandbox-cn.tencentcloudcr.com/cube-sandbox/sandbox-code:latest. For international access, usecube-sandbox-int.tencentcloudcr.com/cube-sandbox/sandbox-code:latest.
Monitor the build progress:
cubemastercli tpl watch --job-id <job_id>⚠️ Note: the image is large; downloading, extracting, and building the template may take a while. Please be patient.
Wait for the command above to finish — the template status should become READY.
Take note of the template ID (template_id) from the output; you'll need it in the next step.
For a full walkthrough and additional parameters, see Create Templates from OCI Image.
Step 3: Run Your First Agent Code
Install Python SDK:
yum install -y python3 python3-pip
pip config set global.index-url https://mirrors.ustc.edu.cn/pypi/simple
pip install e2b-code-interpreterSet environment variables:
export E2B_API_URL="http://127.0.0.1:3000"
export E2B_API_KEY="e2b_000000"
export CUBE_TEMPLATE_ID="<your-template-id>"
export SSL_CERT_FILE="/root/.local/share/mkcert/rootCA.pem"| Variable | Description |
|---|---|
E2B_API_URL | Points the E2B SDK to your local Cube Sandbox instead of the E2B cloud service |
E2B_API_KEY | Required by the SDK; use any placeholder string for local deployment |
CUBE_TEMPLATE_ID | The template ID obtained in Step 2 |
SSL_CERT_FILE | Path to the mkcert CA root certificate, required for sandbox HTTPS connections |
Run code in an isolated sandbox:
import os
from e2b_code_interpreter import Sandbox # Use the E2B SDK directly!
# CubeSandbox seamlessly handles all requests under the hood
with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
result = sandbox.run_code("print('Hello from Cube Sandbox, safely isolated!')")
print(result)For more end-to-end examples, see Examples.
Uninstall
The one-click installation includes a complete uninstall script. It stops and removes CubeSandbox services, containers, volumes, network configuration, runtime data, and logs. Existing templates, sandboxes, and snapshots are also deleted, so back up anything you need first.
sudo /usr/local/services/cubetoolbox/scripts/one-click/uninstall.shAfter uninstalling, check the host for remaining CubeSandbox resources:
sudo /usr/local/services/cubetoolbox/scripts/one-click/uninstall.sh checkOnce the check passes and you no longer need the uninstall script or installed bundle, remove the preserved toolbox directory manually:
sudo rm -rf /usr/local/services/cubetoolboxThe uninstall script does not delete Cube-related Docker images. To remove them as well, follow the command printed by the script.
Next Steps
- Create Templates from OCI Image — Customize sandbox environments
- Multi-Node Cluster — Scale across multiple machines
- HTTPS & Domain Resolution — TLS configuration options
- Authentication — Enable API authentication