Python Quick Start

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

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

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

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

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

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.

┌──────────────────────────────────────────────────────────────┐
│  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 |