BoxLite documentation

​

Run your first sandbox

pip install boxlite

# hello.py — requires hardware virtualization (KVM on Linux, Hypervisor.framework on Apple Silicon)
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!

​

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

1. Install it → Installation (note the platform and virtualization requirements; the Node package is @boxlite-ai/boxlite).
2. Run your first sandbox → pick your language:
   • Python quickstart
   • Node.js quickstart
   • Rust quickstart
   • Go quickstart
   • C quickstart
3. Understand what you are operating → Architecture overview, then Box types.
4. Build something real → go to Agent tools (run code / commands / browser / desktop) or the use cases for end-to-end guides.
5. Go to production → Running sandboxes at scale and Error handling.

Environment prerequisite: BoxLite depends on hardware virtualization. Linux requires KVM; macOS runs through its built-in microVM / virtualization stack. Startup fails in environments without virtualization support (such as some nested VMs or CI runners) — see the Troubleshooting section on each page and Debug macOS Seatbelt denials.

​

Where everything lives

​

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 box.info() is a synchronous call.
• 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(...)]).