Skip to main content

System Requirements

BoxLite requires a platform with hardware virtualization support:
PlatformArchitectureRequirements
macOSApple SiliconmacOS 12+ (Monterey or later)
Linuxx86_64KVM enabled (/dev/kvm accessible)
LinuxARM64KVM enabled (/dev/kvm accessible)
Windows (WSL2)x86_64WSL2 with KVM support
macOS Intel (x86_64) is not supported due to Hypervisor.framework stability issues.

Verify Virtualization Support

# Check macOS version (should be 12+)
sw_vers

# Check architecture (should be arm64)
uname -m

No Daemon Required

Unlike Docker, BoxLite doesn’t require a daemon process. It’s an embeddable library that runs directly in your application.

Choose Your SDK

SDKStatusBest For
PythonStable (v0.4.4)AI agents, scripting, rapid prototyping
Node.jsv0.1.6Web services, TypeScript projects
RustNativePerformance-critical, embedded systems
Cv0.2.0C/C++ applications, system integration
GoComing soon

Next Steps

Learn More

Get Help

Troubleshooting

Installation Issues

Problem: pip install boxlite fails Solutions:
  • Verify Python 3.10+: python --version
  • Update pip: pip install --upgrade pip
  • Check platform support (macOS ARM64, Linux x86_64/ARM64 only)

Runtime Issues

Problem: “KVM not available” error on Linux Solutions:
# Check KVM module
lsmod | grep kvm

# Load KVM module
sudo modprobe kvm kvm_intel  # or kvm_amd

# Check /dev/kvm permissions
ls -l /dev/kvm
sudo chmod 666 /dev/kvm  # or add user to kvm group
Problem: Box fails to start Solutions:
  • Check disk space: df -h ~/.boxlite
  • Enable debug logging: RUST_LOG=debug python script.py
  • Verify image name: Try docker pull <image> to test
  • Check hypervisor: Ensure KVM (Linux) or Hypervisor.framework (macOS) is available

Performance Issues

Problem: Box is slow Solutions:
# Increase resource limits
boxlite.BoxOptions(
    cpus=4,          # More CPUs
    memory_mib=4096, # More memory
)

# Check metrics
metrics = await box.metrics()
print(f"Memory: {metrics.memory_usage_bytes / (1024**2):.2f} MB")
For more troubleshooting help, see FAQ & Troubleshooting.