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

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.
• 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 file for environment-specific requirements and resource recommendations.

Install the CubeSandbox Service

Deploy the platform using either the 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.

# 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:

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.

Configure the SDK Endpoint

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

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:

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:

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	Python client quick‑start and authentication patterns
sdk/node/README.md	Node.js usage examples and async patterns
docs/guide/quickstart.md	Full installation tutorial and first sandbox creation
docs/guide/templates.md	OCI image conversion and template lifecycle management
docs/guide/security-proxy.md	Credential vault configuration and egress policy setup
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 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 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 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 and 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 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 (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.

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