Boxlite AI Agent

<h1 align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/assets/boxlite-banner-dark.png"> <source media="(prefers-color-scheme: light)" srcset=".github/assets/boxlite-banner-light.png"> <img alt="BoxLite" src=".github/assets/boxlite-banner-light.png" width="560"> </picture> </h1> <p align="center"> <a href="https://pypi.org/project/boxlite/"><img alt="PyPI" src="https://img.shields.io/pypi/v/boxlite?logo=pypi&amp;logoColor=white&amp;label=pip"></a> <a href="https://www.npmjs.com/package/@boxlite-ai/boxlite"><img alt="npm" src="https://img.shields.io/npm/v/@boxlite-ai/boxlite?logo=npm&amp;label=npm"></a> <a href="https://crates.io/crates/boxlite"><img alt="crates.io" src="https://img.shields.io/crates/v/boxlite?logo=rust&amp;logoColor=white&amp;label=crates"></a> <a href="https://codecov.io/gh/boxlite-ai/boxlite"><img alt="codecov" src="https://codecov.io/gh/boxlite-ai/boxlite/branch/main/graph/badge.svg"></a> <a href="https://go.boxlite.ai/discord"><img alt="Discord" src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&amp;logoColor=white"></a> <a href="https://github.com/boxlite-ai/boxlite"><img alt="GitHub stars" src="https://img.shields.io/github/stars/boxlite-ai/boxlite?style=social"></a> <a href="https://opensource.org/licenses/Apache-2.0"><img alt="License" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg"></a> </p> <p align="center"> <strong>The compute substrate for AI agents</strong> — light enough to embed on your laptop, elastic enough to power an agentic cloud. </p>

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 into configured request headers at the host proxy.
• 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())

<details> <summary>Other languages — Node.js, Go, Rust (and the C SDK)</summary>

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); }

Full runnable versions: Python, Node, Go, Rust, C.

</details>

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

<details> <summary>Run BoxLite as a REST service; drive it from anything that speaks HTTP.</summary>

boxlite serve
# Listening on 127.0.0.1:8100 (add --host 0.0.0.0 --api-key "$KEY" to expose it)

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

REST-capable CLI commands also work against a running server with --url: boxlite --url http://localhost:8100 list.

</details>

4 · Distribute it — your own agentic cloud

<details> <summary>Deploy into your own AWS account or GCP project, with a shared control plane and a fleet of VM runners.</summary>

Start with the architecture graphs, then follow the deployment guide for stage configuration, bootstrap, preview and verification. Choose the AWS guide or GCP guide for provider-specific setup, operations and costs. Neither cloud is preferred; the stage declaration selects the provider.

</details>

Next steps

• More real-world scenarios → Examples
• How images, disks, networking, and isolation work → Concepts

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 → Concepts.

<details> <summary>Show diagram</summary>

┌──────────────────────────────────────────────────────────────┐
│  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

</details>

Documentation

• API & CLI Reference — SDK API references (Python, Node.js, Rust, C), the boxlite CLI reference, and the REST API contract (openapi/box.openapi.yaml)
• Using BoxLite with AI agents — concurrency, timeouts, security, file transfer
• Examples — Sample code for common use cases
• Concepts — How BoxLite works

Supported Platforms

Platform	Architecture	Status
macOS	Apple Silicon (ARM64)	✅ Supported
Linux	x86_64	✅ Supported
Linux	ARM64	✅ Supported
Windows (WSL2)	x86_64	✅ 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

Getting Help

• GitHub Issues — Bug reports and feature requests
• Discord — Questions and community support
• Status page — Live platform status and incident history
• 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.