boxlite 0.9.0

Python bindings for Boxlite runtime

BoxLite Python SDK

Python bindings for BoxLite - an embeddable virtual machine runtime for secure, isolated code execution.

Overview

The BoxLite Python SDK provides a Pythonic API for creating and managing isolated execution environments. Built with PyO3, it wraps the Rust BoxLite runtime with async-first Python bindings.

Python: 3.10+ Platforms: macOS (Apple Silicon), Linux (x86_64, ARM64)

Key Features

• Async-first API - All I/O operations use async/await
• Context managers - Automatic cleanup with async with
• Streaming I/O - Real-time stdout/stderr as execution happens
• Multiple box types - SimpleBox, CodeBox, BrowserBox, ComputerBox, InteractiveBox
• Resource control - Configure CPUs, memory, volumes, ports
• OCI compatible - Use any Docker/OCI image

Installation

pip install boxlite

Requires Python 3.10 or later.

Verify Installation

import boxlite
print(boxlite.__version__)  # Prints installed package version

System Requirements

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

On Linux, verify KVM is available:

grep -E 'vmx|svm' /proc/cpuinfo  # Should show CPU virtualization support
ls -l /dev/kvm                    # Should exist and be accessible

Quick Start

Basic Execution

import asyncio
import boxlite

async def main():
    # Create a box and run a command
    async with boxlite.SimpleBox(image="python:slim") as box:
        result = await box.exec("python", "-c", "print('Hello from BoxLite!')")
        print(result.stdout)
        # Output: Hello from BoxLite!

asyncio.run(main())

Code Execution (AI Agents)

import asyncio
import boxlite

async def main():
    # Execute untrusted Python code safely
    code = """
import requests
response = requests.get('https://api.github.com/zen')
print(response.text)
"""

    async with boxlite.CodeBox() as codebox:
        # CodeBox automatically installs packages
        result = await codebox.run(code)
        print(result)

asyncio.run(main())

Core API Reference

Runtime Management

boxlite.Boxlite

The main runtime for creating and managing boxes.

Methods:

• Boxlite.default() -> Boxlite Create runtime with default settings (~/.boxlite)

• Boxlite(options: Options) -> Boxlite Create runtime with custom options

• create(box_options: BoxOptions) -> Box Create a new box with specified configuration

• get(box_id: str) -> Box Reattach to an existing box by ID

• list() -> List[BoxInfo] List all boxes (running and stopped)

• metrics() -> RuntimeMetrics Get runtime-wide metrics

Example:

# Default runtime
runtime = boxlite.Boxlite.default()

# Custom runtime with different home directory
runtime = boxlite.Boxlite(boxlite.Options(home_dir="/custom/path"))

# Custom registry host with basic auth
runtime = boxlite.Boxlite(boxlite.Options(
    image_registries=[
        boxlite.ImageRegistry(
            host="registry.example.com",
            username="user",
            password="password",
        )
    ]
))

# Create a box
box = runtime.create(boxlite.BoxOptions(image="alpine:latest"))

# Reattach to existing box
box = runtime.get("01JJNH8...")

# List all boxes
boxes = runtime.list()
for info in boxes:
    print(f"{info.id}: {info.status}")

Runtime Image Management

runtime = boxlite.Boxlite.default()

pull = await runtime.images.pull("alpine:latest")
print(pull.reference, pull.config_digest, pull.layer_count)

for image in await runtime.images.list():
    print(image.repository, image.tag, image.id)

Box Configuration

boxlite.BoxOptions

Configuration options for creating a box.

Parameters:

• image: str - OCI image URI (default: "python:slim")
• cpus: int - Number of CPUs (default: 1, max: host CPU count)
• memory_mib: int - Memory in MiB (default: 512, range: 128-65536)
• disk_size_gb: int | None - Persistent disk size in GB (default: None)
• working_dir: str - Working directory in container (default: "/root")
• env: List[Tuple[str, str]] - Environment variables as (key, value) pairs
• volumes: List[Tuple[str, str, str]] - Volume mounts as (host_path, guest_path, mode)
  • Mode: "ro" (read-only) or "rw" (read-write)
• network: NetworkSpec | None - Structured network configuration
• ports: List[Tuple[int, int, str]] - Port forwarding as (host_port, guest_port, protocol)
  • Protocol: "tcp" or "udp"
• secrets: List[Secret] - Host-side HTTP(S) secret substitution rules
• auto_remove: bool - Auto cleanup after stop (default: True)

NetworkSpec uses:

• mode: str - "enabled" or "disabled"
• allow_net: List[str] - Optional outbound allowlist when mode="enabled"

mode="disabled" removes the guest network interface entirely.

Example:

