The compute substrate for AI agents — light enough to embed on your laptop, elastic enough to power an agentic cloud.
What is BoxLite?
A Box is a hardware-isolated micro-VM that runs any OCI image — and it persists. Agents install packages, write files, and resume across turns, never from cold.
Why BoxLite
- Real isolation: its own kernel — stronger than a container, lighter than a full VM. Small footprint, async-first for fleets.
- Daemonless: embed as a library — no root, no background service. (optional server mode)
- OCI-native: run any Docker image unchanged (
python:slim,node:alpine, …). - Controlled networking: restrict egress with
allow_net; inject real secrets via placeholders. - Embed → cloud: one engine, from your laptop to a multi-tenant cloud.
Get started
One engine. Embed it, run it, deploy it, distribute it.
1 · Embed it — a library in your app
Import BoxLite and give your agent an isolated VM to run code — no daemon, no binary. (Python 3.10+)
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())
Other languages — Node.js, Go, Rust (and the C SDK)
Node.js (npm install @boxlite-ai/boxlite, Node 18+)
import { SimpleBox } from '@boxlite-ai/boxlite';
const box = new SimpleBox({ image: 'python:slim' });
try {
const result = await box.exec('python', '-c', "print('Hello from BoxLite!')");
console.log(result.stdout);
} finally {
await box.stop();
}
Go (go get github.com/boxlite-ai/boxlite/sdks/go, Go 1.24+ with CGO)
ctx := context.Background()
rt, _ := boxlite.NewRuntime()
defer rt.Close()
box, _ := rt.Create(ctx, "alpine:latest")
defer box.Close()
result, _ := box.Exec(ctx, "echo", "Hello from BoxLite!")
fmt.Print(result.Stdout)
Rust (cargo add boxlite tokio futures --features tokio/macros,tokio/rt-multi-thread)
let runtime = BoxliteRuntime::default_runtime();
let litebox = runtime.create(BoxOptions {
rootfs: RootfsSpec::Image("alpine:latest".into()),
..Default::default()
}, None).await?;
let mut execution = litebox.exec(BoxCommand::new("echo").arg("Hello from BoxLite!")).await?;
let mut stdout = execution.stdout().unwrap();
while let Some(line) = stdout.next().await { println!("{}", line); }
2 · Run it — the binary, one command
No code needed — one install, then run any OCI image from your terminal.
curl -fsSL https://sh.boxlite.ai | sh
boxlite run python:slim python -c "print('Hello from BoxLite!')"
Installs to $HOME/.local/bin/boxlite, runtime embedded — no extra setup. Alternatives (cargo install boxlite-cli, version pinning, verification) → CLI reference.
3 · Deploy it — a standalone server
Run BoxLite as a REST service; drive it from anything that speaks HTTP.
boxlite serve
# Listening on 0.0.0.0:8100
curl -s -X POST http://localhost:8100/v1/boxes \
-H 'Content-Type: application/json' \
-d '{"image": "alpine:latest"}'
Every CLI command also works against a running server with --url: boxlite --url http://localhost:8100 list.
4 · Distribute it — your own agentic cloud
Deploy the control plane into your own AWS account (GCP on the way) — multi-tenant, autoscaling boxes for a fleet of agents. The substrate at full scale.
git clone https://github.com/boxlite-ai/boxlite && cd boxlite/apps/infra
npm install
npm run login # browser sign-in: AWS, GitHub, Auth0
npm run bootstrap -- --stage prod # IAM role, GitHub Environment, secrets
npm run deploy -- --stage prod
Needs an AWS account, a Cloudflare-managed domain, and Docker. Full guide → apps/infra/README.md.
Next steps
- More real-world scenarios → Examples
- How images, disks, networking, and isolation work → Architecture
Features
| Area | Capabilities |
|---|---|
| Execution | run any OCI image · async exec with streamed stdout/stderr + exit codes · interactive PTY with live resize · per-command timeout, workdir, env, run-as-user · entrypoint/cmd override |
| Isolation & security | a hardware-virtualized VM per box (KVM / Hypervisor.framework) · OS sandbox (seccomp / sandbox-exec) · CPU, memory & resource limits · egress allow-list (allow_net) · secret injection — real values never enter the VM · env sanitization |
| Storage & state | persists across stop/restart · volume mounts (ro/rw) · per-box QCOW2 disk with copy-on-write · bidirectional file copy · clone, or export/import as .boxlite archives · detached boxes that outlive the parent process |
| Networking | outbound internet · local TCP port forwarding · portable local/remote tunnels · network I/O metrics |
| Images | pull + cache any OCI image · custom & private registries · custom rootfs |
| Observability | per-box & runtime metrics — CPU, memory, network, boot time, commands · console logs · live stats |
| Interfaces | Python · Node.js · Go · Rust · C SDKs · the boxlite CLI · a REST API (WebSocket exec, optional auth) |
Ecosystem
Agent frameworks run on BoxLite:
- Databricks Omnigent — sandbox option in their agent meta-harness
- Alibaba AgentScope Runtime — sandbox backend (
CONTAINER_DEPLOYMENT=boxlite) - ByteDance deer-flow — sandbox provider in their research agent
Architecture
How BoxLite embeds a runtime and runs OCI containers inside micro-VMs. Details → Architecture.
Show diagram
┌──────────────────────────────────────────────────────────────┐
│ Your Application │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ BoxLite Runtime (embedded library) │ │
│ │ │ │
│ │ ╔════════════════════════════════════════════════╗ │ │
│ │ ║ Jailer (OS-level sandbox) ║ │ │
│ │ ║ ┌──────────┐ ┌──────────┐ ┌──────────┐ ║ │ │
│ │ ║ │ Box A │ │ Box B │ │ Box C │ ║ │ │
│ │ ║ │ (VM+Shim)│ │ (VM+Shim)│ │ (VM+Shim)│ ║ │ │
│ │ ║ │┌────────┐│ │┌────────┐│ │┌────────┐│ ║ │ │
│ │ ║ ││Container││ ││Container││ ││Container││ ║ │ │
│ │ ║ │└────────┘│ │└────────┘│ │└────────┘│ ║ │ │
│ │ ║ └──────────┘ └──────────┘ └──────────┘ ║ │ │
│ │ ╚════════════════════════════════════════════════╝ │ │
│ └───────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│
Hardware Virtualization + OS Sandboxing
(KVM/Hypervisor.framework + seccomp/sandbox-exec)
Security Layers:
- Hardware isolation (KVM/Hypervisor.framework)
- OS-level sandboxing (seccomp on Linux, sandbox-exec on macOS)
- Resource limits (cgroups, rlimits)
- Environment sanitization
Documentation
- API & CLI Reference — SDK API references (Python, Node.js, Rust, C) and the
boxliteCLI reference - Using BoxLite with AI agents — concurrency, timeouts, security, file transfer
- Examples — Sample code for common use cases
- Architecture — How BoxLite works under the hood
Supported Platforms
| Platform | Architecture | Status |
|---|---|---|
| macOS | Apple Silicon (ARM64) | ✅ Supported |
| Linux | x86_64 | ✅ Supported |
| Linux | ARM64 | ✅ Supported |
| Windows (WSL2) | x86_64 | ✅ Supported |
| macOS | Intel (x86_64) | 🚀 Coming soon |
System Requirements
| Platform | Requirements |
|---|---|
| macOS | Apple Silicon, macOS 12+ |
| Linux | KVM enabled (/dev/kvm accessible) |
| Windows (WSL2) | WSL2 with KVM support, user in kvm group |
Getting Help
- GitHub Issues — Bug reports and feature requests
- Discord — Questions and community support
- Security Policy — How to privately report a vulnerability
Contributing
We welcome contributions! See CONTRIBUTING.md for guidelines.
License
Licensed under the Apache License, Version 2.0. See LICENSE for details.