# What Is CubeSandbox by Tencent Cloud? A Complete Technical Overview

> Discover CubeSandbox by Tencent Cloud, a powerful sandbox-as-a-service offering hardware-level isolation for AI workloads. Experience sub-60ms cold starts with minimal memory overhead.

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

---

**CubeSandbox by Tencent Cloud is an Apache-2.0-licensed sandbox-as-a-service that delivers hardware-level isolation for AI-agent workloads using RustVMM and KVM-based micro-VMs, achieving sub-60-millisecond cold starts with less than 5 MiB memory overhead.**

CubeSandbox by Tencent Cloud is an open-source project hosted in the **TencentCloud/CubeSandbox** repository that provides high-performance, hardware-isolated sandbox environments designed specifically for high-concurrency AI-agent serving. The system leverages micro-virtualization technology to eliminate container escape vectors while maintaining the density and speed required for modern cloud-native applications.

## Architecture and Core Components

The architecture consists of several tightly-coupled components as documented in [`docs/architecture/overview.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/architecture/overview.md).

### CubeAPI – The E2B-Compatible Gateway

**CubeAPI** serves as the high-throughput REST gateway written in Rust that manages incoming requests. According to the source code, this component is **E2B-compatible**, meaning existing E2B codebases can migrate to CubeSandbox by changing a single URL endpoint.

### CubeMaster – Cluster Orchestration

The **CubeMaster** component functions as the central cluster orchestrator. Implemented in the control plane, it receives API requests, schedules sandbox creation across the cluster, tracks node health, and manages template distribution. The template system logic is handled in [`CubeMaster/pkg/templatecenter/template_image.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/templatecenter/template_image.go), which transforms OCI images into reusable sandbox templates.

### CubeProxy and Cubelet – Node-Level Management

**CubeProxy** operates as a reverse-proxy implementing the E2B protocol to forward requests to appropriate sandbox instances. **Cubelet** runs on each node as a per-node agent managing the full sandbox lifecycle—creation, monitoring, and termination—as implemented in [`Cubelet/pkg/sandbox/manager.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/pkg/sandbox/manager.go).

### CubeVS and CubeEgress – Network Security

**CubeVS** provides **kernel-level network isolation** through an eBPF-based virtual switch. The implementation resides in [`CubeVS/src/ebpf/vswitch.c`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeVS/src/ebpf/vswitch.c), which manages per-sandbox traffic-token policies.

**CubeEgress** is an OpenResty (NGINX-Lua) gateway that enforces domain allow-lists, injects credentials dynamically, and records audit logs. The configuration in [`CubeEgress/conf/nginx.conf`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeEgress/conf/nginx.conf) ensures that external API keys never enter the sandbox environment directly; instead, CubeEgress injects them only when needed and logs every outbound request.

### CubeHypervisor and CubeShim – Virtualization Layer

The virtualization layer consists of **CubeHypervisor**, which runs KVM micro-VMs using RustVMM, and **CubeShim**, which implements the containerd **shim v2** API. This architecture allows sandboxes to appear as regular containers to the host runtime while maintaining hardware-level isolation.

## Key Capabilities and Performance Characteristics

CubeSandbox by Tencent Cloud delivers several critical capabilities for production AI-agent workloads:

- **Instant Startup**: Cold sandboxes boot in fewer than 60 milliseconds, enabling thousands of sandboxes per physical node.
- **Minimal Overhead**: Each sandbox consumes less than 5 MiB of memory overhead beyond the guest workload.
- **Hardware-Level Isolation**: Each sandbox runs its own guest kernel, eliminating shared-kernel escape vectors common in container environments.
- **Snapshot and Clone**: The CubeCoW (Copy-on-Write) engine records filesystem state at event granularity, supporting instantaneous cloning and rollback operations.
- **Template System**: OCI images convert to reusable sandbox templates distributed automatically across the cluster.
- **Web Console**: A built-in UI accessible on port 12088 displays cluster status, templates, active sandboxes, and live logs.

## Working with CubeSandbox: Code Examples

The project provides SDKs for Python, Go, and Node.js, enabling integration with existing AI-agent codebases.

### Creating Sandboxes with the Python SDK

The Python SDK offers E2B-compatible interfaces for sandbox management. As documented in [`sdk/python/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/python/README.md), you can instantiate sandboxes from standard container images:

```python
from cubesandbox import CubeClient

# The CubeSandbox API endpoint (E2B-compatible)

client = CubeClient(base_url="http://<control-node>:12088")

# Choose an official template (e.g., a minimal Ubuntu image)

template = "docker.io/library/ubuntu:22.04"

# Create a sandbox instance

sandbox = client.create_sandbox(template=template, cpu=2, memory_mb=512)

print(f"Sandbox ID: {sandbox.id}")
print(f"SSH endpoint: {sandbox.ssh_host}:{sandbox.ssh_port}")

```

### Executing Code via the Go SDK

The Go SDK supports programmatic code execution within isolated environments:

```go
import (
    "context"
    "fmt"
    "github.com/tencentcloud/cubesandbox-go/sdk"
)

func main() {
    client := sdk.NewClient("http://<control-node>:12088")
    sandbox, _ := client.CreateSandbox(context.Background(),
        sdk.Template("docker.io/library/python:3.11"), sdk.Resources{CPU: 2, MemMB: 256})

    // Run a short Python script
    out, _ := sandbox.Exec(context.Background(),
        sdk.ExecRequest{Cmd: []string{"python", "- <<'PY'\nprint('Hello from CubeSandbox')\nPY"}})

    fmt.Println(string(out.Stdout))
}

```

### REST API Quick Start

For direct integration, the REST API accepts standard HTTP requests:

```bash
curl -X POST http://<control-node>:12088/api/v1/sandboxes \
     -H "Content-Type: application/json" \
     -d '{"template":"docker.io/library/node:20","cpu":1,"memory_mb":256}'

```

## Deployment Targets and Licensing

CubeSandbox by Tencent Cloud is **Apache-2.0 licensed** and listed in the **CNCF Landscape**. The system targets both **bare-metal nodes** (via direct KVM access) and **cloud VMs** (using PVM deployment modes), providing flexibility for hybrid infrastructure strategies.

## Summary

- **CubeSandbox by Tencent Cloud** delivers sub-60-millisecond sandbox startup using RustVMM and KVM micro-VMs.
- The architecture separates concerns across **CubeAPI**, **CubeMaster**, **Cubelet**, and **CubeHypervisor** components.
- **CubeVS** (eBPF virtual switch) and **CubeEgress** (OpenResty gateway) provide kernel-level network isolation and credential vaulting.
- The system supports **E2B-compatible** SDKs for Python, Go, and Node.js, minimizing migration friction.
- Source files including [`CubeMaster/pkg/templatecenter/template_image.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/templatecenter/template_image.go), [`Cubelet/pkg/sandbox/manager.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/pkg/sandbox/manager.go), and [`CubeEgress/conf/nginx.conf`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeEgress/conf/nginx.conf) demonstrate the implementation of template management, lifecycle control, and security policies.

## Frequently Asked Questions

### What makes CubeSandbox different from Docker containers?

Unlike Docker containers which share the host kernel, CubeSandbox by Tencent Cloud runs each workload in its own guest kernel using KVM micro-VMs. This hardware-level isolation eliminates shared-kernel escape vectors while the optimized RustVMM implementation keeps overhead below 5 MiB and startup times under 60 milliseconds.

### Can I use existing E2B code with CubeSandbox?

Yes. The **CubeAPI** component is designed to be E2B-compatible, allowing existing codebases using the E2B SDK to switch to CubeSandbox by changing only the base URL endpoint. The system supports the same sandbox creation, execution, and lifecycle patterns as the original E2B specification.

### How does CubeSandbox handle network security and secrets?

Network traffic is controlled through **CubeVS**, an eBPF-based virtual switch providing kernel-level isolation, while **CubeEgress** acts as a credential vault and traffic inspector. External API keys never enter the sandbox; CubeEgress injects them only at request time and enforces domain allow-lists through OpenResty rules defined in [`CubeEgress/conf/nginx.conf`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeEgress/conf/nginx.conf).

### Where can I find the architecture documentation?

Comprehensive architecture details are located in [`docs/architecture/overview.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/architecture/overview.md) within the TencentCloud/CubeSandbox repository. The [`README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/README.md) file provides quick-start guidance, and specific implementation details for components like the template center ([`CubeMaster/pkg/templatecenter/template_image.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/templatecenter/template_image.go)) and node agent ([`Cubelet/pkg/sandbox/manager.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/pkg/sandbox/manager.go)) are available in their respective source directories.