TencentCloudCubeSandbox

4,377 stars292 forksRustNOASSERTIONUpdated 14h ago1viewdocs.cubesandbox.ai

CubeSandbox

CubeSandbox is a high-performance, open-source sandbox service built on RustVMM and KVM by Tencent Cloud. It delivers hardware-isolated MicroVM environments in under 60ms with less than 5MB of memory overhead per instance, enabling thousands of concurrent sandboxes on a single node. CubeSandbox is natively compatible with the E2B SDK — swap one environment variable to migrate from E2B Cloud without touching business logic. It ships as a multi-component service: CubeAPI (Rust/Axum REST gateway), CubeMaster (Go orchestrator), Cubelet (node-local scheduler), CubeShim (containerd Shim v2 adapter), CubeHypervisor (KVM MicroVM manager), and CubeVS (eBPF virtual switch). Tencent Cloud has validated CubeSandbox at production scale.

Showcase

Single-concurrency cold-start latency — sub-60ms — Single-concurrency sandbox cold-start latencyOpen

50-concurrency cold-start latency chart — 50-concurrency cold-start latency (avg 67ms, P99 137ms)Open

Base memory overhead chart — Base memory overhead across instance sizes (<5MB)Open

Single-concurrency creation benchmarkOpen

Features

E2B SDK drop-in compatibility — Replace E2B_API_URL to point at CubeSandbox; no SDK or business logic changes needed.
Sub-60ms cold start — Resource pool pre-provisioning and CoW snapshot cloning skip time-consuming boot entirely. Average end-to-end < 60ms; P99 < 150ms at 50 concurrent.
< 5MB per-instance memory overhead — Aggressively trimmed Rust runtime + CoW page sharing enables thousands of concurrent sandboxes on one node.
Dedicated Guest OS kernel per sandbox — Each MicroVM runs its own kernel, eliminating container escape risks from shared-kernel namespace isolation.
CubeVS eBPF network isolation — Three eBPF programs (from_cube, from_world, from_envoy) enforce per-sandbox SNAT, DNAT, LPM-trie egress policies, and ARP proxy entirely in kernel space.
OCI image → template pipeline — Import any container image, boot and snapshot it as a MicroVM template via cubemastercli tpl create-from-image.
Bring-your-own-image with envd — Layer envd daemon into any OCI image using the ghcr.io/tencentcloud/cubesandbox-base base image to satisfy the sandbox protocol.
Single-node + multi-node cluster — One-click install for single-node; add compute nodes (install-compute.sh) that auto-register to CubeMaster via the /internal/meta API.
Per-sandbox egress policy — Allow/deny lists specified as CIDR ranges; enforced in eBPF before packets reach userspace. Private address ranges always denied.
Port mapping — Expose sandbox services to external traffic via static NAT rules managed by the Go CubeVS control plane.
Pluggable authentication — Optional auth callback URL; Cube API Server forwards credentials to your service for each request.
Sandbox pause and resume — Pause a running sandbox and resume it later (used in OpenAI Agents SDK example).
Headless browser automation — Run Playwright/CDP-controlled headless Chromium inside a MicroVM sandbox.
Code interpreter — Run Python/Jupyter kernel inside a MicroVM; used with OpenAI Agents SDK for data analysis and pandas/matplotlib workloads.
RL training workloads — SWE-bench + mini-swe-agent example demonstrates multi-agent RL training in isolated sandboxes.
HTTPS + domain routing — CubeProxy + CoreDNS with mkcert TLS; subdomain format <port>-<sandbox_id>.cube.app.
Production-validated — Deployed at scale in Tencent Cloud production; 4 000+ GitHub stars in 18 days.

Live examples

Code Sandbox Quickstart — Create a sandbox, run Python code, execute shell commands, manage network policies via E2B SDK
Browser Sandbox (Playwright) — Headless Chromium inside a MicroVM, controlled remotely via CDP
OpenClaw Integration — AI agents executing code in isolated VM environments via OpenClaw skill
SWE-bench with mini-swe-agent — Automate SWE-bench coding tasks in isolated sandboxes with RL training
OpenAI Agents SDK Integration — Shell Agent with Pause/Resume; SWE-bench Django debugging with streaming + tracing
OpenAI Agents + Code Interpreter — Data-analysis Agent with pandas/matplotlib, Jupyter-kernel Code Interpreter with cross-turn state

