https://github.com/boxlite-ai/boxlite
Embedded sandbox for running AI agents.
https://github.com/boxlite-ai/boxlite
ai-agents containers sandbox security serverless virtualization
Last synced: 24 days ago
JSON representation
Embedded sandbox for running AI agents.
- Host: GitHub
- URL: https://github.com/boxlite-ai/boxlite
- Owner: boxlite-ai
- License: apache-2.0
- Created: 2025-12-07T22:49:32.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-01-13T17:13:52.000Z (about 1 month ago)
- Last Synced: 2026-01-13T19:37:46.802Z (about 1 month ago)
- Topics: ai-agents, containers, sandbox, security, serverless, virtualization
- Language: Rust
- Homepage: https://boxlite-ai.github.io/website/
- Size: 928 KB
- Stars: 474
- Watchers: 4
- Forks: 25
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-rust-python - boxlite - Local-first sandbox for AI agents. (🤖 Machine Learning & AI)
README
# BoxLite
[](https://github.com/boxlite-ai/boxlite/actions/workflows/build-wheels.yml)
[](https://github.com/boxlite-ai/boxlite/actions/workflows/lint.yml)
[](https://pypi.org/project/boxlite/)
[](https://opensource.org/licenses/Apache-2.0)
**Embedded** micro-VM runtime for **AI agents** running OCI containers with
hardware-level isolation — **no daemon required**.
## What is BoxLite?
BoxLite lets you spin up **lightweight VMs** ("Boxes") and run **OCI containers inside them**. It's
designed for use cases like **AI agent sandboxes** and **multi-tenant code execution**, where Docker
alone isn't enough and full VM infrastructure is too heavy.
**Why BoxLite**
- **Hardware isolation**: each Box has its own kernel (not just namespaces).
- **Embeddable**: link a library; no root; no background service to manage.
- **OCI compatible**: use Docker/OCI images (`python:slim`, `node:alpine`, `alpine:latest`).
- **Async-first**: run many boxes concurrently; stream stdout/stderr.
## Python Quick Start
View guide
### Install
```bash
pip install boxlite
```
Requires Python 3.10+.
### Run
```python
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())
```
## Node.js Quick Start
View guide
### Install
```bash
npm install @boxlite-ai/boxlite
```
Requires Node.js 18+.
### Run
```javascript
import { SimpleBox } from '@boxlite-ai/boxlite';
async function main() {
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();
}
}
main();
```
## Rust Quick Start
View guide
### Install
```toml
[dependencies]
boxlite = { git = "https://github.com/boxlite-ai/boxlite" }
```
### Run
```rust
use boxlite::{BoxCommand, BoxOptions, BoxliteRuntime, RootfsSpec};
use futures::StreamExt;
#[tokio::main]
async fn main() -> Result<(), Box> {
let runtime = BoxliteRuntime::default_runtime();
let options = BoxOptions {
rootfs: RootfsSpec::Image("alpine:latest".into()),
..Default::default()
};
let litebox = runtime.create(options, 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);
}
Ok(())
}
```
## Next steps
- Run more real-world scenarios in [Examples](./examples/)
- Learn how images, disks, networking, and isolation work in [Architecture](./docs/architecture/)
## Features
- **Compute**: CPU/memory limits, async-first API, streaming stdout/stderr, metrics
- **Storage**: volume mounts (ro/rw), persistent disks (QCOW2), copy-on-write
- **Networking**: outbound internet, port forwarding (TCP/UDP), network metrics
- **Images**: OCI pull + caching, custom rootfs support
- **Security**: hardware isolation (KVM/HVF), OS sandboxing (seccomp/sandbox-exec), resource limits
- **SDKs**: Python (stable), Node.js (v0.1.6); Go coming soon
## Architecture
High-level overview of how BoxLite embeds a runtime and runs OCI containers inside micro-VMs.
For details, see [Architecture](./docs/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 Reference — Coming soon
- [Examples](./examples/) — Sample code for common use cases
- [Architecture](./docs/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) | ❌ Not supported |
## 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 |
| Python | 3.10+ |
## Getting Help
- [GitHub Issues](https://github.com/boxlite-ai/boxlite/issues) — Bug reports and feature requests
- [Discussions](https://github.com/boxlite-ai/boxlite/discussions) — Questions and community
support
## Contributing
We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
## License
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.