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

> Learn how to use CubeSandbox for secure code execution. This guide covers provisioning hosts, creating OCI templates, and running code in dedicated micro VMs with its E2B-compatible REST API.

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

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```bash
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```bash
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:

```bash
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:

```python
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.