How to Use CubeSandbox for Code Execution: A Complete Guide to Secure Sandboxing

CubeSandbox is a high-performance, hardware-isolated sandbox service built on RustVMM, KVM, and eBPF that exposes an E2B-compatible REST API, enabling you to provision a host, install with a one-click script, create templates from OCI images, and execute arbitrary code securely in dedicated micro-VMs.

TencentCloud/CubeSandbox provides a production-ready solution for running untrusted code with hardware-level isolation. Unlike container-based sandboxes, each execution environment runs in its own KVM micro-VM with a dedicated kernel, eliminating namespace escape risks while maintaining sub-100ms startup times through the CubeCoW copy-on-write engine implemented in Cubelet/storage/*.

Prerequisites and Provisioning

Before you can use CubeSandbox for code execution, you must provision infrastructure that supports hardware virtualization.

Enable KVM and PVM Support

CubeSandbox requires either a bare-metal host with native KVM support or a cloud VM running the PVM (Para-Virtualized Monitor) kernel. The PVM kernel enables nested virtualization on standard cloud instances, allowing the sandbox to create KVM micro-VMs. Consult the docs/guide/quickstart.md file for exact OS requirements and kernel parameters.

Ensure your host meets the following criteria:

• x86_64 architecture
• KVM acceleration enabled in the kernel
• Sufficient disk space for the CubeCoW storage layer (managed by Cubelet/storage/*)

Installing CubeSandbox Components

Once your host is provisioned, deploy the complete CubeSandbox stack using the automated installer.

Run the One-Click Installer

The deploy/one-click/online-install.sh script automates the deployment of all required services. As implemented in TencentCloud/CubeSandbox, this installs the CubeAPI gateway, CubeMaster orchestrator, Cubelet node agent, CubeVS virtual switch, CubeEgress proxy, and supporting infrastructure including MySQL, Redis, and CubeProxy.

Execute the installation as root:

curl -sL https://github.com/tencentcloud/CubeSandbox/raw/master/deploy/one-click/online-install.sh \
    | CUBE_PVM_ENABLE=1 bash

The CUBE_PVM_ENABLE=1 environment variable instructs the installer to configure the system for PVM-based virtualization. The CubeMaster/README.md describes how these components interact to schedule and isolate sandboxes across multi-node clusters.

Creating Sandbox Templates

Templates define the base filesystem and network configuration for your execution environments. According to the source code in docs/guide/templates.md, templates consist of a read-only OCI image layer plus a writable overlay.

Build Templates from OCI Images

Use the cubemastercli command-line tool to create a template from a pre-built image. The following example uses the sandbox-code:latest image and exposes ports for external services:

cubemastercli tpl create-from-image \
    --image cube-sandbox-int.tencentcloudcr.com/cube-sandbox/sandbox-code:latest \
    --writable-layer-size 1G \
    --expose-port 49999 \
    --expose-port 49983 \
    --probe 49999

This command stores the template definition in the CubeCoW storage engine (Cubelet/storage/*), which handles copy-on-write snapshots and rapid cloning. The command returns a template ID required for the next step.

Executing Code via the E2B API

CubeSandbox exposes an E2B-compatible REST API through the CubeAPI gateway, allowing integration with the e2b-code-interpreter SDK.

Configure the Python SDK

Install the official Python package and configure environment variables to point to your local CubeSandbox endpoint:

pip install e2b-code-interpreter

export E2B_API_URL="http://127.0.0.1:3000"
export E2B_API_KEY="e2b_000000"               # Placeholder for local development

export CUBE_TEMPLATE_ID="<your-template-id>"
export SSL_CERT_FILE="/root/.local/share/mkcert/rootCA.pem"

The E2B_API_URL directs the SDK to the CubeProxy (CubeProxy/Dockerfile), which routes requests to the appropriate sandbox instance.

Run Isolated Code

Create a sandbox instance from your template and execute Python code:

import os
from e2b_code_interpreter import Sandbox

with Sandbox.create(template=os.getenv("CUBE_TEMPLATE_ID")) as s:
    result = s.run_code("print('Hello from Cube Sandbox!')")
    print(result)

The SDK communicates with CubeSandbox through the E2B-compatible API, handling sandbox lifecycle management, streaming logs, and returning execution results. Each Sandbox.create() invocation spins up a fresh KVM micro-VM based on your template.

Security Architecture and Network Isolation

Understanding the security model is critical when you use CubeSandbox for code execution in production AI workloads.

Hardware-Level Isolation

Because each sandbox runs in its own KVM micro-VM with a dedicated kernel, isolation occurs at the hardware level rather than the process level. This architecture prevents Docker-style namespace escapes, as implemented in the CubeMaster and Cubelet source trees.

Network Policies and Egress Control

CubeVS provides eBPF-based virtual switching and network policies defined in the CubeVS source directory. CubeEgress, implemented via OpenResty Lua scripts in CubeProxy/lua/, enforces domain allowlists, injects credentials securely from vaults, and logs all outbound traffic for audit purposes. Configure these policies via docs/guide/security-proxy.md to restrict Internet access and prevent data exfiltration.

Summary

• Provision a host with KVM or PVM support to enable hardware virtualization.
• Install all components using deploy/one-click/online-install.sh, which deploys CubeMaster, Cubelet, CubeAPI, and supporting services.
• Create sandbox templates using cubemastercli tpl create-from-image, specifying OCI images and writable layer sizes; the CubeCoW engine in Cubelet/storage/* handles snapshotting.
• Execute code via the E2B-compatible Python SDK by pointing E2B_API_URL to your local CubeSandbox instance and calling Sandbox.create() with your template ID.
• Secure your deployment using CubeVS eBPF policies and CubeEgress filtering for hardware-isolated, auditable code execution.

Frequently Asked Questions

What is CubeSandbox and how does it differ from Docker containers?

CubeSandbox is a sandbox service built on RustVMM, KVM, and eBPF that runs each workload in a dedicated micro-VM with its own kernel. Unlike Docker containers, which share the host kernel and rely on namespace isolation, CubeSandbox provides hardware-level isolation that prevents kernel exploits and namespace escapes. This makes it suitable for executing untrusted AI-generated code safely.

How do I create custom sandbox templates?

You create templates using the cubemastercli CLI tool, typically with the tpl create-from-image subcommand pointing to an OCI-compliant container image. As documented in docs/guide/templates.md, you can specify writable layer sizes, exposed ports, and health check probes. The template is stored in the CubeCoW engine, enabling sub-100ms cloning and state rollback.

What ports need to be exposed for sandbox services?

The default template creation exposes ports 49999 (for health probes) and 49983 (for secondary services), though these are configurable via the --expose-port flag in cubemastercli. The CubeAPI gateway typically listens on port 3000 for E2B API requests, while internal communication between CubeMaster and Cubelet uses dedicated service ports configured during installation.

How does CubeSandbox secure outbound network traffic?

Outbound traffic is controlled by CubeEgress, an L7 proxy implemented in CubeProxy/lua/ that enforces domain allowlists, injects credentials securely without exposing them to the sandbox, and logs all connections for audit. Additionally, CubeVS applies eBPF-based network policies at the kernel level, ensuring that even if application-layer controls are bypassed, the micro-VM cannot communicate with unauthorized endpoints.

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