Documentation

Quick start

# 1. (Skip on bare-metal) Boot a disposable QEMU dev VM
git clone https://github.com/tencentcloud/CubeSandbox.git
cd CubeSandbox/dev-env && ./prepare_image.sh && ./run_vm.sh
# In a second terminal: ./login.sh

# 2. One-click install inside the VM (or directly on bare-metal)
curl -sL https://github.com/tencentcloud/CubeSandbox/raw/master/deploy/one-click/online-install.sh | bash

# 3. Create a code-interpreter template from OCI image
cubemastercli tpl create-from-image \
  --image ccr.ccs.tencentyun.com/ags-image/sandbox-code:latest \
  --writable-layer-size 1G --expose-port 49999 --expose-port 49983 --probe 49999

# 4. Run code in an isolated MicroVM sandbox via E2B SDK
pip install e2b-code-interpreter
E2B_API_URL=http://127.0.0.1:3000 E2B_API_KEY=dummy python3 - <<'EOF'
import os
from e2b_code_interpreter import Sandbox
with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sb:
    print(sb.run_code("print('safely isolated!')"))
EOF

Documentation

18 pages indexed · 1,649 words

READMECubeSandbox — READMEgithub.com/TencentCloud/CubeSandbox/blob/master/README.md

Cube Sandbox is a high-performance, out-of-the-box secure sandbox service built on RustVMM and KVM. It supports both single-node deployment and can be easily scaled to a multi-node cluster. It is compatible with the E2B SDK, capable of creating a hardware-isolated sandbox environment with full service capabilities in under 60ms, while maintaining less than 5MB memory overhead.

Core Highlights:

Blazing-fast cold start (<60ms average, <150ms P99 at 50 concurrent)
High-density deployment: <5MB per-instance memory overhead via CoW + stripped runtime
True kernel-level isolation: each Agent runs with its own dedicated Guest OS kernel — eliminates container escape risks
Zero-cost migration: E2B SDK drop-in replacement, swap one URL environment variable
Network security: CubeVS eBPF-based inter-sandbox network isolation with egress filtering
Ready to use: one-click deployment, single-node and multi-node cluster
Production-validated: deployed at scale in Tencent Cloud environments

Benchmarks vs alternatives:

Metric	Docker	Traditional VM	CubeSandbox
Isolation	Low (Shared Kernel Namespaces)	High	Extreme (Dedicated Kernel + eBPF)
Boot Speed	200ms	Seconds	<60ms
Memory Overhead	Shared Kernel	High (Full OS)	<5MB
E2B SDK Compatible	No	No	Yes (Drop-in)

Introductiongithub.com/TencentCloud/CubeSandbox/blob/master/docs/guide/introduction.md
Cube Sandbox is a production-grade, multi-component security sandbox system designed for serverless computing and secure code execution environments. It implements a VM-based container isolation architecture using KVM hypervisor technology.

Key Advantages:
- Exceptional Performance: under 100ms delivery even at 100 concurrent sandboxes, <5MB memory overhead
- Secure by Design: hardware-level isolation + comprehensive network security policies in multi-tenant environments
- Ready Out of the Box: minimal deployment script, runs locally in minutes
- E2B Compatible: drop-in compatible with the E2B sandbox protocol — existing Agent applications gain stronger security without code changes
Quick Startgithub.com/TencentCloud/CubeSandbox/blob/master/docs/guide/quickstart.md
Get a fully functional Cube Sandbox running in four steps — no source build required.

Prerequisites: WSL 2 on Windows, x86_64 Linux physical machine, Linux VM with nested virtualization, or bare-metal Linux server. KVM must be available (/dev/kvm).

