# How to Integrate CubeSandbox into Your Project: A Complete Developer Guide

> Integrate CubeSandbox into your project easily by setting E2B_API_URL. Enable hardware-isolated sandbox execution without code changes. Get the complete developer guide.

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

---

**You can integrate CubeSandbox into any existing application by setting the `E2B_API_URL` environment variable to your control node endpoint, enabling hardware-isolated sandbox execution without modifying your codebase.**

CubeSandbox is a fast, secure, and lightweight sandbox service designed to execute untrusted code in isolated micro-VMs. Because the platform follows the **E2B SDK** contract, you can integrate it into AI agents, browser automation tools, or RL training pipelines by simply swapping the API endpoint. Below is the complete integration path based on the TencentCloud/CubeSandbox source code architecture.

## Architecture Overview

CubeSandbox consists of six core components that work together to provide secure code execution:

- **CubeAPI**: High‑throughput REST gateway written in Rust that receives all sandbox requests. See the request handling logic in [`CubeAPI/src/state.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeAPI/src/state.rs).
- **CubeMaster**: Orchestrates clusters, schedules sandbox creation, and tracks resource allocation across nodes.
- **Cubelet**: Runs on each compute node to manage the lifecycle of individual sandbox instances. Storage backends are implemented in `Cubelet/storage/*.go`.
- **CubeVS**: eBPF‑based virtual switch enforcing network isolation and security policies.
- **CubeEgress**: OpenResty proxy providing L7 domain filtering, credential injection, and audit logging. Configuration scripts reside in `CubeProxy/lua/*.lua`.
- **CubeHypervisor / CubeShim**: KVM‑based micro-VMs via Cloud‑Hypervisor with containerd‑shim API compatibility.

## Step-by-Step Integration Process

### Provision the Control Node

Start by provisioning a control node on bare‑metal hardware, a PVM cloud VM, or using the provided development VM. This node hosts the web UI and API gateway. Consult the [`docs/guide/quickstart.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/quickstart.md) file for environment-specific requirements and resource recommendations.

### Install the CubeSandbox Service

Deploy the platform using either the [`install.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/install.sh) script for standalone deployments or the Helm chart for Kubernetes clusters. The installer automatically creates a default configuration and exposes the web UI on port **12088**.

```bash

# Example using the install script

curl -fsSL https://raw.githubusercontent.com/TencentCloud/CubeSandbox/master/install.sh | bash

```

### Create Your First Sandbox Template

Convert an **OCI image** (such as `docker.io/library/python:3.11`) into a CubeSandbox template using the CLI:

```bash
cubesandbox template create python-3.11 --image docker.io/library/python:3.11

```

Alternatively, browse the **Template Store** in the web UI (port 12088) to select from official presets. Template management details are documented in [`docs/guide/templates.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/templates.md).

### Configure the SDK Endpoint

Point your existing E2B‑compatible code to the CubeSandbox control plane by setting a single environment variable:

```bash
export E2B_API_URL="http://<control-node-ip>:12088"

```

No source‑code changes are required for existing E2B integrations.

## SDK Implementation Examples

### Python SDK Integration

Install the official Python SDK from PyPI and execute code in an isolated sandbox:

```python
import os
from cubesandbox import Sandbox

# Point to your CubeSandbox deployment

os.environ["E2B_API_URL"] = "http://<control-node-ip>:12088"

# Create a sandbox from a template

sandbox = await Sandbox.create(template="python-3.11")

# Execute arbitrary code safely

result = await sandbox.exec(
    ["python", "- <<'PY'\nprint('Hello from CubeSandbox!')\nPY"]
)

print("STDOUT:", result.stdout)
print("STDERR:", result.stderr)

# Clean up resources

await sandbox.close()

```

### Node.js SDK Integration

The Node.js SDK follows the same pattern. Reference the implementation details in [`sdk/node/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/node/README.md):

```javascript
import { Sandbox } from "cubesandbox";

process.env.E2B_API_URL = "http://<control-node-ip>:12088";

(async () => {
  const sandbox = await Sandbox.create({ template: "node-18" });
  const { stdout } = await sandbox.exec(["node", "-e", "console.log('Hello CubeSandbox')"]);
  console.log("Result:", stdout);
  await sandbox.close();
})();

```

## Key Configuration Files and Source References

Understanding these specific files helps customize and troubleshoot your integration:

| File Path | Purpose |
|-----------|---------|
| [`sdk/python/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/python/README.md) | Python client quick‑start and authentication patterns |
| [`sdk/node/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/node/README.md) | Node.js usage examples and async patterns |
| [`docs/guide/quickstart.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/quickstart.md) | Full installation tutorial and first sandbox creation |
| [`docs/guide/templates.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/templates.md) | OCI image conversion and template lifecycle management |
| [`docs/guide/security-proxy.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/security-proxy.md) | Credential vault configuration and egress policy setup |
| [`CubeAPI/src/state.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeAPI/src/state.rs) | Core API request handling and state management |
| `Cubelet/storage/*.go` | OverlayFS and Copy‑on‑Write snapshot implementations |
| `CubeProxy/lua/*.lua` | Reverse‑proxy routing rules and health check configurations |

## Production Security Considerations

Before deploying to production, configure the **CubeEgress** proxy and **CubeVS** virtual switch to enforce network policies. The [`docs/guide/security-proxy.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/security-proxy.md) file documents how to set up domain filtering, credential injection, and audit logging for egress traffic. These components provide hardware‑level isolation with sub‑60 ms startup times and snapshot/clone capabilities.

## Summary

- **CubeSandbox** provides hardware‑isolated sandbox execution through KVM‑based micro‑VMs.
- **Integration requires only** changing the `E2B_API_URL` environment variable to point at your control node (port 12088).
- **Install** the service via [`install.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/install.sh) or Helm, then create templates using `cubesandbox template create`.
- **SDKs** are available for Python, Node.js, Go, and Rust, all following the E2B contract.
- **Customize** storage backends in `Cubelet/storage/*.go` and API behavior in [`CubeAPI/src/state.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeAPI/src/state.rs) for advanced use cases.

## Frequently Asked Questions

### Do I need to modify my existing code to use CubeSandbox?

No. If your application already uses an E2B‑compatible SDK, you only need to set the `E2B_API_URL` environment variable to your CubeSandbox control node address. This makes CubeSandbox a drop‑in replacement for other sandbox services without requiring source‑code changes.

### What programming languages does the CubeSandbox SDK support?

The SDK supports **Python**, **Node.js**, **Go**, and **Rust**. All SDKs follow the same E2B contract, so integration patterns are consistent across languages. Reference [`sdk/python/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/python/README.md) and [`sdk/node/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/node/README.md) for language‑specific implementation details.

### How do I create custom sandbox templates from my own container images?

Use the CLI command `cubesandbox template create <name> --image <oci-image>` to convert any Docker or OCI‑compliant image into a CubeSandbox template. The platform stores these as efficient Copy‑on‑Write snapshots managed by the Cubelet storage backend (`Cubelet/storage/*.go`). See [`docs/guide/templates.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/templates.md) for advanced template management.

### Where can I find the API reference for extending CubeSandbox's core functionality?

Core API request handling is implemented in [`CubeAPI/src/state.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeAPI/src/state.rs) (Rust), while storage backends are in `Cubelet/storage/*.go` (Go). For proxy and routing customizations, examine `CubeProxy/lua/*.lua`. These files contain the extension points for customizing sandbox lifecycle, networking, and storage behaviors.