BoxLite: a micro-VM sandbox for AI agents that runs OCI images without a daemon

What BoxLite solves for agent code execution

An agent that writes and runs code needs a place to run it that is not your application process. Containers share the host kernel, so a kernel-level escape is a host-level escape. Full VMs are heavy to start per turn. BoxLite targets that gap with what the README calls a Box: a hardware-isolated micro-VM that runs any OCI image and persists across stop and restart. The audience is narrow and identifiable. You are building an agent that installs packages, writes files and resumes across turns, and you want each session to sit behind its own kernel without shipping a background daemon or requiring root. The README's framing is a compute substrate that is light enough to embed on a laptop and elastic enough to run multi-tenant in the cloud, with the same engine in both places. That last claim is the interesting one, because embedded library use and multi-tenant server use usually pull a project in opposite directions: one optimises for zero setup on a developer machine, the other for isolation between mutually hostile tenants. BoxLite's answer is that both are the same Rust engine with different front doors.

How the BoxLite engine is put together

The workspace layout in Cargo.toml is the clearest statement of the architecture. There is a core crate at src/boxlite, a CLI at src/cli, shared types at src/shared, a guest component at src/guest, and a shim at src/shim. Four vendored dependency crates sit under src/deps: libkrun-sys, libgvproxy-sys, bubblewrap-sys and e2fsprogs-sys. Those names tell you the mechanism. libkrun is the virtual machine monitor that provides the per-box kernel; libgvproxy is the user-space network stack that makes outbound networking and port forwarding work without host-level network configuration; bubblewrap supplies the OS sandbox layer the README lists alongside seccomp and sandbox-exec; e2fsprogs handles the filesystem images. The README states that isolation is a hardware-virtualized VM per box using KVM on Linux and Hypervisor.framework on macOS, with an OS sandbox on top. Storage is a per-box QCOW2 disk with copy-on-write, which is what makes clone and the .boxlite export/import archive possible, and what lets a box persist across restarts rather than booting cold each turn. Networking is outbound internet plus local TCP port forwarding, with an egress allow-list configured through allow_net. Secret injection is the design choice worth noting: the README says real secret values never enter the VM, and placeholders are substituted instead. That is a meaningful boundary, because an agent that can read its own environment cannot exfiltrate a credential it never had. The Cargo.toml also carries a patch entry pulling libcontainer from a youki commit rather than a tagged release, with a comment explaining it fixes an InitReady/IntermediateReady race under concurrent builds. Shipping against an untagged upstream revision is a real maintenance cost, not a detail.

Installing BoxLite and running a first box

The README gives four entry points. The library path is the shortest. BoxLite's Python package requires Python 3.10 or newer, and the example creates a box from an OCI image, runs a command inside it, and prints stdout.

pip install boxlite

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())

If you prefer a terminal, the install script places a binary in $HOME/.local/bin/boxlite with the runtime embedded, so there is no separate setup step. The README notes cargo install boxlite-cli as an alternative and points to the CLI reference for version pinning and verification.

curl -fsSL https://sh.boxlite.ai | sh
boxlite run python:slim python -c "print('Hello from BoxLite!')"

Server mode turns the same engine into a REST service. The README shows boxlite serve listening on 0.0.0.0:8100, and a POST to /v1/boxes with an image name creating a box. REST-capable CLI commands accept --url to target a running server, so boxlite --url http://localhost:8100 list works against the daemon.

boxlite serve
curl -s -X POST http://localhost:8100/v1/boxes \
  -H 'Content-Type: application/json' \
  -d '{"image": "alpine:latest"}'

For other languages the README lists npm install @boxlite-ai/boxlite for Node 18+, go get github.com/boxlite-ai/boxlite/sdks/go for Go 1.24+ with CGO, and cargo add boxlite for Rust. The repository ships runnable examples under sdks/python, sdks/node, sdks/go, sdks/c and docs/reference/rust. One caveat on the root package.json: it declares boxlite version 1.0.0 with an ISC license and a test script that exits with an error, while the workspace Cargo.toml sets version 0.10.1 and Apache-2.0. That root file looks like a leftover rather than the published package metadata, so read the language-specific package manifests instead of trusting it.

Where BoxLite gets expensive or simply does not fit

