Skip to main content
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)

​
Quick Start

1

Clone the repository

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

Initialize submodules

git submodule update --init --recursive
3

Install platform dependencies

make setup
4

Build the Python SDK for local development

make dev:python

​
Makefile Targets

BoxLite uses a Makefile to orchestrate all builds. Below is a complete reference of available targets.
TargetDescription
make setupInstall platform-specific dependencies
make guestCross-compile guest binary (musl static)
make shimBuild boxlite-shim binary
make runtimeBuild complete BoxLite runtime
make dev:pythonLocal Python SDK development
make dist:pythonBuild portable Python wheels
make cleanClean build artifacts

​
Platform Support

ArchitectureHypervisor
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.

​
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

1

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.
2

Build the shim binary

The shim is the host-side process that manages the VM:
make shim
This runs scripts/build/shim.sh.
3

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

​
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

BoxLite requires Rust 1.75 or newer. Check your version with:
rustc --version
Update with:
rustup update stable
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.
BoxLite requires macOS 12 (Monterey) or later for Hypervisor.framework support. Check your version:
sw_vers
If submodules fail to initialize, try a clean clone:
git clone --recursive https://github.com/boxlite-labs/boxlite.git