Skip to main content
Complete reference for BoxLite APIs, configuration, and error handling.

​
SDK API References

Complete API documentation for each SDK:
SDKDescription
PythonAsync/sync API, box types, metrics
Node.jsTypeScript definitions, box types, CDP endpoints
RustCore runtime, stream APIs, security options
CFFI bindings, JSON API, callback streaming

Python SDK

Async and sync APIs, box types, code execution, metrics. Python 3.10+.

Node.js SDK

TypeScript definitions, box types, CDP endpoints for browser automation.

Rust SDK

Core runtime, stream APIs, security options. Native performance.

C SDK

FFI bindings, JSON API, callback streaming for system-level integration.

​
Quick Reference

​
Python API

For complete Python API documentation, see Python API Reference. Key Classes:
ClassDescription
BoxliteMain runtime for creating and managing boxes
BoxHandle to a running or stopped box
SimpleBoxContext manager for basic execution
CodeBoxSpecialized box for Python code execution
BrowserBoxBox configured for browser automation
ComputerBoxBox with desktop automation capabilities
InteractiveBoxBox for interactive shell sessions

​
Node.js API

For complete Node.js API documentation, see Node.js API Reference. Key Classes:
ClassDescription
SimpleBoxBasic container for command execution
CodeBoxPython code execution sandbox
BrowserBoxBrowser automation with CDP endpoint
ComputerBoxDesktop automation (14 methods)
InteractiveBoxPTY terminal sessions

​
Rust API

For complete Rust API documentation, see Rust API Reference. Core Types: 
use boxlite::{
    BoxliteRuntime,  // Main runtime
    BoxOptions,       // Box configuration
    LiteBox,          // Box handle
    BoxCommand,       // Command builder
    RootfsSpec,       // Rootfs specification
    VolumeSpec,       // Volume mount specification
    PortSpec,         // Port forwarding specification
};

​
C API

For complete C API documentation, see C API Reference. Functions:
FunctionDescription
boxlite_runtime_newCreate runtime instance
boxlite_create_boxCreate a new box
boxlite_executeRun command with streaming
boxlite_stop_boxStop and free box

​
SDK Feature Comparison

FeaturePythonNode.jsRustC
Async APIYesYesYesCallback-based
Sync APIYes (greenlet)NoYes (blocking)Yes
SimpleBoxYesYesYesYes
CodeBoxYesYesNoNo
BrowserBoxYesYesNoNo
ComputerBoxYesYesNoNo
InteractiveBoxYesYesNoNo
Streaming I/OYesYesYesYes
MetricsYesYesYesYes
Type SafetyType hintsTypeScriptNativeManual

​
Configuration Reference

For complete BoxOptions parameter documentation, see the SDK-specific pages:

​
Runtime Options

​
home_dir: str

Base directory for BoxLite runtime data. Default: ~/.boxlite Override: Set BOXLITE_HOME environment variable Structure: 
~/.boxlite/
├── images/       # OCI image cache (blobs, index.json)
├── boxes/        # Per-box data (config.json, disk.qcow2)
├── init/         # Shared guest rootfs
├── logs/         # Runtime logs
├── gvproxy/      # Network backend binaries
├── lock          # Filesystem lock file
└── db/           # SQLite databases (boxes.db, images.db)

​
Environment Variables

VariableDefaultDescription
BOXLITE_HOME~/.boxliteOverride runtime home directory
RUST_LOG-Debug logging level (trace, debug, info, warn, error)
BOXLITE_TMPDIRSystem tempOverride temporary directory
# Example: enable debug logging
RUST_LOG=debug python script.py

# Example: module-specific logging
RUST_LOG=boxlite::runtime=debug python script.py

​
Error Codes & Handling

For detailed error types and handling patterns, see the SDK-specific error pages:

​
File Formats

​
QCOW2 Disk Images

BoxLite uses QCOW2 (QEMU Copy-On-Write version 2) for persistent disks. Location: ~/.boxlite/boxes/{box-id}/disk.qcow2 Features:
  • Thin provisioning (sparse allocation)
  • Copy-on-write snapshots
  • Compression support
Tools: 
# Inspect QCOW2 image
qemu-img info ~/.boxlite/boxes/{box-id}/disk.qcow2

# Convert to raw (if needed)
qemu-img convert -f qcow2 -O raw disk.qcow2 disk.raw

​
OCI Image Cache

BoxLite caches OCI images at the layer level for fast starts. Location: ~/.boxlite/images/ Structure: 
~/.boxlite/images/
├── blobs/
│   └── sha256/
│       ├── abc123...  # Layer blob
│       ├── def456...  # Layer blob
│       └── ...
└── index.json         # Image index
Blob-level deduplication across images means shared base layers (e.g., python:3.11 and python:3.12) are stored only once.
Clearing Cache: 
# Clear all cached images
rm -rf ~/.boxlite/images/*

# Images will be re-pulled on next use

​
Box Configuration

Box metadata and state are stored as JSON. Location: ~/.boxlite/boxes/{box-id}/config.json Example: 
{
  "id": "01JJNH8...",
  "image": "python:slim",
  "cpus": 2,
  "memory_mib": 1024,
  "volumes": [
    {
      "host_path": "/host/data",
      "guest_path": "/mnt/data",
      "read_only": true
    }
  ],
  "ports": [
    {
      "host_port": 8080,
      "guest_port": 80,
      "protocol": "tcp"
    }
  ],
  "created_at": "2025-01-15T10:30:00Z",
  "status": "running"
}
Do not manually edit box configuration files. They are managed by BoxLite and manual changes may cause unexpected behavior.

​
SQLite Databases

BoxLite uses SQLite for metadata persistence. Locations:
  • ~/.boxlite/db/boxes.db - Box registry and metadata
  • ~/.boxlite/db/images.db - Image cache index
Tools: 
# Inspect database
sqlite3 ~/.boxlite/db/boxes.db ".tables"
sqlite3 ~/.boxlite/db/boxes.db "SELECT * FROM boxes;"

# Backup
cp ~/.boxlite/db/boxes.db ~/backup/boxes.db.backup
Do not manually modify the SQLite databases. Data corruption may result. Corruption recovery: delete and recreate from box config files.