InstantConcurrentSecure & Lightweight Sandbox Service for AI Agents

中文文档 · Quick Start · Documentation · Discord

Cube Sandbox is a high-performanceout-of-the-box secure sandbox service built on RustVMM and KVM. It supports both single-node deployment and can be easily scaled to a multi-node cluster. It is compatible with the E2B SDKcapable of creating a hardware-isolated sandbox environment with full service capabilities in under 60mswhile maintaining less than 5MB memory overhead.

• Blazing-fast cold start: Built on resource pool pre-provisioning and snapshot cloning technologyskipping time-consuming initialization entirely. Average end-to-end cold start time for a fully serviceable sandbox is < 60ms.
• High-density deployment on a single node: Extreme memory reuse via CoW technology combined with a Rust-rebuiltaggressively trimmed runtime keeps per-instance memory overhead below 5MB — run thousands of Agents on a single machine.
• True kernel-level isolation: No more unsafe Docker shared-kernel (Namespace) hacks. Each Agent runs with its own dedicated Guest OS kerneleliminating container escape risks and enabling safe execution of any LLM-generated code.
• Zero-cost migration (E2B drop-in replacement): Natively compatible with the E2B SDK interface. Just swap one URL environment variable — no business logic changes needed — to migrate from expensive closed-source sandboxes to free Cube Sandbox with better performance.
• Network security: CubeVSpowered by eBPFenforces strict inter-sandbox network isolation at the kernel level with fine-grained egress traffic filtering policies.
• Ready to use out of the box: One-click deployment with support for both single-node and cluster setups.
• Event-level snapshot rollback (coming soon): High-frequency snapshot rollback at millisecond granularityenabling rapid fork-based exploration environments from any saved state.
• Production-ready: Cube Sandbox has been validated at scale in Tencent Cloud production environmentsproven stable and reliable.

In the context of AI Agent code executionCubeSandbox achieves the perfect balance of security and performance:

• Cold start benchmarked on bare-metal. 60ms at single concurrency; under 50 concurrent creationsavg 67msP95 90msP99 137ms — consistently sub-150ms.
• Memory overhead measured with sandbox specs ≤ 32GB. Larger configurations may see a marginal increase.

For detailed metrics on startup latency and resource overheadplease refer to:

Sub-150ms sandbox delivery under both single and high-concurrency workloads		CubeSandbox base memory footprint across various instance sizes (*Blue: Sandbox specifications; Orange: Base memory overhead). Note that memory consumption increases only marginally as instance sizes scale up.

⚡ Millisecond-level startup — watch the fast-start flowthen jump into the Quick Start guide.

Cube Sandbox requires a KVM-enabled x86_64 Linux environment — WSL 2a Linux physical machineor a cloud bare-metal server all work.

Don't have one yet?

• Windows users: run wsl --install in an admin PowerShell to set up WSL 2 (requires Windows 11 22H2+with nested virtualization enabled in BIOS / WSL).
• Others: grab an x86_64 Linux physical machineor rent a bare-metal server from a cloud provider.

Once your environment is readylaunch your first sandbox in four steps:

1. Prepare the runtime environment (skip this step if you already have an x86_64 bare-metal Linux server)

Run the following on your WSL / Linux machine:

git clone https://github.com/tencentcloud/CubeSandbox.git
# For faster access from mainland Chinaclone from the mirror instead:
# git clone https://cnb.cool/CubeSandbox/CubeSandbox

cd CubeSandbox/dev-env
./prepare_image.sh   # one-off: download and initialize the runtime image
./run_vm.sh          # boot the environment; keep this terminal open (Ctrl+a x to exit)

In a second terminallog into the environment you just prepared:

cd CubeSandbox/dev-env && ./login.sh

This drops you into a disposable Linux environment where all the subsequent installation happensso your host stays clean. See Development Environment for details.

2. Start the Cube Sandbox Service

Inside the environment you entered via login.sh (or directly on your bare-metal server)run one of the following commands depending on your location:

• Global Users (downloads from GitHub):

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

• 中国用户请执行这条命令 (Mainland China):

  curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | MIRROR=cn bash

See Quick Start — China mainland mirror for details.

3. Create a Code Interpreter Sandbox Template

After installationcreate a code interpreter template from the prebuilt image:

cubemastercli tpl create-from-image \
  --image ccr.ccs.tencentyun.com/ags-image/sandbox-code:latest \
  --writable-layer-size 1G \
  --expose-port 49999 \
  --expose-port 49983 \
  --probe 49999

Then run the following command to monitor the build progress:

cubemastercli tpl watch --job-id <job_id>

⚠️ The image is fairly large — downloadingextractingand building the template may take a while; please be patient.

Wait for the command above to finish and the template status to reach READY. Note the template ID (template_id) from the output — you will need it in the next step.

4. Run Your First Agent Code

Install the Python SDK:

yum install -y python3 python3-pip
pip install e2b-code-interpreter

Set environment variables:

export E2B_API_URL="http://127.0.0.1:3000"
export E2B_API_KEY="dummy"
export CUBE_TEMPLATE_ID="<your-template-id>"  # template ID obtained from Step 3
export SSL_CERT_FILE="$(mkcert -CAROOT)/rootCA.pem"

Run code inside an isolated sandbox:

import os
from e2b_code_interpreter import Sandbox  # drop-in E2B SDK

# Cube Sandbox transparently intercepts all requests
with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    result = sandbox.run_code("print('Hello from Cube Sandboxsafely isolated!')")
    print(result)

See Quick Start — Step 4 for the full variable reference and more examples.

Want to explore more? Check out the 📂 examples/ directorycovering scenarios like: code executionShell commandsfile operationsbrowser automationnetwork policiespause/resumeOpenClaw integrationand RL training.

• 📖 Documentation Home - Complete guide and API reference
• 🔧 Template Concepts - Image-to-Template concepts and workflows
• 🌟 Example Projects - Hands-on examples demonstrating various Cube Sandbox use cases (Browser automationOpenClaw integrationRL training workflowsetc.)
• 💻 Development Environment (QEMU VM) - No bare-metal? Spin up a disposable OpenCloudOS 9 VM and run Cube Sandbox inside it

👉 For more detailsplease read the Architecture Design Document and CubeVS Network Model.

We welcome contributions of all kinds—whether it’s a bug reportfeature suggestiondocumentation improvementor code submission!

• 🐞 Found a Bug? Submit an issue on GitHub Issues.
• 💡 Have an Idea? Join the conversation in GitHub Discussions.
• 🛠️ Want to Code? Check out our CONTRIBUTING.md to learn how to submit a Pull Request.
• 💬 Want to Chat? Join our Discord.

CubeSandbox is released under the Apache License 2.0.

The birth of CubeSandbox stands on the shoulders of open-source giants. Special thanks to Cloud HypervisorKata Containersvirtiofsdcontainerd-shim-rsttrpc-rustand others. We have made tailored modifications to some components to fit the CubeSandbox execution modeland the original in-file copyright notices are preserved.