CubePod — Persistent Writable RootFS MicroVM Execution Platform
Persistent Writable RootFS MicroVM Execution Platform for AI Agents
Hardware-isolated Kata MicroVMs with Dual CSI Raw Block persistence, Zero-Export 0-CPU hibernation with ~1s cross-node resume, <50ms PodWarmPool claims, 1s CoW forks, and a Zero-Trust cpodref_ egress vault.
Drop-in E2B Compatibility or Enterprise Superset SDKs
Point E2B_DOMAIN to cubepod-gateway with zero code changes, or adopt the native CubePod Python, TypeScript, Go, and MCP toolchains to unlock RootFS resets, 1s CoW forks, and cpodref_ secret bindings.
export E2B_DOMAIN="localhost:8080"
export E2B_API_KEY="cpod_live_secret"
from e2b_code_interpreter import Sandbox
with Sandbox.create() as sandbox:
# Install system packages once — persisted in rootfs-pvc across suspends
sandbox.commands.run("pip install pandas matplotlib")
exec_res = sandbox.run_code("import pandas as pd; pd.DataFrame({'a': [1, 2, 3]})")
print(exec_res.results[0].html)import asyncio
from cubepod import AsyncCubePod
async def main() -> None:
async with AsyncCubePod(base_url="http://localhost:8080") as client:
box = await client.create(
"cubeplex-ubuntu24-desktop",
secret_bindings=[{
"env_name": "GITHUB_TOKEN",
"placeholder": "cpodref_gh_readonly_01",
"allowed_hosts": ["api.github.com"],
}],
)
forked = await client.fork(box.sandbox_id) # <1s CoW clone of both volumes
await client.reset_rootfs(box.sandbox_id) # Reset OS, keep /workspace intact
await client.pause(box.sandbox_id) # 0 CPU/RAM suspendimport { Sandbox } from 'cubepod';
const sandbox = await Sandbox.create({
baseUrl: 'http://localhost:8080',
templateId: 'cubeplex-ubuntu24-desktop',
timeout: 1800,
});
// Atomic tar.gz sync + streaming Code Interpreter + signed WebRTC/CDP panel URL
await sandbox.files.archiveSync({ 'app/main.py': 'print("ready")\n' }, { dest: '/workspace' });
const panel = await sandbox.createEndpoint(8080, { expiresInSeconds: 3600 });
console.log('Interactive GUI Panel:', panel.url);
await sandbox.pause();# Provision from WarmPool or template, inspect, fork, and expose MCP tools
cubepod health
cubepod sandbox create --template cubeplex-ubuntu24-desktop
cubepod sandbox exec <sandbox-id> "apt-get update && apt-get install -y ripgrep"
cubepod sandbox pause <sandbox-id>
cubepod sandbox fork <sandbox-id>
cubepod sandbox reset-rootfs <sandbox-id>
# Start native Model Context Protocol (MCP) JSON-RPC stdio server
cubepod mcpFour-Layer Cloud-Native Architecture
Decouples ephemeral base OCI images from persistent RootFS deltas and user workspaces—with zero host-level kubelet/containerd patches.
Access Layer: Agent Platforms & SDKs
- CubePlex Platform & CubeLoop Runtime
- Official E2B SDKs (e2b / e2b-code-interpreter)
- CubePod SDKs (Python / TypeScript / Go)
- Native MCP stdio Server (cubepod mcp)
Control & Gateway Plane (Stateless HA)
- cubepod-gateway (Go): E2B REST/SSE router & Auto-Resume traffic interceptor
- Signed /panel/{jwt}/ Reverse Proxy: HTTP / WebSocket / WebRTC GUI streaming
- cubepod-controller (Go): Dual Block PVC, PodWarmPool, CoW Fork & per-pod mTLS CA
Data Plane: Hardware-Isolated Kata MicroVM
- podd-init (Rust PID 1): e2fsck/mkfs.ext4 + OverlayFS assembly + pivot_root
- podd (Rust :49983): Exec, disk ring-buffer cursor logs & streaming tar.gz archive-sync
- cubepod-egress (Go): nftables redirection + TLS SNI policy + cpodref_ mTLS swap
- Lazy Desktop Stack: Xorg + Chromium CDP (:9222) + Neko WebRTC (:8080) + ttyd (:7681)
Persistent Storage Plane (CSI Raw Block)
- Base OCI Image (RO, virtio-fs / EROFS): Stock upstream images kept 100% clean
- rootfs-pvc (volumeMode: Block -> ext4): Persists /usr, /etc, /var across suspends
- workspace-pvc (volumeMode: Block -> /workspace): Native NVMe-oF speed & independent lifecycle
Enterprise Superset Capabilities Built for Long-Lived Agents
Decoupled RootFS Reset
RootFS Upper and /workspace reside on independent Raw Block PVCs. Increment rootfsGeneration to wipe a broken OS package state while keeping /workspace 100% intact.
Zero-Export0-CPU Suspend & ~1s Resume
Quiesce filesystems with sync + fsfreeze and delete the Pod to drop compute cost to zero. Any incoming request auto-schedules a MicroVM on any node in ~1s.
CoW Fork< 1s Copy-on-Write Sandbox Fork
Clone an active sandbox and both its RootFS and Workspace volumes via CSI snapshots so sub-agents can branch speculative trajectories concurrently.
Zero-Trustcpodref_ Secret Vault & Egress
Real API keys never enter sandbox memory or env vars. Outbound requests carry opaque placeholders exchanged by cubepod-egress over per-sandbox mTLS.
GUI & PanelLazy Desktop & Signed Panel Proxy
Activate Xorg, Chromium CDP, Neko WebRTC, and ttyd on demand—exposed safely via HMAC-SHA256 /panel/{token}/ URLs with zero port collisions.
MCP & Kernels6 Code Kernels & Native MCP
Stream NDJSON outputs and charts across Python, JS, TS, R, Java, and Bash, or expose sandboxes directly to Claude & Cursor via cubepod mcp.
CubePod vs. Upstream E2B & Standard Sandboxes
| Capability | Upstream E2B / Standard Containers | CubePod v0.4.0 Open-Source |
|---|---|---|
| System Persistence | Ephemeral RootFS; apt/pip installs lost on sleep | Full RootFS + /workspace dual block persistence across suspends |
| Storage Performance | Container overlay or slow shared NFS/CephFS RPCs | Dual CSI Raw Block (Longhorn V2 SPDK / OpenEBS LVM) at NVMe-oF speed |
| OS / Data Coupling | Resetting environment wipes workspace or vice versa | Fully decoupled: increment rootfsGeneration without touching /workspace |
| Suspend & Cold Start | Multi-GB VM memory snapshots or cold boots | Zero-Export (0 CPU/RAM) + ~1s block re-attach + <50ms WarmPool claims |
| Sandbox Forking | Unsupported or full volume copies | < 1s Copy-on-Write volume clone (POST /sandboxes/{id}/fork) |
| Secret Isolation | Plaintext API keys in environment variables | Opaque cpodref_ placeholders + nftables + mTLS egress swap |
| Deployment Freedom | Proprietary SaaS vendor lock-in | 100% E2B superset · Self-host on K8s (Kata) or Docker Compose |