boxlite-ai / boxlite

BoxLite Local-first micro-VM sandbox for **AI agents** — stateful, lightweight, hardware-level isolation, **no daemon required**. 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 ( , , ). • **Local-first**: runs entirely on your machine — no cloud account needed. Scale out when ready. Python Quick Start View guide Install Requires Python 3.10+. Run Node.js Quick Start View guide Install Requires Node.js 18+. Run Rust Quick Start View guide Install Run Go Quick Start View guide Install Requires Go 1.24+ with CGO enabled. The setup step downloads the prebuilt native library (one-time). Run REST API Quick Start View guide Install Start the server Use it All CLI commands also work against a running server: 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 ( ), CLI flags ( ), 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 ( ) — 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 **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 Reference — Coming soon • 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 ( accessible) | | Windows (WSL2) | WSL2 with KVM support, user in group | Getting Help • GitHub Issues — Bug reports and feature requests • Discord — Questions and community support Contributing We welcome contributions! See CONTRIBUTING.md for guidelines. License Licensed under the Apache License, Version 2.0. See LICENSE for details.