options = boxlite.BoxOptions(
    image="postgres:latest",
    cpus=2,
    memory_mib=1024,
    disk_size_gb=10,  # 10 GB persistent disk
    env=[
        ("POSTGRES_PASSWORD", "secret"),
        ("POSTGRES_DB", "mydb"),
    ],
    volumes=[
        ("/host/data", "/mnt/data", "ro"),  # Read-only mount
    ],
    ports=[
        (5432, 5432, "tcp"),  # PostgreSQL
    ],
    network=boxlite.NetworkSpec(
        mode="enabled",
        allow_net=["api.openai.com"],
    ),
    secrets=[
        boxlite.Secret(
            name="openai",
            value="sk-...",
            hosts=["api.openai.com"],
        ),
    ],
)
box = runtime.create(options)

Box Handle

boxlite.Box

Handle to a running or stopped box.

Properties:

• id: str - Unique box identifier (ULID format)

Methods:

• exec(*args, **kwargs) -> Execution Execute a command in the box (async)

• stop() -> None Stop the box gracefully (async)

• remove() -> None Delete the box and its data (async)

• info() -> BoxInfo Get box metadata (async)

• metrics() -> BoxMetrics Get box resource usage metrics (async)

Example:

box = runtime.create(boxlite.BoxOptions(image="alpine:latest"))

# Execute commands
execution = await box.exec("echo", "Hello")
result = await execution.wait()

# Get box info
info = await box.info()
print(f"Box {info.id}: {info.status}")

# Stop and remove
await box.stop()
await box.remove()

Command Execution

boxlite.Execution

Represents a running command execution.

Methods:

• stdout() -> ExecStdout Get stdout stream (async iterator)

• stderr() -> ExecStderr Get stderr stream (async iterator)

• stdin() -> ExecStdin Get stdin writer

• wait() -> ExecResult Wait for command to complete and get result (async)

• kill(signal: int = 9) -> None Send signal to process (async)

• resize_tty(rows: int, cols: int) -> None Resize PTY terminal window (async). Only works with TTY-enabled executions.

Example:

# Streaming output
execution = await box.exec("python", "-c", "for i in range(5): print(i)")

stdout = execution.stdout()
async for line in stdout:
    print(f"Output: {line}")

# Wait for completion
result = await execution.wait()
print(f"Exit code: {result.exit_code}")

boxlite.ExecStdout / boxlite.ExecStderr

Async iterators for streaming output.

Usage:

execution = await box.exec("ls", "-la")

# Stream stdout line by line
stdout = execution.stdout()
async for line in stdout:
    print(line)

# Stream stderr
stderr = execution.stderr()
async for line in stderr:
    print(f"Error: {line}", file=sys.stderr)

Higher-Level APIs

boxlite.SimpleBox

Context manager for basic execution with automatic cleanup.

Parameters: Same as BoxOptions

Methods:

• exec(cmd, *args, env=None, user=None, timeout=None, cwd=None) -> ExecResult Execute command and wait for result
  • env: Dict of environment variables (e.g., {"FOO": "bar"})
  • user: Run as user (format: name or uid:gid, like docker exec --user)
  • timeout: Timeout in seconds (default: no timeout)
  • cwd: Working directory inside the container

Example:

async with boxlite.SimpleBox(image="python:slim") as box:
    result = await box.exec("python", "-c", "print('Hello')")
    print(result.stdout)  # "Hello\n"
    print(result.exit_code)  # 0

    # Run in a specific directory as a specific user
    result = await box.exec("pwd", cwd="/tmp", user="nobody")
    print(result.stdout)  # "/tmp\n"

    # With a timeout
    result = await box.exec("sleep", "60", timeout=5)

boxlite.CodeBox

Specialized box for Python code execution with package management.

Methods:

• run(code: str) -> str Execute Python code and return output

• install_package(package: str) -> None Install a Python package with pip

Example:

async with boxlite.CodeBox() as codebox:
    # Install packages
    await codebox.install_package("requests")

    # Run code
    result = await codebox.run("""
import requests
print(requests.get('https://api.github.com/zen').text)
""")
    print(result)

boxlite.BrowserBox

Box configured for browser automation (Chromium, Firefox, WebKit).

Example:

async with boxlite.BrowserBox() as browser:
    endpoint = browser.endpoint()
    print(f"Connect Puppeteer to: {endpoint}")
    # Use with Puppeteer/Playwright for browser automation

boxlite.ComputerBox

Box with desktop automation capabilities (mouse, keyboard, screenshots).

Methods:

14 desktop interaction functions including:

• screenshot() -> bytes - Capture screen
• left_click() - Click mouse
• type_text(text: str) - Type text
• get_screen_size() -> Tuple[int, int] - Get screen dimensions

Example:

async with boxlite.ComputerBox() as computer:
    # Get screen size
    width, height = await computer.get_screen_size()

    # Take screenshot
    screenshot_bytes = await computer.screenshot()

    # Mouse and keyboard
    await computer.left_click()
    await computer.type_text("Hello, world!")

