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

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

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

• async get_info(box_id: str) -> Optional[BoxInfo] Get current metadata for a box by ID or name

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

• async 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 = await runtime.create(boxlite.BoxOptions(image="alpine:latest"))

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

# List all boxes
boxes = await runtime.list_info()
for info in boxes:
    print(f"{info.id}: {info.state.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)

Remote BoxLite server (REST)

Connect to a remote BoxLite server instead of the local runtime. Auth uses a credential class: ApiKeyCredential is a concrete implementation of the Credential ABC.

from boxlite import Boxlite, BoxliteRestOptions, ApiKeyCredential

rt = Boxlite.rest(
    BoxliteRestOptions(
        url="http://localhost:8100",
        credential=ApiKeyCredential("your-api-key"),
    )
)
boxes = await rt.list_info()

# Env discovery — returns None when BOXLITE_API_KEY is unset:
cred = ApiKeyCredential.from_env()

# Or read everything (BOXLITE_REST_URL + BOXLITE_API_KEY) from the env:
rt = Boxlite.rest(BoxliteRestOptions.from_env())

isinstance(ApiKeyCredential(k), Credential) is True (registered as a virtual subclass), so code can type-check against the Credential ABC and accept any future credential kind unchanged.

Routing prefix (vendor-agnostic)

Box-scoped requests resolve to {url}/v1/{prefix}/…. The v1 segment is hardcoded; path_prefix is an opaque, deployment- defined routing value that the server tells the client to use via Principal.path_prefix from GET /v1/me. The slot's semantics are vendor-specific: boxlite cloud uses it for the organization id; another deployment may use a workspace name, a region+team pair, or any other multi-segment value such as us-east/team-42.

rt = Boxlite.rest(
    BoxliteRestOptions(
        url="https://api.boxlite.ai",
        credential=ApiKeyCredential("blk_live_…"),
        path_prefix="acme",  # → requests hit /v1/acme/boxes
    )
)

When path_prefix is unset or empty, the client builds URLs without the segment (/v1/boxes/…) — the canonical shape for single-tenant deployments such as the local boxlite serve reference server.

The CLI captures Principal.path_prefix at login and caches it under the active profile, so subsequent boxlite commands route correctly without an extra flag.

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 - Container disk size in GB, never smaller than the image (default: None, the image size)
• working_dir: str - Working directory in container (default: "/root")
• env: List[Tuple[str, str]] - Environment variables as (key, value) pairs
• volumes: List[Tuple | Dict] - Volume mounts; a tuple is a host bind, a dict takes managed_volume (id or name) or host_path
  • read_only is a bool and defaults to False
• network: NetworkSpec | None - Structured network configuration
• ports: List[Tuple | Dict] - Local TCP forwarding; omit host_port in a dict for automatic allocation
  • Protocol: "tcp"; UDP is rejected
  • Portable local/remote code uses box.network.tunnel(port); each tunnel is a prepared one-shot tunnel; call forward() for a listener
• secrets: List[Secret] - Host-side HTTPS secret substitution rules
• advanced: AdvancedBoxOptions | None - Expert-only container options
  • capabilities.add: List[str] - Capabilities added to BoxLite's baseline
  • capabilities.drop: List[str] - Capabilities removed from the resulting set
• auto_delete: int | None - 0 keeps the box after stop; above 0, a REST runtime deletes it that many seconds after stop and a local runtime at stop. Default None keeps the runtime's default (auto_remove locally)
• auto_remove: bool - Deprecated: use auto_delete. Auto cleanup after stop (default: True)

NetworkSpec uses:

• outbound: OutboundNetworkSpec - Guest egress policy
• inbound: InboundNetworkSpec - Service access policy

The pre-split form NetworkSpec(mode=..., allow_net=...) still works and configures the outbound direction, positionally as well as by keyword. Supplying it together with outbound raises ValueError. spec.mode and spec.allow_net remain readable as views onto outbound.

allow_net restricts both TCP and UDP egress. Hostname entries are enforced by inspecting TLS SNI / HTTP Host, which only TCP carries, so an allow_net holding only hostnames denies all UDP egress — add the IP or CIDR to keep UDP open. A host matched by a configured Secret is additionally reachable on port 443 without a rule of its own, so allow_net is not the only egress gate. The connection is dialed by name, and under a non-empty allow_net an answer in a private, loopback or CGNAT range is refused unless an IP or CIDR rule covers it.

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 disk
    env=[
        ("POSTGRES_PASSWORD", "secret"),
        ("POSTGRES_DB", "mydb"),
    ],
    volumes=[
        ("/host/data", "/mnt/data", True),  # Read-only mount
    ],
    ports=[
        (5432, 5432, "tcp"),  # PostgreSQL
    ],
    network=boxlite.NetworkSpec(
        outbound=boxlite.OutboundNetworkSpec(
            mode="enabled",
            allow_net=["api.openai.com"],
        ),
        inbound=boxlite.InboundNetworkSpec(mode="disabled"),
    ),
    advanced=boxlite.AdvancedBoxOptions(
        capabilities=boxlite.ContainerCapabilities(
            add=["NET_ADMIN"],
            drop=["NET_RAW"],
        ),
    ),
    secrets=[
        boxlite.Secret(
            name="openai",
            value="sk-...",
            hosts=["api.openai.com"],
        ),
    ],
)
box = await runtime.create(options)

Box Handle

boxlite.Box

Handle to a running or stopped box.

Properties:

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

Methods:

• exec(command, args=None, env=None, tty=False, user=None, timeout_secs=None, cwd=None) -> Execution Execute a command in the box (async); args is a list

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

• info() -> Awaitable[BoxInfo] Get box metadata (async)

  • info.network contains NetworkInfo when network metadata is available
  • When info.network is not None, published_ports is None when this handle does not know the bindings, [] when there are no active publications, or a list of named PublishedPort objects
  • bindings become available after this handle starts or reattaches the box

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

Example:

box = await 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.state.status}")

# Stop; by default this also removes the box
await box.stop()

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) from a low-level Box
low_level_box = await runtime.create(boxlite.BoxOptions(image="python:slim"))
execution = await low_level_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 = await runtime.create(boxlite.BoxOptions(image="alpine"))
try:
    await box.exec("command")
finally:
    await box.stop()  # also removes the box by default

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", True),
        # Read-write mount
        ("/host/data", "/mnt/data", False),
    ]
)

Port Forwarding

boxlite.BoxOptions(
    ports=[
        (8080, 80, "tcp"),  # Fixed host port
        {"guest_port": 3000},  # OS-selected host port
    ]
)

Persistent Storage

# Default - the box and its disk are removed when it stops
boxlite.BoxOptions(image="postgres")

# Kept - the box and its QCOW2 disk survive stop/restart
boxlite.BoxOptions(
    image="postgres",
    disk_size_gb=20,  # 20 GB disk
    auto_delete=0,    # keep the box after stop
)

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 = await 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 = await 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
• Concepts - How BoxLite works
• Getting Started Guide - Installation and setup
• Guides - Practical guides
• API Reference - Complete API documentation

License

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