Skip to main content

​
Overview

BoxLite is a local-first micro-VM sandbox for AI agents. It follows the SQLite philosophy: a library that can be embedded directly into applications without requiring a daemon or external service. Boxes are stateful — they retain packages, files, and environment across stop/restart cycles.
Throughout this documentation, we use “Box” to refer to an isolated execution environment (the underlying implementation uses a lightweight VM). A Box provides hardware-level isolation while presenting a simple, container-like interface.

​
Core Design Philosophy

BoxLite is built around several key principles:
  • Stateful workspaces — Boxes retain state across stop/restart, no rebuilding on every interaction
  • Embeddable library model — no daemon or external service required, just link and use
  • Hardware-level isolation — each Box runs in a lightweight VM for strong security boundaries
  • Container-like interface — familiar OCI image and exec workflows despite VM-backed isolation
  • Lazy initialization — heavy work (image pulling, Box startup) is deferred until first use
  • Defense-in-depth security — OS-level sandboxing layered on top of hardware virtualization

​
High-Level Architecture

The architecture spans multiple layers: host runtime, subprocess isolation, OS-level sandboxing, and guest VM execution. 
┌────────────────────────────────────────────────────────────────────┐
│                          Host Application                          │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                        BoxliteRuntime                        │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐       │  │
│  │  │ BoxManager  │  │ImageManager │  │ RuntimeMetrics  │       │  │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘       │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                              │                                     │
│                              ▼                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                           LiteBox                            │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐       │  │
│  │  │  Lifecycle  │  │    Exec     │  │    Metrics      │       │  │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘       │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                              │                                     │
│                              ▼                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                        ShimController                        │  │
│  │        (Spawns shim with jailer isolation)                   │  │
│  └──────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────┘
                               │
                      Spawns subprocess
                               │
                               ▼
┌────────────────────────────────────────────────────────────────────┐
│                    JAILER BOUNDARY (OS Sandbox)                    │
│  ╔══════════════════════════════════════════════════════════════╗  │
│  ║                 Shim Process (boxlite-shim)                  ║  │
│  ║  - Seccomp filtering (Linux)                                 ║  │
│  ║  - Namespace isolation (Linux)                               ║  │
│  ║  - sandbox-exec (macOS)                                      ║  │
│  ║  - Resource limits (cgroups/rlimits)                         ║  │
│  ╚══════════════════════════════════════════════════════════════╝  │
│                              │                                     │
│                        Unix Socket / Vsock                         │
│                              │                                     │
│                              ▼                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                        Box (Guest VM)                        │  │
│  │  ┌────────────────────────────────────────────────────────┐  │  │
│  │  │                      Guest Agent                       │  │  │
│  │  │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐      │  │  │
│  │  │  │  Guest   │  │Container │  │   Execution      │      │  │  │
│  │  │  │  Service │  │  Service │  │    Service       │      │  │  │
│  │  │  └──────────┘  └──────────┘  └──────────────────┘      │  │  │
│  │  └────────────────────────────────────────────────────────┘  │  │
│  │                              │                               │  │
│  │                              ▼                               │  │
│  │  ┌────────────────────────────────────────────────────────┐  │  │
│  │  │                 OCI Container Runtime                  │  │  │
│  │  └────────────────────────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────┘

​
Concurrency Model

​
Thread Safety

  • BoxliteRuntime: Send + Sync, safely shareable across threads
  • LiteBox: Send + Sync, handles can be passed between threads
  • Single RwLock protects all mutable runtime state
  • Metrics use AtomicU64 for lock-free updates

​
Single Lock Design

BoxLite uses one RwLock for all mutable state:
  • Eliminates nested locking complexity
  • Simplifies reasoning about concurrency
  • Filesystem lock prevents multiple runtimes using same BOXLITE_HOME

​
Async Design

  • All I/O operations are async (Tokio runtime)
  • Streaming operations use futures::Stream
  • gRPC uses tonic’s async support

​
Error Handling

All public APIs return BoxliteResult<T> which is an alias for Result<T, BoxliteError>. 
pub enum BoxliteError {
    UnsupportedEngine,
    Engine(String),
    Storage(String),
    Image(String),
    Portal(String),
    Network(String),
    Rpc(String),
    RpcTransport(String),
    Internal(String),
    Execution(String),
}

​
Directory Layout

Default home directory: ~/.boxlite 
~/.boxlite/
├── boxes/              # Per-Box runtime data
│   └── {box-id}/
│       ├── rootfs/     # Container rootfs
│       └── config.json
├── images/             # OCI image cache
│   ├── blobs/          # Image layer blobs (by digest)
│   └── index.json      # Image index
├── init/               # Shared init rootfs
│   └── rootfs/
├── logs/               # Runtime logs
│   └── boxlite.log     # Daily rotating log
└── boxlite.lock        # Runtime lock file (prevents multiple instances)

​
SDK Architecture

BoxLite provides language-specific SDKs built on the core Rust library. 
┌─────────────────────────────────────────┐
│           Host Application              │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│     Language SDK (Python, Node, C)      │
│         (Native bindings)               │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│         BoxLite Core (Rust)             │
└─────────────────────────────────────────┘
SDKTechnologyStatusLocation
PythonPyO3 + maturinAvailablesdks/python/
Node.jsnapi-rsAvailablesdks/node/
CFFI + cbindgenAvailablesdks/c/

​
Shared Library

The boxlite-shared crate contains data types, error definitions, and constants shared between the host runtime, the shim, and the guest agent. Location: boxlite-shared/ Key Components:
  • BoxliteError: Centralized error type
  • Constants: Shared constants (e.g. socket paths, default ports)
  • Transport: gRPC transport utilities

​
Explore the Architecture

Core Components

Deep dive into BoxliteRuntime, LiteBox, ShimController, Jailer, Guest Agent, and the VMM abstraction layer.

Security & Isolation

Understand the defense-in-depth security model, OS-level sandboxing, and platform-specific isolation mechanisms.

Networking & Storage

Learn about network backends, port forwarding, image management, rootfs assembly, and volume types.