SDK Reference

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
};

~/.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)

# Example: enable debug logging
RUST_LOG=debug python script.py

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

# 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

~/.boxlite/images/
├── blobs/
│   └── sha256/
│       ├── abc123...  # Layer blob
│       ├── def456...  # Layer blob
│       └── ...
└── index.json         # Image index

# Clear all cached images
rm -rf ~/.boxlite/images/*

# Images will be re-pulled on next use

{
  "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"
}

# 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