zeroboot-vm-sandbox

Zeroboot VM Sandbox

Skill by ara.so — Daily 2026 Skills collection.

Zeroboot provides sub-millisecond KVM virtual machine sandboxes for AI agents using copy-on-write forking. Each sandbox is a real hardware-isolated VM (via Firecracker + KVM), not a container. A template VM is snapshotted once, then forked in ~0.8ms per execution using mmap(MAP_PRIVATE) CoW semantics.

How It Works

Firecracker snapshot ──► mmap(MAP_PRIVATE) ──► KVM VM + restored CPU state
                           (copy-on-write)          (~0.8ms)

1. Template: Firecracker boots once, pre-loads your runtime, snapshots memory + CPU state
2. Fork (~0.8ms): New KVM VM maps snapshot memory as CoW, restores CPU state
3. Isolation: Each fork is a separate KVM VM with hardware-enforced memory isolation

Installation

Python SDK

pip install zeroboot

Node/TypeScript SDK

npm install @zeroboot/sdk
# or
pnpm add @zeroboot/sdk

Authentication

Set your API key as an environment variable:

export ZEROBOOT_API_KEY="zb_live_your_key_here"

Never hardcode keys in source files.

Quick Start

REST API (cURL)

curl -X POST https://api.zeroboot.dev/v1/exec \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ZEROBOOT_API_KEY" \
  -d '{"code":"import numpy as np; print(np.random.rand(3))"}'

Python

import os
from zeroboot import Sandbox

# Initialize with API key from environment
sb = Sandbox(os.environ["ZEROBOOT_API_KEY"])

# Run Python code
result = sb.run("print(1 + 1)")
print(result)  # "2"

# Run multi-line code
result = sb.run("""
import numpy as np
arr = np.arange(10)
print(arr.mean())
""")
print(result)

TypeScript / Node.js

import { Sandbox } from "@zeroboot/sdk";

const apiKey = process.env.ZEROBOOT_API_KEY!;
const sb = new Sandbox(apiKey);

// Run JavaScript/Node code
const result = await sb.run("console.log(1 + 1)");
console.log(result); // "2"

// Run async code
const output = await sb.run(`
const data = [1, 2, 3, 4, 5];
const sum = data.reduce((a, b) => a + b, 0);
console.log(sum / data.length);
`);
console.log(output);

Common Patterns

AI Agent Code Execution Loop (Python)

import os
from zeroboot import Sandbox

def execute_agent_code(code: str) -> dict:
    """Execute LLM-generated code in an isolated VM sandbox."""
    sb = Sandbox(os.environ["ZEROBOOT_API_KEY"])
    try:
        result = sb.run(code)
        return {"success": True, "output": result}
    except Exception as e:
        return {"success": False, "error": str(e)}

# Example: running agent-generated code safely
agent_code = """
import json
data = {"agent": "result", "value": 42}
print(json.dumps(data))
"""
response = execute_agent_code(agent_code)
print(response)

Concurrent Sandbox Execution (Python)

import os
import asyncio
from zeroboot import Sandbox

async def run_sandbox(code: str, index: int) -> str:
    sb = Sandbox(os.environ["ZEROBOOT_API_KEY"])
    result = await asyncio.to_thread(sb.run, code)
    return f"[{index}] {result}"

async def run_concurrent(snippets: list[str]):
    tasks = [run_sandbox(code, i) for i, code in enumerate(snippets)]
    results = await asyncio.gather(*tasks)
    return results

# Run 10 sandboxes concurrently
codes = [f"print({i} ** 2)" for i in range(10)]
outputs = asyncio.run(run_concurrent(codes))
for out in outputs:
    print(out)

TypeScript: Agent Tool Integration

import { Sandbox } from "@zeroboot/sdk";

interface ExecutionResult {
  success: boolean;
  output?: string;
  error?: string;
}

async function runInSandbox(code: string): Promise<ExecutionResult> {
  const sb = new Sandbox(process.env.ZEROBOOT_API_KEY!);
  try {
    const output = await sb.run(code);
    return { success: true, output };
  } catch (err) {
    return { success: false, error: String(err) };
  }
}

// Integrate as a tool for an LLM agent
const tool = {
  name: "execute_code",
  description: "Run code in an isolated VM sandbox",
  execute: async ({ code }: { code: string }) => runInSandbox(code),
};

REST API with fetch (TypeScript)

const API_BASE = "https://api.zeroboot.dev/v1";

async function execCode(code: string): Promise<string> {
  const res = await fetch(`${API_BASE}/exec`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.ZEROBOOT_API_KEY}`,
    },
    body: JSON.stringify({ code }),
  });
  if (!res.ok) {
    const err = await res.text();
    throw new Error(`Zeroboot error ${res.status}: ${err}`);
  }
  const data = await res.json();
  return data.output;
}

Health Check

curl https://api.zeroboot.dev/v1/health

API Reference

POST /v1/exec

Execute code in a fresh sandbox fork.

Request:

{
  "code": "print('hello')"
}

Headers:

Authorization: Bearer <ZEROBOOT_API_KEY>
Content-Type: application/json

Response:

{
  "output": "hello\n",
  "duration_ms": 0.79
}

Performance Characteristics

• Each sandbox is a real KVM VM — not a container or process jail
• Memory isolation is hardware-enforced (not software)
• CoW means only pages written by your code consume extra RAM

Self-Hosting / Deployment

See docs/DEPLOYMENT.md in the repo. Requirements:

• Linux host with KVM support (/dev/kvm accessible)
• Firecracker binary
• Rust 2021 edition toolchain

# Check KVM availability
ls /dev/kvm

# Clone and build
git clone https://github.com/adammiribyan/zeroboot
cd zeroboot
cargo build --release

Architecture Notes

• Snapshot layer: Firecracker VM boots once per runtime template, memory + vCPU state saved to disk
• Fork layer (Rust): mmap(MAP_PRIVATE) on snapshot file → kernel handles CoW page faults per VM
• Isolation: Each fork has its own KVM VM file descriptors, vCPU, and page table — fully hardware-separated
• No shared kernel: Unlike containers, each sandbox runs its own kernel instance

Troubleshooting

/dev/kvm not found (self-hosted)

# Enable KVM kernel module
sudo modprobe kvm
sudo modprobe kvm_intel  # or kvm_amd

API returns 401 Unauthorized

• Verify ZEROBOOT_API_KEY is set and starts with zb_live_
• Check the key is not expired in your dashboard

Timeout on execution

• Default execution timeout is enforced server-side
• Break large computations into smaller chunks
• Avoid infinite loops or blocking I/O in sandbox code

High memory usage (self-hosted)

• Each VM fork starts at ~265KB CoW overhead
• Pages are allocated on write — memory grows with sandbox activity
• Tune concurrent fork limits based on available RAM

Resources

• API Reference
• Architecture Docs
• Deployment Guide
• Homepage
• GitHub