Skip to main content
BoxLite ships with nine Python examples that cover all major use cases. Each example is a standalone script you can run after building the Python SDK.

​
Prerequisites

1

Clone the repository

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

Build the Python SDK

make dev:python

​
Examples

SimpleBox

Foundation patterns — command execution, stdout/stderr separation, environment variables, working directories, and error handling.

CodeBox

AI code execution — securely run AI-generated Python code with automatic package installation.

BrowserBox

Browser automation — web scraping, end-to-end testing, and screenshot generation.

ComputerBox

Desktop automation — screenshots, mouse clicks, text input, and 9+ additional functions.

Lifecycle Management

Box state management — start, stop, restart, and inspect box lifecycle.

List Boxes

Runtime introspection — enumerate and inspect all active boxes.

Cross Process

Multi-process operations — share boxes across processes.

InteractiveBox

Interactive shells — TTY sessions with stdin/stdout streaming.

Native Example

Low-level Rust API — direct access to the BoxLite Rust runtime.

​
1. SimpleBox — Foundation Patterns

File: examples/python/simplebox_example.py Demonstrates core BoxLite features: basic command execution, stdout/stderr separation, environment variables, working directory configuration, error handling, and running multiple commands in the same box. 
python examples/python/simplebox_example.py
Key Patterns: 
async with boxlite.SimpleBox(image="python:alpine") as box:
    # Execute command
    result = await box.exec("ls", "-lh", "/")
    print(result.stdout)

    # With environment variables
    result = await box.exec(
        "python", "-c", "import os; print(os.getenv('MY_VAR'))",
        env=[("MY_VAR", "value")]
    )

​
2. CodeBox — AI Code Execution

File: examples/python/codebox_example.py Secure Python code execution for AI agents. CodeBox provides automatic package installation and a safe execution sandbox. 
python examples/python/codebox_example.py
Key Patterns: 
async with boxlite.CodeBox() as codebox:
    # Install packages automatically
    await codebox.install_package("requests")

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

​
3. BrowserBox — Browser Automation

File: examples/python/browserbox_example.py Browser automation in an isolated VM. Use cases include web scraping, end-to-end testing, browser automation, and screenshot generation. 
python examples/python/browserbox_example.py

​
4. ComputerBox — Desktop Automation

File: examples/python/computerbox_example.py Full desktop automation with a rich set of interaction functions. 
python examples/python/computerbox_example.py
Available Functions:
FunctionDescription
screenshot()Capture the screen
left_click()Left mouse click
right_click()Right mouse click
double_click()Double mouse click
type_text(text)Type text input
get_screen_size()Get screen dimensions
move_mouse(x, y)Move cursor to position
+ 9 moreAdditional interaction functions

​
5. Lifecycle Management

File: examples/python/lifecycle_example.py Demonstrates box state management including starting, stopping, restarting, and inspecting box state. 
python examples/python/lifecycle_example.py

​
6. List Boxes

File: examples/python/list_boxes_example.py Runtime introspection — enumerate and inspect all active boxes. 
python examples/python/list_boxes_example.py

​
7. Cross Process

File: examples/python/cross_process_example.py Multi-process operations — share and access boxes across different processes. 
python examples/python/cross_process_example.py

​
8. InteractiveBox

File: examples/python/interactivebox_example.py Interactive shell sessions with TTY support. 
python examples/python/interactivebox_example.py

​
9. Native Example

File: examples/python/native_example.py Low-level access to the BoxLite Rust API from Python. 
python examples/python/native_example.py

​
Customizing Examples

All examples can be customized by editing the source files. Here are the most common modifications.

​
Change the Image

async with boxlite.SimpleBox(image="ubuntu:22.04") as box:
    # Use Ubuntu instead of the default
    result = await box.exec("cat", "/etc/os-release")

​
Add Resources

async with boxlite.SimpleBox(
    image="python:slim",
    cpus=2,
    memory_mib=2048
) as box:
    # More CPU and memory for intensive workloads
    result = await box.exec("python", "heavy_computation.py")

​
Mount Volumes

async with boxlite.SimpleBox(
    image="python:slim",
    volumes=[("/host/data", "/mnt/data", "ro")]
) as box:
    # Access host data inside the box
    result = await box.exec("ls", "/mnt/data")
For more advanced patterns like networking, port forwarding, debugging, and resource tuning, see the AI Agent Integration guide or the SDK Reference.