Building from Source

This guide walks you through building BoxLite from source on macOS (Apple Silicon) and Linux (x86_64 / ARM64).

Prerequisites

Rust 1.75+ (stable toolchain)
macOS (Apple Silicon) or Linux (x86_64/ARM64) with KVM
Python 3.10+ (for Python SDK development)
Node.js 18+ (for Node.js SDK development)

Quick Start

Clone the repository

git clone https://github.com/boxlite-ai/boxlite.git
cd boxlite

Initialize submodules

git submodule update --init --recursive

Install platform dependencies

make setup

Build the Python SDK for local development

make dev:python

Verify your build

Confirm the SDK installed correctly:

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

You should see a version string confirming the SDK installed correctly.

Makefile Targets

BoxLite uses a Makefile to orchestrate all builds. Below is a complete reference of available targets.

Target	Description
`make setup`	Install platform-specific dependencies
`make guest`	Cross-compile guest binary (musl static)
`make shim`	Build boxlite-shim binary
`make runtime`	Build complete BoxLite runtime
`make dev:python`	Local Python SDK development
`make dist:python`	Build portable Python wheels
`make dev:node`	Local Node.js SDK development
`make dist:node`	Build portable Node.js package
`make clean`	Clean build artifacts

Platform Support

macOS
Linux (x86_64)
Linux (ARM64)

Architecture	Hypervisor
ARM64 (Apple Silicon)	Hypervisor.framework

macOS builds use Apple’s native Hypervisor.framework. Only Apple Silicon (ARM64) is supported. Intel Macs are not supported.The platform setup script is located at scripts/setup/macos.sh.

Architecture	Hypervisor
x86_64	KVM

Requires KVM support. Verify with:

ls -l /dev/kvm
grep -E 'vmx|svm' /proc/cpuinfo

The platform setup script is located at scripts/setup/ubuntu.sh.

Architecture	Hypervisor
ARM64	KVM

Requires KVM support on ARM64 hardware. The setup scripts for Linux ARM64 are the same as x86_64 (scripts/setup/ubuntu.sh).

Build Scripts

Build scripts are located in the scripts/ directory:

scripts/
├── setup/              # Platform-specific setup
│   ├── macos.sh
│   ├── ubuntu.sh
│   ├── manylinux.sh
│   └── musllinux.sh
├── build/              # Build scripts
│   ├── guest.sh        # Guest binary (cross-compile)
│   ├── shim.sh         # Shim binary
│   └── build-runtime.sh
├── package/            # Packaging scripts
└── common.sh           # Shared utilities

Building Individual Components

Build the guest binary

The guest binary is cross-compiled as a static musl binary:

make guest

This runs scripts/build/guest.sh under the hood.

Build the shim binary

The shim is the host-side process that manages the VM:

make shim

This runs scripts/build/shim.sh.

Build the complete runtime

Build all components together:

make runtime

This runs scripts/build/build-runtime.sh, which builds the guest, shim, and runtime library.

Building Python Wheels

To build distributable Python wheels (for publishing or CI):

make dist:python

For local development (editable install):

make dev:python

Building the Node.js Package

To build the Node.js package for publishing:

make dist:node

For local development:

make dev:node

Cleaning Build Artifacts

make clean

This removes all compiled binaries, intermediate build files, and generated artifacts.

Debugging Build Issues

If you encounter build failures, enable debug logging to get more detail:

RUST_LOG=debug make runtime

Common Issues

Rust version too old

BoxLite requires Rust 1.75 or newer. Check your version with:

rustc --version

Update with:

rustup update stable

KVM not available (Linux)

Verify KVM is accessible:

ls -l /dev/kvm

If the device does not exist, enable hardware virtualization in your BIOS/UEFI settings. If it exists but is not accessible, check permissions:

sudo usermod -aG kvm $USER

Log out and back in for the group change to take effect.

macOS version too old

BoxLite requires macOS 12 (Monterey) or later for Hypervisor.framework support. Check your version:

sw_vers

Submodule initialization failed

If submodules fail to initialize, try a clean clone:

git clone --recursive https://github.com/boxlite-ai/boxlite.git

Getting Started

Tutorials

Guides

SDK Reference

Architecture

Resources

Development

Prerequisites

Quick Start

Makefile Targets

Platform Support

Build Scripts

Building Individual Components

Building Python Wheels

Building the Node.js Package

Cleaning Build Artifacts

Debugging Build Issues

Common Issues

​Prerequisites

​Quick Start

​Makefile Targets

​Platform Support

​Build Scripts

​Building Individual Components

​Building Python Wheels

​Building the Node.js Package

​Cleaning Build Artifacts

​Debugging Build Issues

​Common Issues

Prerequisites

Quick Start

Makefile Targets

Platform Support

Build Scripts

Building Individual Components

Building Python Wheels

Building the Node.js Package

Cleaning Build Artifacts

Debugging Build Issues

Common Issues