What Is CubeSandbox by Tencent Cloud? A Complete Technical Overview

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.

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

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, 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 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, you can instantiate sandboxes from standard container images:

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:

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:

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, Cubelet/pkg/sandbox/manager.go, and 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.

Where can I find the architecture documentation?

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

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