boxlite.InteractiveBox

Box for interactive shell sessions.

Example:

async with boxlite.InteractiveBox(image="alpine:latest") as itbox:
    # Drop into interactive shell
    await itbox.wait()

API Patterns

Async/Await

All I/O operations are async. Use await for operations and async for for streams.

# Create and use box (async)
async with boxlite.SimpleBox(image="alpine") as box:
    result = await box.exec("echo", "Hello")

# Stream output (async iterator)
execution = await box.exec("python", "script.py")
async for line in execution.stdout():
    print(line)

Context Managers

Use async with for automatic cleanup:

# SimpleBox - auto cleanup
async with boxlite.SimpleBox() as box:
    result = await box.exec("command")
# Box automatically stopped and removed

# Manual cleanup (if not using context manager)
box = runtime.create(boxlite.BoxOptions(image="alpine"))
try:
    await box.exec("command")
finally:
    await box.stop()
    await box.remove()

Streaming I/O

Stream output line-by-line as it's produced:

execution = await box.exec("tail", "-f", "/var/log/app.log")

# Process output in real-time
stdout = execution.stdout()
async for line in stdout:
    if "ERROR" in line:
        print(f"Alert: {line}")

Error Handling

Catch exceptions from BoxLite operations:

import boxlite
from boxlite import BoxliteError, ExecError

try:
    async with boxlite.SimpleBox(image="invalid:image") as box:
        result = await box.exec("command")
except BoxliteError as e:
    print(f"BoxLite error: {e}")
except ExecError as e:
    print(f"Execution error: {e}")

Configuration Reference

Image Selection

Any OCI-compatible image from Docker Hub, GHCR, ECR, or other registries:

# Docker Hub (default registry)
boxlite.BoxOptions(image="python:3.11-slim")
boxlite.BoxOptions(image="alpine:latest")
boxlite.BoxOptions(image="ubuntu:22.04")

# GitHub Container Registry
boxlite.BoxOptions(image="ghcr.io/owner/repo:tag")

# Amazon ECR
boxlite.BoxOptions(image="123456.dkr.ecr.us-east-1.amazonaws.com/repo:tag")

Resource Limits

boxlite.BoxOptions(
    cpus=4,           # 4 CPU cores
    memory_mib=2048,  # 2 GB RAM
)

Environment Variables

boxlite.BoxOptions(
    env=[
        ("DATABASE_URL", "postgresql://localhost/db"),
        ("API_KEY", "secret"),
        ("DEBUG", "true"),
    ]
)

Volume Mounts

boxlite.BoxOptions(
    volumes=[
        # Read-only mount
        ("/host/config", "/etc/app/config", "ro"),

        # Read-write mount
        ("/host/data", "/mnt/data", "rw"),
    ]
)

Port Forwarding

boxlite.BoxOptions(
    ports=[
        (8080, 80, "tcp"),      # HTTP
        (8443, 443, "tcp"),     # HTTPS
        (5432, 5432, "tcp"),    # PostgreSQL
        (53, 53, "udp"),        # DNS
    ]
)

Persistent Storage

# Ephemeral (default) - data lost on box removal
boxlite.BoxOptions(image="postgres")

# Persistent - data survives stop/restart via QCOW2 disk
boxlite.BoxOptions(
    image="postgres",
    disk_size_gb=20,  # 20 GB persistent disk
)

Examples Gallery

The examples/python/ directory contains categorized examples:

1. run_simplebox.py - Foundation Patterns

Demonstrates core BoxLite features:

• Basic command execution with results
• Separate stdout/stderr handling
• Environment variables and working directory
• Error handling and exit codes
• Multiple commands in same box
• Data processing pipeline

View source

2. run_codebox.py - AI Code Execution

Secure Python code execution for AI agents:

• Basic code execution
• Dynamic package installation
• Data processing (AI agent use case)
• Isolation demonstration

View source

3. automate_with_playwright.py - Browser Automation

Browser automation with Playwright:

• Basic Chromium setup
• Custom browser configurations (Firefox, WebKit)
• Cross-browser testing patterns
• Integration examples

View source

4. automate_desktop.py - Desktop Automation

Desktop interaction for agent workflows:

• 14 desktop functions (mouse, keyboard, screenshots)
• Screen size detection
• Workflow automation
• GUI interaction patterns

View source

5. manage_lifecycle.py - Box Lifecycle Management

Managing box state:

• Stop and restart operations
• State persistence
• Data persistence verification
• Resource cleanup

View source

6. list_boxes.py - Runtime Introspection

Enumerate and inspect boxes:

• List all boxes with status
• Display box metadata (ID, name, state, resources)
• Filter by status