Step 1: Boot a disposable QEMU VM (skip on bare-metal):
```
git clone https://github.com/tencentcloud/CubeSandbox.git
cd CubeSandbox/dev-env && ./prepare_image.sh && ./run_vm.sh
# in a second terminal:
./login.sh
```
Step 2: One-click install:
```
curl -sL https://github.com/tencentcloud/CubeSandbox/raw/master/deploy/one-click/online-install.sh | bash
```
Installs: E2B-compatible REST API on port 3000, CubeMaster, Cubelet, network-agent, CubeShim, MySQL+Redis via Docker Compose, CubeProxy with TLS + CoreDNS.

Step 3: Create template from OCI image:
```
cubemastercli tpl create-from-image --image ccr.ccs.tencentyun.com/ags-image/sandbox-code:latest --writable-layer-size 1G --expose-port 49999 --expose-port 49983 --probe 49999
```
Step 4: Run code in isolated sandbox using E2B SDK:
```
from e2b_code_interpreter import Sandbox
with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    result = sandbox.run_code("print('Hello from Cube Sandbox, safely isolated!')")
```
Architecture Overviewgithub.com/TencentCloud/CubeSandbox/blob/master/docs/architecture/overview.md
Cube Sandbox follows a clear layered architecture. Key components:
1. CubeAPI: E2B-compatible REST API gateway (Rust/Axum). Switch from E2B Cloud to Cube Sandbox by replacing environment variables.
2. CubeMaster: Orchestration scheduler (Go). Receives E2B API requests and dispatches to Cubelets, handling resource scheduling and cluster state.
3. CubeProxy: Reverse proxy and request routing. Parses -. in Host header to forward SDK requests to sandbox.
4. Cubelet: Node-local scheduling (Go). Manages full lifecycle of all sandbox instances on a single node.
5. CubeVS: eBPF-based kernel-level packet forwarding, comprehensive network isolation and security policy enforcement.
6. CubeHypervisor & CubeShim: Virtualization layer. CubeHypervisor manages KVM MicroVMs; CubeShim implements containerd Shim v2 API to integrate sandboxes into the container runtime.
Network (CubeVS)github.com/TencentCloud/CubeSandbox/blob/master/docs/architecture/network.md
CubeVS is a purpose-built network virtualization layer for CubeSandbox composed of three eBPF programs, shared BPF maps, and a Go control-plane library.

Design goals:
- Point-to-point low latency: each sandbox communicates through a dedicated TAP device; no shared bridge
- Kernel-space policy enforcement: network policies evaluated in eBPF before any packet reaches userspace
- Scalable NAT: SNAT port allocation using lock-protected pool, avoiding iptables rule explosion
Three BPF programs:
- from_cube (mvmtap.bpf.c): TC ingress on each TAP device — SNAT, policy check, session creation, ARP proxy
- from_world (nodenic.bpf.c): TC ingress on host NIC — reverse NAT, port-mapping proxy
- from_envoy (localgw.bpf.c): TC egress on cube-dev — DNAT overlay traffic to sandbox IP
Network policy enforcement: per-sandbox LPM (Longest Prefix Match) tries for CIDR-based allow/deny rules. Always-denied: 10.0.0.0/8, 127.0.0.0/8, 169.254.0.0/16, 172.16.0.0/12, 192.168.0.0/16.

Port mapping: static NAT rule for inbound connections to services exposed by sandboxes. Go API: AddPortMapping, DelPortMapping, ListPortMapping, GetPortMapping.
Templates Overviewgithub.com/TencentCloud/CubeSandbox/blob/master/docs/guide/templates.md
A Template is the base image and configuration snapshot used to create Cube-Sandbox instances. Template Lifecycle:
1. Init: Build rootfs using Buildkit from a base OCI image + Dockerfile
2. Boot & Snapshot: Cold-boot the rootfs inside a MicroVM, wait for language environment to load, take memory snapshot
3. Deploy: Register rootfs + Snapshot into the system as an available Template enabling hot-start in tens-of-milliseconds
Templates enable the sub-60ms cold start time: the snapshot cloning avoids time-consuming initialization entirely.
Creating Templates from OCI Imagesgithub.com/TencentCloud/CubeSandbox/blob/master/docs/guide/tutorials/template-from-image.md
Create, monitor, and delete Cube-Sandbox templates from any standard OCI container image using cubemastercli.

A template is a pre-built, immutable rootfs snapshot. Pipeline: OCI Image → ext4 rootfs → Snapshot → Template READY.

