BoxLite: a micro-VM sandbox for AI agents, embedded or served over HTTP

The problem BoxLite targets: agent code that must run somewhere real

An agent that writes and executes code needs a place to run it that is not the host machine. Running the code in the same process as the agent means a bad import or a runaway loop takes down the agent. Running it in a container gives process isolation but shares the host kernel, which is a weaker boundary than many teams want when the code was generated by a model. BoxLite's answer is a micro-VM per box: the README states each box gets a hardware-virtualized VM via KVM on Linux or Hypervisor.framework on macOS, with its own kernel, plus an OS sandbox layer using seccomp or sandbox-exec. The pitch is that this is stronger than a container and lighter than a full VM. The intended audience is narrow but real: developers embedding an agent runtime in a desktop or server application, and platform teams that want to run a fleet of agent boxes without operating a full hypervisor stack. The README frames it as one engine that scales from a laptop to what it calls an agentic cloud.

How a Box actually works: OCI image in, persistent micro-VM out

The unit of work is a Box. According to the README, a Box runs any OCI image unchanged, so python:slim or node:alpine work as they would under Docker. Underneath, the runtime pulls and caches the image, then boots a micro-VM whose root filesystem is backed by a per-box QCOW2 disk with copy-on-write. That copy-on-write layer is what makes persistence possible: the README says a box persists across stop and restart, so packages installed in one turn are still there in the next. Commands are executed asynchronously with streamed stdout and stderr plus exit codes, and there is an interactive PTY with live resize. Networking is outbound by default, with an egress allow-list controlled by the allow_net key, local TCP port forwarding, and what the README calls portable local and remote tunnels. Secrets are handled by placeholder injection: the real value never enters the VM. Storage also supports read-only or read-write volume mounts, bidirectional file copy, cloning, and export or import as .boxlite archives. Detached boxes can outlive the parent process, which matters if the agent process restarts while a long job is still running.

Getting it running: four entry points, four install commands

The README gives four distinct paths, and they are genuinely different products sharing one engine. For embedding, pip install boxlite requires Python 3.10 or newer, and the example wraps a SimpleBox in an async with block, calls box.exec("python", "-c", ...) and reads result.stdout. The Node binding is npm install @boxlite-ai/boxlite on Node 18 or newer, with a SimpleBox class and an explicit await box.stop() in a finally block. Go uses go get github.com/boxlite-ai/boxlite/sdks/go and requires Go 1.24 or newer with CGO enabled, which is a notable constraint for Go teams used to pure-Go builds. Rust is cargo add boxlite tokio futures with the tokio/macros and tokio/rt-multi-thread features, and the example builds a BoxliteRuntime, creates a box from RootfsSpec::Image("alpine:latest"), then streams stdout line by line. There is also a C SDK. For terminal use, the shell installer is curl -fsSL https://sh.boxlite.ai | sh, which installs to $HOME/.local/bin/boxlite with the runtime embedded; the README notes cargo install boxlite-cli as an alternative. Server mode is a single boxlite serve command that listens on 0.0.0.0:8100, after which you can POST to /v1/boxes with a JSON body containing an image field. REST-capable CLI commands accept --url, so boxlite --url http://localhost:8100 list works against a running server.

The daemonless claim is the real differentiator, and it has a cost

Most sandbox runtimes in this space assume a long-running daemon: Docker needs dockerd, containerd needs containerd, and Firecracker-style setups usually need a manager process. BoxLite's README states it is daemonless and can be embedded as a library with no root and no background service, with server mode described as optional. That is a meaningful property for desktop agents, where asking a user to install and run a system service is a hard sell. It also means the runtime is linked into your process, which changes the failure model. A crash in the VM layer is a crash in your application, not in a service that can be restarted independently. The README does not describe crash recovery or how a detached box is reattached after the parent process dies, only that detached boxes outlive the parent. That gap matters for anyone building long-running jobs. The four SDKs are also not equivalent in maturity by construction: the Go binding requires CGO, which implies the core is a C ABI shared library, and that is a packaging surface you will have to ship and version alongside your own application.

Where BoxLite is the wrong tool

BoxLite is not a general container runtime and should not be adopted as one. If your workload is a trusted, long-lived service, the micro-VM boundary buys you isolation you do not need and charges you boot time and memory per box. The README gives no boot latency figures, no memory overhead numbers and no density claims, so you cannot size a fleet from the documentation alone; that is a real gap, not a detail. The multi-tenant cloud path is also the least settled part of the project. The README's distribution section describes deploying a control plane into your own AWS account, and states it needs an AWS account, a Cloudflare-managed domain and Docker, with GCP described as on the way. It also lists npm run login, npm run bootstrap -- --stage prod and npm run deploy -- --stage prod, and points to apps/infra/README.md for the full guide. That is an infrastructure recipe, not a hosted service, and it ties the deployment to AWS and Cloudflare specifically. Teams that need a managed, provider-neutral control plane today will not find one described here.

Compared with running agent code in Docker containers

The honest comparison is with plain Docker. Docker shares the host kernel; BoxLite gives each box its own kernel through KVM or Hypervisor.framework, which is the difference the README leans on when it says stronger than a container. Docker is also daemon-based, while BoxLite can be linked into the process. But Docker has a decade of tooling around image building, networking, volume drivers and orchestration that BoxLite does not claim to match, and Docker runs on hosts where nested virtualization is unavailable. BoxLite's own constraints point the same way: the README names KVM and Hypervisor.framework specifically, which means Linux and macOS, and it does not describe a Windows path. If your agents run on Windows developer machines or on cloud instances without nested virtualization exposed, the isolation model BoxLite depends on is not available to you, and a container runtime is the practical choice. Conversely, if you are already comfortable with Docker and your threat model accepts a shared kernel, BoxLite adds a virtualization dependency and a smaller ecosystem for a boundary you may not need.

Licence, maintenance and what the release cadence tells you

BoxLite is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notice files and comply with the patent grant and termination terms. That is a permissive licence, and it is compatible with embedding the runtime in a closed-source product, but the usual caveat applies: if you modify the source and redistribute, the notice obligations follow, and this is not legal advice. On maintenance, the repository shows releases v0.10.0 on 2026-08-28, v0.9.7 on 2026-07-01 and v0.9.5 on 2026-05-16, with the last push on 2026-09-10. The version numbers are still in the 0.x range and the gap between 0.9.7 and 0.10.0 suggests the API is still moving, so pinning a version and reading the release notes before upgrading is the practical posture. The README also lists Python 3.10+, Node 18+ and Go 1.24+ with CGO as minimums, which means each SDK upgrade can pull a toolchain requirement forward. There is no documented deprecation policy or long-term support branch in the material supplied.

Editorial conclusion

Adopt BoxLite if you are building an agent that must run untrusted code on a developer laptop or a small self-hosted fleet, and you want VM-level isolation without running a daemon as root. Do not adopt it if your workload is a single trusted Python process, or if you need a mature multi-tenant control plane today; the README describes the AWS deployment path as requiring your own account, a Cloudflare-managed domain and Docker, with GCP still on the way. Before committing, verify three things on your own hardware: that KVM or Hypervisor.framework is available and permitted, that the OCI images you depend on boot correctly under the micro-VM, and that the persistence and clone semantics of the .boxlite archive format match what your agent expects across restarts.

Official sources

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