zeroboot-vm-sandbox

$27

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

Metric

Value

Spawn latency p50

~0.79ms

Spawn latency p99

~1.74ms

Memory per sandbox

~265KB

Fork + exec Python

~8ms

1000 concurrent forks

~815ms

• 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