The first constraint is the hypervisor. KVM on Linux and Hypervisor.framework on macOS are not optional accelerators here; they are the isolation mechanism. A container-based CI runner, a nested-virtualization-disabled cloud instance, or a Linux host without /dev/kvm exposed will not give you the boundary the README describes. That is a deployment-shape decision you make before writing code, and the README does not document a fallback path for those environments.

The second constraint is API stability. The workspace version is 0.10.1, releases arrive at a cadence of roughly six to eight weeks, and the Cargo patch pulls libcontainer from an untagged youki revision. The README also does not document rollback or downgrade behaviour for boxes, nor does it describe what happens to a running box when the embedding process exits, beyond noting that detached boxes outlive the parent. If you are pinning BoxLite inside a long-lived product, plan to read the changelog per release rather than assuming interface continuity.

The third is scope. BoxLite is an engine you operate. If what you want is a managed sandbox API with someone else answering the pager, this is the wrong layer. The apps/infra path deploys a control plane into your own AWS account, and the README lists a Cloudflare-managed domain, Docker and an AWS account as prerequisites. That is infrastructure you own and pay for, not a hosted service.

Finally, the secret-injection model is worth pressure-testing against your own threat model. Placeholders that never carry real values into the VM are a strong default, but the README does not spell out how a process inside the box authenticates against an external service that expects the real credential. Read docs/architecture before assuming the mechanism covers your case.

BoxLite against container-based agent sandboxes

The obvious alternative is running agent code in a Docker container, which is what most agent frameworks do today. The difference is the boundary. A container shares the host kernel and relies on namespaces, cgroups and a seccomp profile for separation; BoxLite gives each box its own kernel through libkrun. If your agent runs code you did not write, that is a different class of guarantee, and it is the whole reason the project exists. The cost is startup weight and host requirements: a micro-VM boots a kernel, and it needs KVM or Hypervisor.framework, where a container starts in milliseconds anywhere Docker runs. BoxLite also keeps the OCI image format, so python:slim or node:alpine work unchanged, which removes the usual objection to VM-based sandboxes that require bespoke images. A second comparison point is the persistence model. A plain container is typically ephemeral per exec unless you mount a volume, whereas a Box has a per-box QCOW2 disk with copy-on-write and survives stop and restart. For an agent that installs a package in turn one and imports it in turn five, that changes the design of the agent loop itself. If your workload is short, stateless and already containerised with a hardened runtime, BoxLite adds hypervisor requirements for isolation you may not need.

Licence, upgrade cost and what to check before pinning

BoxLite is Apache-2.0, stated in the repository LICENSE, the README badge and the workspace Cargo.toml. That is a permissive licence with an explicit patent grant, and it does not impose copyleft obligations on your own code. It also means you can embed the engine in a commercial product. Two things to check that are not legal questions but do affect what you ship: the NOTICE file, which Apache-2.0 projects use to record attribution, and the licences of the four vendored dependency crates under src/deps, since libkrun, gvproxy, bubblewrap and e2fsprogs are separate upstream projects with their own terms. The root package.json declares ISC, which conflicts with the Apache-2.0 declaration elsewhere; treat that file as stale metadata rather than a licensing statement, and confirm with the maintainers if it matters to your review process.

Upgrade cost is the more practical concern. The version is 0.10.x, the release cadence is roughly every six to eight weeks, and the libcontainer patch tracks a youki commit rather than a release. Each upgrade means reading the changelog and re-checking that the patch still applies cleanly, because that dependency sits on the critical path for container construction inside the box. If you vendor BoxLite, budget for that review per release. If you consume it from PyPI, npm or crates.io, the pinning discipline is the same but the failure mode is quieter: a minor version bump can change behaviour you depended on without breaking your build.

Editorial conclusion

BoxLite fits teams running untrusted agent-generated code on their own machines or in their own cloud, who want a real kernel boundary rather than a container namespace and are willing to build against a young API. It is the wrong pick if you need a stable interface across many releases, if your deployment target lacks KVM or Hypervisor.framework, or if you want a managed sandbox service rather than an engine you operate. Before committing, verify three things against the tag you pin: that your host exposes /dev/kvm or the macOS hypervisor, that the guest kernel and rootfs you need are covered by the image and custom-rootfs paths the README describes, and that the secret-injection and allow_net behaviour match your threat model by reading the architecture docs rather than the feature table.

Frequently asked questions

Official sources

1. boxlite-ai/boxlite on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases