BoxLite Python Examples

A collection of Python examples demonstrating how to use BoxLite.

What is BoxLite?

BoxLite is an embeddable virtual machine runtime for secure, isolated execution environments. Following the SQLite philosophy of "small, fast, reliable", BoxLite lets you run containers inside lightweight VMs with hardware-level isolation—no daemon required.

The Problem

AI agents are most powerful when they have freedom—freedom to write code, install packages, modify files, access the network, and explore solutions creatively. But that freedom on your host system is dangerous. And if you're hosting AI agents for customers, you need isolation that scales—without managing VM infrastructure.

Today's options force you to choose:

Approach	Trade-off
Restrict the AI	Safer, but cripples capability
Trust the AI	Full power, but one mistake away from disaster
Docker containers	Partial isolation—shares host kernel
Traditional VMs	Heavy, slow, complex to orchestrate
Cloud sandboxes	Latency, cost, vendor lock-in

BoxLite's Solution

BoxLite gives AI agents a complete playground—a full Linux environment where they can do anything—while guaranteeing nothing escapes to your host:

• Full Freedom Inside — Install packages, write files, run servers, use the network
• Hardware Isolation — Each Box is a separate VM with its own kernel, not just namespaces
• Batteries Included — VM, networking, OCI images, storage—all integrated, nothing to configure
• Embeddable — No daemon, no root, just a library in your application
• OCI Compatible — Use any Docker/OCI image (python:slim, node:alpine, etc.)
• Cross-Platform — macOS (Apple Silicon) and Linux (x86_64, ARM64)

The AI explores freely. Your system stays safe.

Use Cases

• AI Agent Sandbox — A full computer for your AI to explore, experiment, and build—safely isolated from your system
• AI Agent Hosting — Serverless multi-tenant runtime—spin up isolated environments on demand for each customer's AI
• Code Execution — Run untrusted code from users, playgrounds, or educational platforms
• Desktop Automation — Full GUI environments for browser automation and testing
• Regulated Environments — Hardware-level isolation for compliance where container breakout is unacceptable
• Local Development — Consistent Linux environments on macOS and Linux—no Docker Desktop required

Why BoxLite over Alternatives?

Feature	BoxLite	Docker	Traditional VMs	Cloud Sandboxes
Isolation Level	Hardware (VM)	Kernel namespaces	Hardware (VM)	Hardware (VM)
Startup Time	~100ms	~100ms	30+ seconds	Network latency ~1s
Requires Daemon	No	Yes	Yes	N/A
Requires Root	No	Often	Often	N/A
Embeddable	Yes	No	No	No
OCI Images	Yes	Yes	No	Varies
Cost	Free	Free	Free	Pay-per-use

Table of Contents

• Prerequisites
• Installation
• Quick Start
• Examples
• Troubleshooting
• Contributing
• License

Prerequisites

System Requirements

Platform	Architecture	Requirements
macOS	Apple Silicon	macOS 12+
Linux	x86_64, ARM64	KVM enabled (/dev/kvm accessible)

Software Requirements

• Python 3.10+ — Check with python3 --version
• uv — Fast Python package manager. Install with curl -LsSf https://astral.sh/uv/install.sh | sh

Linux-specific Setup

If you're on Linux, ensure KVM is accessible:

# Check if KVM is available
ls -la /dev/kvm

# If permission denied, add your user to the kvm group
sudo usermod -aG kvm $USER

# Log out and log back in for changes to take effect

Installation

Step 1: Clone this repository

git clone https://github.com/boxlite-labs/boxlite-python-examples.git
cd boxlite-python-examples

Step 2: Create a virtual environment and install dependencies

# Create virtual environment and install dependencies in one command
uv sync

Or if you prefer to do it step by step:

# Create virtual environment
uv venv

# Activate it
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt

Step 3: Verify installation

uv run python -c "import boxlite; print(f'BoxLite version: {boxlite.__version__}')"

Quick Start

Run the simplest example:

uv run python basics/hello_world.py

Expected output:

Starting BoxLite...
Hello from BoxLite!
Done!

That's it! You just ran a command inside an isolated virtual machine.

Examples

Basics

Start here to learn the fundamentals.

Example	Description	Run Command
hello_world.py	Simplest example - run a command in an isolated VM	uv run python basics/hello_world.py
simplebox_example.py	Basic container operations with SimpleBox	uv run python basics/simplebox_example.py
computerbox_example.py	Desktop automation with ComputerBox	uv run python basics/computerbox_example.py
interactivebox_example.py	Interactive shell session	uv run python basics/interactivebox_example.py

Use Cases

Real-world applications.

Example	Description	Run Command
run_python_code.py	Execute untrusted Python code safely	uv run python use-cases/run_python_code.py
web_automation.py	Browser automation with full desktop	uv run python use-cases/web_automation.py
file_processing.py	Process files in isolated environment	uv run python use-cases/file_processing.py

Advanced

For power users.

Example	Description	Run Command
multiple_boxes.py	Run multiple VMs concurrently	uv run python advanced/multiple_boxes.py
custom_environment.py	Configure CPU, memory, and environment	uv run python advanced/custom_environment.py
low_level_api.py	Direct runtime access and streaming	uv run python advanced/low_level_api.py

API Overview

SimpleBox — Run Commands

The easiest way to execute commands in isolation:

import asyncio
import boxlite

async def main():
    async with boxlite.SimpleBox(image="python:slim") as box:
        result = await box.exec("python3", "-c", "print('Hello!')")
        print(result.stdout)  # "Hello!"

asyncio.run(main())

ComputerBox — Desktop Automation

Full GUI desktop with mouse/keyboard automation:

import asyncio
import boxlite

async def main():
    async with boxlite.ComputerBox(cpu=2, memory=2048) as desktop:
        print(f"Desktop at: {desktop.endpoint()}")  # Open in browser

        await desktop.wait_until_ready()
        await desktop.mouse_move(100, 100)
        await desktop.left_click()
        await desktop.type("Hello World!")

        screenshot = await desktop.screenshot()

asyncio.run(main())

InteractiveBox — Shell Access

Interactive terminal session like docker exec -it:

import asyncio
from boxlite import InteractiveBox

async def main():
    async with InteractiveBox(image="alpine:latest") as box:
        await box.wait()  # Interactive shell - type "exit" to quit

asyncio.run(main())

Troubleshooting

"BoxLite native extension not found"

uv pip uninstall boxlite
uv pip install boxlite

"Permission denied: /dev/kvm" (Linux)

sudo usermod -aG kvm $USER
# Log out and log back in

"Image pull failed"

Ensure internet connectivity—BoxLite pulls images from container registries.

ComputerBox shows black screen

Always wait for the desktop to initialize:

await desktop.wait_until_ready(timeout=60)

Browser certificate warning for ComputerBox

ComputerBox uses self-signed HTTPS. Click "Advanced" → "Proceed to localhost".

Contributing

We welcome contributions!

1. Fork this repository
2. Create your example in basics/, use-cases/, or advanced/
3. Ensure it's self-contained and well-documented
4. Update this README
5. Submit a pull request

Resources

• BoxLite GitHub — Main repository
• BoxLite on PyPI — Python package
• GitHub Issues — Bug reports and feature requests

License

Apache License 2.0 — see LICENSE for details.