Installation

# Install protoc (choose one per platform)
# macOS (Homebrew)
brew install protobuf

# Ubuntu / Debian
sudo apt-get update && sudo apt-get install -y protobuf-compiler

# Verify the version (must be >= 3.12)
protoc --version
# Expected output, e.g.: libprotoc 3.21.12

pip install boxlite

# hello_boxlite.py — run directly: python hello_boxlite.py
import asyncio
import boxlite

async def main() -> None:
    try:
        # SimpleBox is an async context manager; it stops and cleans up automatically on exit
        async with boxlite.SimpleBox(image="python:slim") as box:
            result = await box.exec("python", "-c", "print('Hello from BoxLite!')")
            print("stdout:", result.stdout.strip())
            print("exit_code:", result.exit_code)  # a non-zero exit code does not raise; check it yourself
    except RuntimeError as exc:
        # Image pull failure / missing virtualization raises a standard RuntimeError (not BoxliteError)
        print(f"Failed to start: {exc}")

if __name__ == "__main__":
    asyncio.run(main())

# verify.py
import boxlite

print(boxlite.__version__)  # Prints the installed package version (the latest published version)

npm install @boxlite-ai/boxlite

// hello.mjs — run directly: node hello.mjs (package is pure ESM)
import { SimpleBox } from "@boxlite-ai/boxlite";

async function main() {
  const box = new SimpleBox({ image: "alpine:latest" });
  try {
    const result = await box.exec("echo", "Hello from BoxLite!");
    console.log("stdout:", result.stdout.trim());
    console.log("exitCode:", result.exitCode); // check it yourself; a non-zero exit code does not raise
  } catch (err) {
    console.error("Failed to start:", err instanceof Error ? err.message : err);
  } finally {
    await box.stop();
  }
}

main();

# One-line install (Linux and macOS Apple Silicon), installs to $HOME/.local/bin/boxlite
curl -fsSL https://sh.boxlite.ai | sh

# Verify
boxlite --help

# Run a command
boxlite run python:slim python -c "print('Hello from BoxLite!')"

# Install both sync and orchestration capabilities at once
pip install "boxlite[sync,orchestration]"

# Pin a version and choose a custom install directory
curl -fsSL https://sh.boxlite.ai \
  | BOXLITE_VERSION=vX.Y.Z BOXLITE_INSTALL_DIR=/usr/local/bin sh

# Pin both the version and an independently attested digest
curl -fsSL https://sh.boxlite.ai \
  | BOXLITE_VERSION=vX.Y.Z \
    BOXLITE_EXPECTED_SHA256=<sha256-of-boxlite-cli-vX.Y.Z-target.tar.gz> sh

# Check the digest against the published sidecar
sha256sum -c "boxlite-cli-${VERSION}-${TARGET}.tar.gz.sha256"

# Verify the build provenance attestation (requires the GitHub CLI)
gh attestation verify "boxlite-cli-${VERSION}-${TARGET}.tar.gz" \
  --repo boxlite-ai/boxlite

curl -fsSL -o install.sh \
  "https://github.com/boxlite-ai/boxlite/releases/latest/download/install.sh"
curl -fsSL -o install.sh.sha256 \
  "https://github.com/boxlite-ai/boxlite/releases/latest/download/install.sh.sha256"
sha256sum -c install.sh.sha256
gh attestation verify install.sh --repo boxlite-ai/boxlite
sh ./install.sh

# Confirm the CPU supports virtualization
grep -E 'vmx|svm' /proc/cpuinfo   # any output means supported

# Confirm the KVM module is loaded and the device exists
lsmod | grep kvm
ls -l /dev/kvm

# Add the current user to the kvm group (requires re-login or newgrp to take effect)
sudo usermod -aG kvm $USER
newgrp kvm

# Install and confirm the version is >= 3.12
brew install protobuf           # macOS
sudo apt-get install -y protobuf-compiler   # Ubuntu/Debian
protoc --version                # must be >= 3.12

git submodule update --init --recursive   # required after cloning

pip install --upgrade boxlite
python -c "import boxlite; print(boxlite.__version__)"

RUST_LOG=debug python hello_boxlite.py
# Log levels: trace / debug / info / warn / error