CLI commands: cubemastercli tpl create-from-image --image --writable-layer-size 1G --expose-port --probe cubemastercli tpl watch --job-id cubemastercli tpl list cubemastercli tpl delete --template-id

The template must expose an HTTP health probe endpoint. Cube probes the container after boot to mark it READY.
Bring Your Own Image (envd)github.com/TencentCloud/CubeSandbox/blob/master/docs/guide/tutorials/bring-your-own-image.md
Use your own application/container image as a Cube-Sandbox template. Requirements: image must include envd daemon listening on :49983.

Fastest path: build FROM ghcr.io/tencentcloud/cubesandbox-base:2026.16 (Ubuntu 22.04 + envd preinstalled).

Alternative: inject envd from cubesandbox-base into an existing image:
```
COPY --from=ghcr.io/tencentcloud/cubesandbox-base:2026.16 /usr/bin/envd /usr/bin/envd
COPY --from=ghcr.io/tencentcloud/cubesandbox-base:2026.16 /usr/local/bin/cube-entrypoint.sh /usr/local/bin/cube-entrypoint.sh
```
envd capabilities: Template readiness probe (GET :49983/health), Sandbox.commands.run() (POST :49983/process), Sandbox.files.read/write() (POST :49983/files), Sandbox init (POST :49983/init).
Examplesgithub.com/TencentCloud/CubeSandbox/blob/master/docs/guide/tutorials/examples.md
Hands-on examples demonstrating various Cube Sandbox use cases:
- Code Sandbox Quickstart: create a sandbox, run Python code, shell commands, manage network policies via E2B SDK
- Browser Sandbox (Playwright): run headless Chromium inside a MicroVM, control remotely via CDP
- OpenClaw Integration: deploy Cube Sandbox + configure OpenClaw skill for AI agents to execute code in isolated VM environments
- SWE-bench with mini-swe-agent: automate SWE-bench coding tasks in isolated sandboxes, multi-model support and RL training vision
- OpenAI Agents SDK Integration: wire OpenAI Agents SDK E2BSandboxClient to Cube Sandbox; Shell Agent with Pause/Resume; SWE-bench Django debugging agent with streaming + tracing
- OpenAI Agents + Code Interpreter: data-analysis Agent running pandas/matplotlib inside Cube Sandbox, Jupyter-kernel Code Interpreter with cross-turn state and auto image capture
Multi-Node Cluster Deploymentgithub.com/TencentCloud/CubeSandbox/blob/master/docs/guide/multi-node-deploy.md
Expand a single-node Cube Sandbox deployment into a multi-node cluster by adding compute nodes.

Architecture: Control Node (CubeMaster + CubeAPI + CubeProxy + CoreDNS + MySQL + Redis + Cubelet + network-agent) + N Compute Nodes (Cubelet + network-agent each).

Add a compute node:
```
ONE_CLICK_DEPLOY_ROLE=compute
CUBE_SANDBOX_NODE_IP=<node-ip>
ONE_CLICK_CONTROL_PLANE_IP=<control-ip>
sudo ./install-compute.sh
```
Compute nodes auto-register to CubeMaster via /internal/meta API. No shared bridge — each sandbox has its own network isolation via CubeVS eBPF.
Authenticationgithub.com/TencentCloud/CubeSandbox/blob/master/docs/guide/authentication.md
By default, Cube API Server allows all requests without authentication. Enable with --auth-callback-url flag. When configured, every incoming request is validated by forwarding the credential header to your callback service.

Supported credential formats: Authorization: Bearer and X-API-Key header. The E2B SDK passes E2B_API_KEY as Authorization: Bearer.

Callback contract: Cube API Server POSTs to your callback URL with credential headers. HTTP 200 → allow, non-200 → 401 Unauthorized.
Self-Build Deploymentgithub.com/TencentCloud/CubeSandbox/blob/master/docs/guide/self-build-deploy.md
Build Cube Sandbox from source and deploy on a single bare-metal server. Hardware requirements: physical/bare-metal x86_64 server, KVM enabled (/dev/kvm), 8+ CPU cores, 16+ GB RAM.

