BoxLite

Compute substrate for AI agents: lightweight enough to live on your laptop, elastic enough to scale into the cloud and unleash unlimited resources.

What is BoxLite?

BoxLite lets you spin up lightweight VMs ("Boxes") and run OCI containers inside them. Unlike
ephemeral sandboxes that destroy state after each execution, BoxLite Boxes are persistent workspaces —
install packages, create files, build up environment state, then come back later and pick up where you left off.

Why BoxLite

• Stateful: Boxes retain packages, files, and environment across stop/restart. No rebuilding on every interaction.
• Lightweight: small footprint, fast boot, async-first API for high concurrency.
• Hardware isolation: each Box runs its own kernel — not just namespaces or containers.
• No daemon: embed as a library, no root, no background service.
• OCI compatible: use standard Docker images (python:slim, node:alpine, alpine:latest).
• Network policy + secret placeholders: restrict outbound access with allow_net and inject real HTTP(S) secrets from host-side secrets.
• Local-first: runs entirely on your machine — no cloud account needed. Scale out when ready.

Python Quick Start

View guide

Install

pip install boxlite

Requires Python 3.10+.

Run

import asyncio
import boxlite


async def main():
    async with boxlite.SimpleBox(image="python:slim") as box:
        result = await box.exec("python", "-c", "print('Hello from BoxLite!')")
        print(result.stdout)


asyncio.run(main())

Node.js Quick Start

View guide

Install

npm install @boxlite-ai/boxlite

Requires Node.js 18+.

Run

import { SimpleBox } from '@boxlite-ai/boxlite';

async function main() {
  const box = new SimpleBox({ image: 'python:slim' });
  try {
    const result = await box.exec('python', '-c', "print('Hello from BoxLite!')");
    console.log(result.stdout);
  } finally {
    await box.stop();
  }
}

main();

Rust Quick Start

View guide

Install

cargo add boxlite tokio futures --features tokio/macros,tokio/rt-multi-thread

Run

use boxlite::{BoxCommand, BoxOptions, BoxliteRuntime, RootfsSpec};
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = BoxliteRuntime::default_runtime();
    let options = BoxOptions {
        rootfs: RootfsSpec::Image("alpine:latest".into()),
        ..Default::default()
    };

    let litebox = runtime.create(options, None).await?;
    let mut execution = litebox
        .exec(BoxCommand::new("echo").arg("Hello from BoxLite!"))
        .await?;

    let mut stdout = execution.stdout().unwrap();
    while let Some(line) = stdout.next().await {
        println!("{}", line);
    }

    Ok(())
}

Go Quick Start

View guide

Install

go get github.com/boxlite-ai/boxlite/sdks/go
go run github.com/boxlite-ai/boxlite/sdks/go/cmd/setup

Requires Go 1.24+ with CGO enabled. The setup step downloads the prebuilt native library (one-time).

Run

package main

import (
	"context"
	"fmt"
	"log"

	boxlite "github.com/boxlite-ai/boxlite/sdks/go"
)

func main() {
	rt, err := boxlite.NewRuntime()
	if err != nil {
		log.Fatal(err)
	}
	defer rt.Close()

	ctx := context.Background()
	box, err := rt.Create(ctx, "alpine:latest", boxlite.WithName("my-box"))
	if err != nil {
		log.Fatal(err)
	}
	defer box.Close()

	result, err := box.Exec(ctx, "echo", "Hello from BoxLite!")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(result.Stdout)
}

CLI Quick Start

View guide

Install

curl -fsSL https://sh.boxlite.ai | sh

Installs to $HOME/.local/bin/boxlite. The runtime is embedded in the
binary — no extra setup. For alternatives (cargo install boxlite-cli,
version pinning, custom install dir) and release-artifact verification,
see the CLI Reference's Installation & Verification section.

Run

boxlite run python:slim python -c "print('Hello from BoxLite!')"

REST API Quick Start

View guide

Install

Install the boxlite CLI — see CLI Quick Start. The
REST server ships with the same binary. For release-artifact verification,
see the CLI Reference's Installation & Verification section.

Start the server

