cubesandbox-ai-sandbox

What this skill does

# CubeSandbox AI Sandbox Skill

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

CubeSandbox is a high-performance secure sandbox service built on RustVMM and KVM. It provides hardware-isolated (dedicated Guest OS kernel) sandbox environments that start in under 60ms, consume less than 5MB memory overhead per instance, and are fully compatible with the E2B SDK — making it a drop-in replacement for E2B with better performance and true VM-level isolation.

---

## What CubeSandbox Does

- Spins up KVM-backed microVMs in <60ms using snapshot cloning + CoW memory
- Provides thousands of concurrent isolated sandboxes per node (<5MB RAM overhead each)
- Offers E2B SDK compatibility — just change one env var to migrate
- Enforces kernel-level network isolation via eBPF (CubeVS)
- Supports single-node and multi-node cluster deployments
- Enables code execution, shell commands, file ops, browser automation, and RL training

---

## Requirements

- x86_64 Linux with KVM enabled (bare metal, WSL2, or cloud bare-metal)
- Not supported on shared VMs that don't allow nested virtualization

**Check KVM availability:**
```bash
ls /dev/kvm && echo "KVM available"
```

---

## Installation

### Option A: Development VM (WSL2 / no bare metal)

```bash
git clone https://github.com/tencentcloud/CubeSandbox.git
cd CubeSandbox/dev-env
./prepare_image.sh   # one-time: downloads runtime image
./run_vm.sh          # start the dev VM (keep terminal open)
# In a second terminal:
./login.sh           # shell into the dev VM
```

### Option B: Bare-Metal / Cloud Server

Inside the target Linux host (or the dev VM from Option A):

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

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

This installs `cubemastercli` and starts the CubeAPI service on port 3000.

---

## Key CLI: `cubemastercli`

### Create a Template from a Docker Image

```bash
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
# Returns a job_id
```

### Watch Build Progress

```bash
cubemastercli tpl watch --job-id <job_id>
# Wait for status: READY
# Note the template_id from output
```

### List Templates

```bash
cubemastercli tpl list
```

### Delete a Template

```bash
cubemastercli tpl delete --template-id <template_id>
```

### List Running Sandboxes

```bash
cubemastercli sandbox list
```

### Kill a Sandbox

```bash
cubemastercli sandbox kill --sandbox-id <sandbox_id>
```

---

## Environment Variables

```bash
# Required for SDK usage
export E2B_API_URL="http://127.0.0.1:3000"     # CubeAPI endpoint
export E2B_API_KEY="dummy"                       # any non-empty string (auth not required locally)
export CUBE_TEMPLATE_ID="<your-template-id>"     # from cubemastercli tpl watch output
export SSL_CERT_FILE="/root/.local/share/mkcert/rootCA.pem"  # local CA cert
```

---

## Python SDK Usage (E2B-Compatible)

Install the E2B SDK:

```bash
pip install e2b-code-interpreter
```

### Basic Code Execution

```python
import os
from e2b_code_interpreter import Sandbox

template_id = os.environ["CUBE_TEMPLATE_ID"]

with Sandbox.create(template=template_id) as sandbox:
    result = sandbox.run_code("print('Hello from CubeSandbox!')")
    print(result.text)
    # Output: Hello from CubeSandbox!
```

### Run Python with Return Values

```python
import os
from e2b_code_interpreter import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    result = sandbox.run_code("""
import math
data = [1, 4, 9, 16, 25]
roots = [math.sqrt(x) for x in data]
print(roots)
roots
""")
    print(result.text)       # stdout
    print(result.results)    # return value of last expression
```

### Shell Command Execution

```python
import os
from e2b_code_interpreter import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    # Run shell commands
    result = sandbox.run_code("import subprocess; print(subprocess.check_output(['ls', '-la', '/'], text=True))")
    print(result.text)
```

### File Operations

```python
import os
from e2b_code_interpreter import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    # Write a file
    sandbox.files.write("/tmp/hello.txt", "Hello, CubeSandbox!")

    # Read the file back
    content = sandbox.files.read("/tmp/hello.txt")
    print(content)

    # List directory
    entries = sandbox.files.list("/tmp")
    for entry in entries:
        print(entry.name, entry.type)
```

### Install Packages at Runtime

```python
import os
from e2b_code_interpreter import Sandbox

with Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"]) as sandbox:
    # Install a package inside the sandbox
    result = sandbox.run_code("import subprocess; subprocess.run(['pip', 'install', 'requests'], capture_output=True)")

    # Use the installed package
    result = sandbox.run_code("""
import requests
r = requests.get("https://httpbin.org/get")
print(r.status_code)
""")
    print(result.text)
```

### Persistent Sandbox (Manual Lifecycle)

```python
import os
from e2b_code_interpreter import Sandbox

# Create without context manager for explicit control
sandbox = Sandbox.create(template=os.environ["CUBE_TEMPLATE_ID"])
try:
    sandbox.run_code("x = 42")
    result = sandbox.run_code("print(x)")  # state persists within session
    print(result.text)  # 42
finally:
    sandbox.kill()
```

### Concurrent Sandboxes

```python
import os
import asyncio
from e2b_code_interpreter import AsyncSandbox

template_id = os.environ["CUBE_TEMPLATE_ID"]

async def run_task(task_id: int, code: str):
    async with await AsyncSandbox.create(template=template_id) as sandbox:
        result = await sandbox.run_code(code)
        return task_id, result.text

async def main():
    tasks = [
        run_task(i, f"print('Task {i} result:', {i} ** 2)")
        for i in range(10)
    ]
    results = await asyncio.gather(*tasks)
    for task_id, output in results:
        print(f"Task {task_id}: {output.strip()}")

asyncio.run(main())
```

---

## Custom Template Creation

### From a Custom Dockerfile

Build and push your image, then create a template:

```bash
# Build and push your image
docker build -t myregistry.example.com/my-sandbox:latest .
docker push myregistry.example.com/my-sandbox:latest

# Create CubeSandbox template
cubemastercli tpl create-from-image \
  --image myregistry.example.com/my-sandbox:latest \
  --writable-layer-size 2G \
  --expose-port 49999 \
  --expose-port 8080 \
  --probe 49999

# Watch until READY
cubemastercli tpl watch --job-id <job_id>
```

### Template with Multiple Exposed Ports

```bash
cubemastercli tpl create-from-image \
  --image ccr.ccs.tencentyun.com/ags-image/sandbox-code:latest \
  --writable-layer-size 1G \
  --expose-port 49999 \   # code interpreter
  --expose-port 49983 \   # file server
  --expose-port 3000  \   # custom app port
  --probe 49999            # health check port
```

---

## REST API (CubeAPI)

CubeAPI runs on port 3000 and is E2B-compatible. Example direct calls:

```bash
# Create a sandbox
curl -s -X POST http://127.0.0.1:3000/sandboxes \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dummy" \
  -d "{\"templateID\": \"$CUBE_TEMPLATE_ID\"}"

# List sandboxes
curl -s http://127.0.0.1:3000/sandboxes \
  -H "X-API-Key: dummy"

# Delete a sandbox
curl -s -X DELETE "http://127.0.0.1:3000/sandboxes/<sandbox_id>" \
  -H "X-API-Key: dummy"
```

---

## Architecture Overview

| Component | Role |
|---|---|
| **CubeAPI** | Rust REST gateway, E2B-compatible, port 3000 |
| **CubeMaster** | Cluster orchestrator, dispatches to Cubelets, manages scheduling |
| **Cubelet** | Per-node agent, manages local microVM l