BoxLite documentation - BoxLite Documentation

BoxLite runs arbitrary code, commands, browsers, desktops, or entire AI agents inside hardware-isolated microVM sandboxes that start in about a second — in a few lines of code, and isolated enough to run untrusted LLM output directly.

Which BoxLite do I want?

There are two ways to run boxes, and the choice is made for you by one thing: whether the machine running your code has hardware virtualization.

Open source — boxes on your own machine

Free, self-hosted, no account. Needs hardware virtualization — KVM on Linux, Apple Silicon on macOS, WSL2 on Windows. Not available in most CI runners, nested VMs, or containers.

BoxLite Cloud — boxes on our machines

An API key and HTTPS is all your machine needs. Works from CI, containers, and locked-down laptops. Same SDK, different runtime handle.

Not sure? Run this. If it prints a path, take the open-source track; if it prints nothing, take Cloud:

# Linux
ls /dev/kvm 2>/dev/null
# macOS (Apple Silicon reports arm64)
uname -m | grep -q arm64 && echo "/dev/kvm-equivalent: Hypervisor.framework"

The two tracks are not exclusive — the same SDK talks to both, so developing against a local box and running the same code against Cloud in production is a change of runtime handle, not a rewrite. BoxLite Cloud vs open source enumerates every difference.

Run your first sandbox

This is the open-source path. For the Cloud path, see the Cloud quickstart.

pip install boxlite

# hello.py — needs hardware virtualization; see the Cloud track above if you have none
import asyncio
import boxlite


async def main() -> None:
    try:
        async with boxlite.SimpleBox(image="python:slim") as box:
            result = await box.exec("python", "-c", "print('Hello from BoxLite!')")
            # A non-zero exit code does not raise — check it yourself.
            print(result.stdout if result.exit_code == 0 else result.stderr, end="")
    except RuntimeError as exc:
        print("Box failed to start:", exc)


asyncio.run(main())

Hello from BoxLite!

The same five steps in Node.js, Rust, Go, and C are on the Quickstart. Platform matrix, the CLI, and offline installs are on Installation.

Who this documentation is for

AI / agent engineers: you need to give an LLM a secure sandbox that can run code, open a browser, and operate a desktop, without exposing the host to model-generated commands.
Backend / platform engineers: you need to start, reuse, and reclaim isolated execution environments on demand inside your own service (multi-tenant, CI, code grading, untrusted third-party code).
Agent product authors: you already have a demo and want to turn it into a concurrency-safe, observable, cleanable production service.

Quickest path for new users

Pick a track → above. Self-hosted needs virtualization; Cloud does not.
Run your first box → Quickstart for self-hosted, Cloud quickstart for Cloud.
Understand what you are operating → Architecture overview, then Box types.
Build something real → Agent tools for the capabilities, or use cases for end-to-end guides.
Go to production → Running sandboxes at scale and Error handling.

Where everything lives

One row per section. The sidebar lists every page; this table is for deciding which section you need.

Section	Answers
Introduction	What a Box is, how it differs from a container, and what is ready today
BoxLite Cloud	The hosted runtime: API keys, boxes, volumes, network, and pricing
Manage sandbox	Creating, configuring, and reclaiming boxes — resources, volumes, network, secrets
Agent tools	The capabilities an agent calls: run code, PTY, browser, desktop, MCP, Git
Agent in a box	Putting a full agent inside a box — Claude Code, tool loops, a REST service
Human tools	Handing a running box to a person: desktop and browser takeover
Use cases	End-to-end guides — one complete, runnable deliverable per page
From demo to production	Turning a demo into a production service: concurrency, limits, cleanup, deployment
Architecture	Components, the path of one `exec`, and — deeper — how isolation, networking, storage, and boot actually work
SDK reference	Exact signatures and types, one page per language, plus the CLI
FAQ and releases	Recurring questions, and where each release’s notes are published
Contributing	Working on BoxLite itself — build, tests, style, and the contributor license agreement

Key mental model (three sentences)

The Boxlite runtime: a synchronous context manager that creates / queries / reuses / reclaims a set of boxes (get / get_or_create / list_info / remove(id_or_name, force=False) / metrics / shutdown / close).
A Box: each sandbox is an async context manager (SimpleBox / CodeBox / BrowserBox / ComputerBox / InteractiveBox / SkillBox), and every method must be awaited — box.info() included, on both SimpleBox and the native Box.
Isolation: microVM-level isolation is on by default; to tighten it further use BoxOptions(advanced=AdvancedBoxOptions(security=SecurityOptions.maximum())), and to inject credentials use BoxOptions(secrets=[Secret(...)]).

​Which BoxLite do I want?

Open source — boxes on your own machine

BoxLite Cloud — boxes on our machines

​Run your first sandbox

​Who this documentation is for

​Quickest path for new users

​Where everything lives

​Key mental model (three sentences)