boxlite serve
# Listening on 0.0.0.0:8100

Use it

# Create a box
curl -s -X POST http://localhost:8100/v1/default/boxes \
  -H 'Content-Type: application/json' \
  -d '{"image": "alpine:latest"}'

# Run a command (replace BOX_ID from the response above)
curl -s -X POST http://localhost:8100/v1/default/boxes/BOX_ID/exec \
  -H 'Content-Type: application/json' \
  -d '{"command": "echo", "args": ["Hello from BoxLite!"]}'

All CLI commands also work against a running server:

boxlite --url http://localhost:8100 list
boxlite --url http://localhost:8100 exec BOX_ID -- echo "Hello!"

Next steps

• Run more real-world scenarios in Examples
• Learn how images, disks, networking, and isolation work in Architecture

Features

• Compute: CPU/memory limits, async-first API, streaming stdout/stderr, metrics
• Storage: volume mounts (ro/rw), persistent disks (QCOW2), copy-on-write
• Networking: outbound internet, port forwarding (TCP/UDP), network metrics
• Images: OCI pull + caching, custom rootfs support
• Security: hardware isolation (KVM/HVF), OS sandboxing (seccomp/sandbox-exec), resource limits
• Image Registry Configuration: Configure custom registries via config file (--config), CLI flags (--registry), or SDK options. See the configuration guide.
• SDKs: Rust (Rust 1.88+), Python (Python 3.10+), C (C11-compatible compiler), Node.js (Node.js 18+), Go (Go 1.24+)
• REST API: built-in HTTP server (boxlite serve) — use BoxLite from any language or tool via curl

Architecture

High-level overview of how BoxLite embeds a runtime and runs OCI containers inside micro-VMs.
For details, see Architecture.

Show diagram

┌──────────────────────────────────────────────────────────────┐
│  Your Application                                            │
│  ┌───────────────────────────────────────────────────────┐   │
│  │  BoxLite Runtime (embedded library)                   │   │
│  │                                                        │   │
│  │  ╔════════════════════════════════════════════════╗   │   │
│  │  ║ Jailer (OS-level sandbox)                      ║   │   │
│  │  ║  ┌──────────┐  ┌──────────┐  ┌──────────┐      ║   │   │
│  │  ║  │  Box A   │  │  Box B   │  │  Box C   │      ║   │   │
│  │  ║  │ (VM+Shim)│  │ (VM+Shim)│  │ (VM+Shim)│      ║   │   │
│  │  ║  │┌────────┐│  │┌────────┐│  │┌────────┐│      ║   │   │
│  │  ║  ││Container││  ││Container││  ││Container││      ║   │   │
│  │  ║  │└────────┘│  │└────────┘│  │└────────┘│      ║   │   │
│  │  ║  └──────────┘  └──────────┘  └──────────┘      ║   │   │
│  │  ╚════════════════════════════════════════════════╝   │   │
│  └───────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘
                              │
              Hardware Virtualization + OS Sandboxing
             (KVM/Hypervisor.framework + seccomp/sandbox-exec)

Security Layers:

• Hardware isolation (KVM/Hypervisor.framework)
• OS-level sandboxing (seccomp on Linux, sandbox-exec on macOS)
• Resource limits (cgroups, rlimits)
• Environment sanitization

Documentation

• API & CLI Reference — SDK API references (Python, Node.js, Rust, C) and the boxlite CLI reference
• Examples — Sample code for common use cases
• Architecture — How BoxLite works under the hood

Supported Platforms

Platform	Architecture	Status
macOS	Apple Silicon (ARM64)	✅ Supported
Linux	x86_64	✅ Supported
Linux	ARM64	✅ Supported
Windows (WSL2)	x86_64	✅ Supported
macOS	Intel (x86_64)	🚀 Coming soon

System Requirements

Platform	Requirements
macOS	Apple Silicon, macOS 12+
Linux	KVM enabled (/dev/kvm accessible)
Windows (WSL2)	WSL2 with KVM support, user in kvm group

Getting Help

• GitHub Issues — Bug reports and feature requests
• Discord — Questions and community support
• Security Policy — How to privately report a vulnerability

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.