Skip to main content

​
Installation

Add BoxLite to your Cargo.toml: 
[dependencies]
boxlite = { git = "https://github.com/boxlite-labs/boxlite" }
tokio = { version = "1", features = ["full"] }
futures = "0.3"

​
Basic Execution

1

Create a file src/main.rs

use boxlite::{BoxliteRuntime, BoxOptions, BoxCommand, RootfsSpec};
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create runtime
    let runtime = BoxliteRuntime::default_runtime();

    // Create box
    let options = BoxOptions {
        rootfs: RootfsSpec::Image("alpine:latest".into()),
        ..Default::default()
    };
    let (_, litebox) = runtime.create(options)?;

    // Execute command
    let mut execution = litebox
        .exec(BoxCommand::new("echo").arg("Hello from BoxLite!"))
        .await?;

    // Stream stdout
    let mut stdout = execution.stdout().unwrap();
    while let Some(line) = stdout.next().await {
        println!("{}", line);
    }

    Ok(())
}
2

Run it

cargo run

​
From Source (Development)

For contributing or local development:
1

Clone the repository

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

Initialize submodules

This step is critical! The build will fail without submodules.
git submodule update --init --recursive
3

Install platform dependencies

make setup
4

Build and test

# Build
cargo build

# Run tests
cargo test
See CONTRIBUTING.md for detailed build instructions.

​
Next Steps

Architecture Documentation

Understand how BoxLite works — Core components (Runtime, LiteBox, VMM, Portal), Image management and rootfs preparation, Host-guest communication protocol.

Rust API Reference

Complete Rust API reference documentation.