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.images holds the images a runtime can boot from: the local cache on an embedded runtime, the server's catalog on Boxlite.rest(...). The same code runs against either; pull is local only (a REST runtime pulls when a box is created) and usage, create_alias and delete_alias are REST only.

runtime = boxlite.Boxlite.default()

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

detail = await runtime.images.get("docker.io/library/alpine")
print(detail.aliases, [version.digest for version in detail.versions])
await runtime.images.remove("docker.io/library/alpine")

pull fills a local cache ahead of time. A REST runtime refuses it with UnsupportedError, because creating a box there pulls the image:

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

See the Python reference for each method on each runtime.

Private Registry Logins

On Boxlite.rest(...), runtime.images.registries manages the logins the server pulls private images with. The password goes up once and is never returned. A local runtime raises UnsupportedError: pass image_registries to boxlite.Options instead.

runtime = boxlite.Boxlite.rest(boxlite.BoxliteRestOptions.from_env())

login = await runtime.images.registries.create(
    registry_host="ghcr.io",
    repository_prefix="acme/",  # leave out for the whole registry
    username="acme-bot",
    password=os.environ["GHCR_TOKEN"],
)
box = await runtime.create(boxlite.BoxOptions(image="ghcr.io/acme/private-app:1"))
...
await runtime.images.registries.remove(login.id)  # refused while a box pulls through it

See the Python reference.

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 (default: mode="disabled", private)

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

NotFoundError, InvalidStateError, UnsupportedError, … - A failure the runtime reported, one class per kind, each with a code such as not_found. Every one is also a RuntimeError. The full list is in the Python reference.

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; on Boxlite.rest(...), add a login with runtime.images.registries.create(...)

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.