View source

7. share_across_processes.py - Multi-Process Operations

Cross-process box management:

• Reattach to running boxes from different processes
• Restart stopped boxes
• Multi-process runtime handling

View source

8. run_interactive_shell.py - Interactive Shells

Direct shell access:

• Interactive terminal sessions
• Terminal mode handling
• Simple container experience

View source

9. use_native_api.py - Low-Level API

Using the Rust API directly from Python:

• Default and custom runtime initialization
• Resource limits (CPU, memory, volumes, ports)
• Box information retrieval
• Streaming execution

View source

Metrics & Monitoring

Runtime Metrics

Get aggregate metrics across all boxes:

runtime = boxlite.Boxlite.default()
metrics = runtime.metrics()

print(f"Boxes created: {metrics.boxes_created}")
print(f"Boxes destroyed: {metrics.boxes_destroyed}")
print(f"Total exec calls: {metrics.total_exec_calls}")

RuntimeMetrics Fields:

• boxes_created: int - Total boxes created
• boxes_destroyed: int - Total boxes destroyed
• total_exec_calls: int - Total command executions
• active_boxes: int - Currently running boxes

Box Metrics

Get per-box resource usage:

box = runtime.create(boxlite.BoxOptions(image="alpine"))
metrics = await box.metrics()

print(f"CPU time: {metrics.cpu_time_ms}ms")
print(f"Memory: {metrics.memory_usage_bytes / (1024**2):.2f} MB")
print(f"Network sent: {metrics.network_bytes_sent}")
print(f"Network received: {metrics.network_bytes_received}")

BoxMetrics Fields:

• cpu_time_ms: int - Total CPU time in milliseconds
• memory_usage_bytes: int - Current memory usage
• network_bytes_sent: int - Total bytes sent
• network_bytes_received: int - Total bytes received

Error Handling

Exception Types

from boxlite import BoxliteError, ExecError, TimeoutError, ParseError

BoxliteError - Base exception for all BoxLite errors

ExecError - Command execution failed

TimeoutError - Operation timed out

ParseError - Failed to parse output

Common Error Patterns

import boxlite

async def safe_execution():
    try:
        async with boxlite.SimpleBox(image="python:slim") as box:
            result = await box.exec("python", "script.py")

            # Check exit code
            if result.exit_code != 0:
                print(f"Command failed: {result.stderr}")

    except boxlite.BoxliteError as e:
        # Handle BoxLite-specific errors
        print(f"BoxLite error: {e}")
    except Exception as e:
        # Handle other errors
        print(f"Unexpected error: {e}")

Troubleshooting

Installation Issues

Problem: pip install boxlite fails

Solutions:

• Ensure Python 3.10+: python --version
• Update pip: pip install --upgrade pip
• Check platform support (macOS ARM64, Linux x86_64/ARM64 only)

Runtime Errors

Problem: "KVM not available" error on Linux

Solutions:

# Check if KVM is loaded
lsmod | grep kvm

# Check if /dev/kvm exists
ls -l /dev/kvm

# Add user to kvm group (may require logout/login)
sudo usermod -aG kvm $USER

Problem: "Hypervisor.framework not available" on macOS

Solutions:

• Ensure macOS 12+ (Monterey or later)
• Verify Apple Silicon (ARM64) - Intel Macs not supported
• Check System Settings → Privacy & Security → Developer Tools

Image Pull Failures

Problem: "Failed to pull image" error

Solutions:

• Check internet connectivity
• Verify image name and tag exist: docker pull <image>
• For private images, pass image_registries=[boxlite.ImageRegistry(...)] when creating boxlite.Options

Performance Issues

Problem: Box is slow or unresponsive

Solutions:

# Increase resource limits
boxlite.BoxOptions(
    cpus=4,          # More CPUs
    memory_mib=4096, # More memory
)

# Check metrics
metrics = await box.metrics()
print(f"Memory usage: {metrics.memory_usage_bytes / (1024**2):.2f} MB")
print(f"CPU time: {metrics.cpu_time_ms}ms")

Debug Logging

Enable debug logging to troubleshoot issues:

# Set RUST_LOG environment variable
RUST_LOG=debug python script.py

Log levels: trace, debug, info, warn, error

Contributing

We welcome contributions to the Python SDK!

Development Setup

# Clone repository
git clone https://github.com/boxlite-ai/boxlite.git
cd boxlite

# Initialize submodules
git submodule update --init --recursive

# Build Python SDK in development mode
make dev:python

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest sdks/python/tests/

Building Wheels

# Build portable wheel
make dist:python

Further Documentation

• BoxLite Main README - Project overview
• Architecture Documentation - How BoxLite works
• Getting Started Guide - Installation and setup
• How-to Guides - Practical guides
• API Reference - Complete API documentation

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.