Software stack installed: E2B-compatible REST API (port 3000), CubeMaster, Cubelet, network-agent, CubeShim as host processes, MySQL + Redis via Docker Compose, CubeProxy with TLS (mkcert) + CoreDNS for cube.app domain routing.

Components built from source: CubeAPI (Rust/Axum), CubeMaster (Go/Gin/GORM), Cubelet (Go/gRPC), CubeShim (Rust/containerd-shim-v2), CubeHypervisor (Rust/RustVMM), network-agent (Go/cilium-eBPF).
Development Environment (QEMU VM)github.com/TencentCloud/CubeSandbox/blob/master/docs/guide/dev-environment.md
Run Cube Sandbox in a disposable QEMU/KVM VM for development without a bare-metal server. Uses OpenCloudOS 9 as the guest OS.

Scripts: prepare_image.sh (one-off: download and init runtime image), run_vm.sh (boot VM), login.sh (SSH into VM as root).

Requirements on host: qemu, qemu-img, ripgrep. The VM uses nested virtualization — works on WSL 2 (Windows 11 22H2+), VMware with VT-x passthrough, or bare-metal.

Purpose: isolate Cube Sandbox installation from host so the host stays clean. All subsequent installation happens inside this disposable VM.
Template Inspection and Request Previewgithub.com/TencentCloud/CubeSandbox/blob/master/docs/guide/template-inspection-and-preview.md
Inspect template build status and preview the effective API request before creating sandboxes.

cubemastercli commands for template management:
- tpl create-from-image: create template from OCI image (async)
- tpl watch: monitor build progress by job ID
- tpl list: list all templates with status (BUILDING, READY, FAILED)
- tpl inspect: view template configuration and probe settings
- tpl preview: preview the effective sandbox creation request for a template
HTTPS & Domain Resolutiongithub.com/TencentCloud/CubeSandbox/blob/master/docs/guide/https-and-domain.md
Cube Sandbox uses CubeProxy + CoreDNS for TLS and domain routing. The installer bundles mkcert for local CA generation.

Domain format: -.cube.app — CubeProxy parses the subdomain to route SDK requests to the correct sandbox instance.

For production deployments, replace the mkcert CA with your organization's CA or a public CA. HTTPS is required for the E2B SDK when using Bearer token authentication.
Connect to an Existing Cube Clustergithub.com/TencentCloud/CubeSandbox/blob/master/docs/guide/connect/existing/cluster.md
Connect to an already-running Cube Sandbox cluster rather than deploying a fresh one.

Set environment variables to point at the existing cluster: export CUBEMASTER_ADDR=:8089 export E2B_API_URL=http://:3000 export E2B_API_KEY=

Then create templates and run sandboxes as normal. Useful for shared team environments or Tencent Cloud hosted Cube Sandbox endpoints.
CubeSandbox Design Languagegithub.com/TencentCloud/CubeSandbox/blob/master/docs/design-language.md
Cube Console design system for the CubeSandbox management UI. Target audience: AI agent developers, platform operators, SREs.

Design principles: Millisecond-Native (every metric in monospace, live stopwatch on sandbox creation), Glass & Grid (deep black/midnight-blue with frosted-glass layers, CRT scanline accents), Operator-First (keyboard-driveable, high density, dark-mode only).

Color tokens: bg-0 #070B10 (page), primary #5B8DEF (CTAs), accent-cyan #22D3EE (running/live), accent-violet #A78BFA (templates/snapshots), accent-amber #F59E0B (paused).

Status states: Running (breathing pulse 1.6s), Creating (rotating stroke), Paused (static), Error (shake). All meet WCAG AA contrast.
Documentation Indexgithub.com/TencentCloud/CubeSandbox/blob/master/docs/index.md
CubeSandbox documentation home. Sections: Guide (Introduction, Quick Start, Self-Build Deployment, Multi-Node Cluster Deployment, Templates, HTTPS & Domain, Authentication, Development Environment), Architecture (Overview, Network/CubeVS), Tutorials (Examples, Creating Templates from OCI Images, Bring Your Own Image).

CubeSandbox

Showcase

Features

Live examples

Documentation

Quick start

Tags

Documentation