Rust quickstart - BoxLite Documentation

Use the Rust crate boxlite to run a command in an isolated microVM sandbox within minutes, getting streaming output and an exit code without managing virtual machines, images, or networking yourself. This is the shortest path to safely executing untrusted code, AI-generated code, or third-party commands.

Prerequisites

The boxlite crate and a machine with hardware virtualization — see Installation for the supported platforms.
Rust 1.88 or newer (rustc --version to check).

Add the dependencies to your project:

# Three crates: boxlite itself + tokio async runtime + futures (for reading streaming output)
cargo add boxlite
cargo add tokio --features macros,rt-multi-thread
cargo add futures

Quick Example

Write the following into src/main.rs, then run cargo run. This code is standalone and includes the full imports, runtime initialization, and error propagation (? + Box<dyn Error>).

use boxlite::{BoxCommand, BoxOptions, BoxliteRuntime, RootfsSpec};
use futures::StreamExt; // provides .next() for the stdout stream

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Get the global default runtime (construction is synchronous; do not .await)
    let runtime = BoxliteRuntime::default_runtime();

    // 2. Configure a box based on the alpine image
    let options = BoxOptions {
        rootfs: RootfsSpec::Image("alpine:latest".into()),
        ..Default::default()
    };

    // 3. Create the box (pass None as name to let the runtime auto-name it). create/exec/stop are async
    let litebox = runtime.create(options, None).await?;
    println!("Created box: {}", litebox.id());

    // 4. Execute a command — note the method is exec (not run)
    let mut execution = litebox
        .exec(BoxCommand::new("echo").arg("Hello from BoxLite!"))
        .await?;

    // 5. Read stdout as a stream (each item is one line String)
    if let Some(mut stdout) = execution.stdout() {
        while let Some(line) = stdout.next().await {
            println!("{}", line);
        }
    }

    // 6. Wait for completion and check the exit code (a non-zero code does not error automatically; check it yourself)
    let result = execution.wait().await?;
    if !result.success() {
        eprintln!("Command exited with a non-zero code: {}", result.exit_code);
    }

    // 7. Cleanup: stop the box
    litebox.stop().await?;

    Ok(())
}

Expected output:

Created box: <box-id>
Hello from BoxLite!

Parameters and Returns (Core API)

`BoxliteRuntime` (runtime handle)

The constructors are synchronous fns (do not .await); only create / exec / remove and similar operations are async.

Method	Signature	Required	Description
`with_defaults`	`fn() -> BoxliteResult<Self>`	—	Build a new runtime instance with default options
`default_runtime`	`fn() -> &'static Self`	—	Get/create the global singleton runtime (simplest)
`new`	`fn(options: BoxliteOptions) -> BoxliteResult<Self>`	`options`	Build with a custom home_dir / image registries
`create`	`async fn(&self, options: BoxOptions, name: Option<String>) -> BoxliteResult<LiteBox>`	`options`, `name`	Create a box; `name=None` auto-names it
`get`	`async fn(&self, id_or_name: &str) -> BoxliteResult<Option<LiteBox>>`	`id_or_name`	Get an existing box by ID or name
`list_info`	`async fn(&self) -> BoxliteResult<Vec<BoxInfo>>`	—	List all boxes (newest first)
`remove`	`async fn(&self, id_or_name: &str, force: bool) -> BoxliteResult<()>`	`id_or_name`, `force`	Fully remove a box (called on the runtime, not `box.remove()`)
`metrics`	`async fn(&self) -> BoxliteResult<RuntimeMetrics>`	—	Aggregated runtime metrics

`LiteBox` (box handle)

Method	Signature	Description
`id`	`fn(&self) -> &BoxID`	Box identifier
`info`	`fn(&self) -> BoxInfo`	Box metadata (synchronous; does not trigger VM startup)
`start`	`async fn(&self) -> BoxliteResult<()>`	Explicit start (idempotent; `exec` calls it on demand)
`exec`	`async fn(&self, command: BoxCommand) -> BoxliteResult<Execution>`	Execute a command (the method is `exec`; there is no `run`)
`metrics`	`async fn(&self) -> BoxliteResult<BoxMetrics>`	Per-box metrics
`stop`	`async fn(&self) -> BoxliteResult<()>`	Stop the VM (can `start` again)

`BoxCommand` (command builder)

Chained construction; all methods return Self:

Method	Signature	Description
`new`	`fn(command: impl Into<String>) -> Self`	Create a command
`arg`	`fn(self, arg: impl Into<String>) -> Self`	Append a single argument
`args`	`fn(self, args: I) -> Self`	Append multiple arguments
`env`	`fn(self, key, val) -> Self`	Set an environment variable
`timeout`	`fn(self, timeout: Duration) -> Self`	Set an execution timeout
`working_dir`	`fn(self, dir) -> Self`	Set the working directory
`user`	`fn(self, user) -> Self`	Specify the user to run as (e.g. `"nobody"`, `"1000:1000"`)
`tty`	`fn(self, enable: bool) -> Self`	Enable a pseudo-terminal

`Execution` / `ExecResult` (execution handle and result)

Item	Type/signature	Description
`stdout()` / `stderr()`	`fn(&mut self) -> Option<ExecStdout>`	Take the output stream (once per box); implements `Stream<Item = String>`
`stdin()`	`fn(&mut self) -> Option<ExecStdin>`	Take stdin (write, then `drop` to send EOF)
`wait()`	`async fn(&self) -> BoxliteResult<ExecResult>`	Block until the process ends
`kill()` / `signal(i32)`	`async fn(&self) -> BoxliteResult<()>`	Send SIGKILL / an arbitrary signal
`ExecResult.exit_code`	`i32`	Exit code (0 = success)
`ExecResult.success()`	`fn -> bool`	Whether the exit code is 0

Important: the Rust core-layer ExecResult contains only exit_code (and error_message), not stdout/stderr; output must be read via the streaming stdout() / stderr() above. This differs from the C/Go/Python SDKs.

`BoxOptions` (common fields)

Field	Type	Default	Description
`rootfs`	`RootfsSpec`	`Image("alpine:latest")`	`Image(ref)` to pull an image, or `RootfsPath(path)` to use a prepared rootfs
`cpus`	`Option<u8>`	`None`	Number of vCPUs; passed through as `None`, in which case the runtime’s default VM size applies. Set it explicitly in production (see Compute resources)
`memory_mib`	`Option<u32>`	`None`	Memory in MiB; passed through as `None`, in which case the runtime’s default VM size applies. Set it explicitly in production
`env`	`Vec<(String, String)>`	`[]`	Environment variables
`volumes`	`Vec<VolumeSpec>`	`[]`	Volume mounts (see below)
`auto_delete`	`Option<u32>`	`None`	Seconds after a successful stop before deletion. `Some(0)` keeps the box; leave it unset to delete on stop

Mount a host directory (read_only is a bool, not a string):

use boxlite::{BoxOptions, RootfsSpec};
use boxlite::runtime::options::VolumeSpec;

let options = BoxOptions {
    rootfs: RootfsSpec::Image("alpine:latest".into()),
    volumes: vec![VolumeSpec {
        host_path: "<YOUR_PROJECT_PATH>".into(), // e.g. "/home/you/project"
        guest_path: "/app".into(),
        read_only: true, // true=read-only / false=read-write; do not use "ro"/"rw" strings
    }],
    ..Default::default()
};

Troubleshooting

Method `run` not found / `BoxliteError::Run`

error[E0599]: no method named `run` found for struct `LiteBox`

The method to execute a command is exec, not run. Likewise, the error enum has no BoxliteError::Run variant; the variant for a command execution failure is BoxliteError::Execution(String). When matching errors:

use boxlite::{BoxOptions, BoxliteError, BoxliteRuntime};

# async fn demo() -> Result<(), Box<dyn std::error::Error>> {
let runtime = BoxliteRuntime::with_defaults()?;
match runtime.create(BoxOptions::default(), None).await {
    Ok(litebox) => println!("created: {}", litebox.id()),
    Err(BoxliteError::Image(msg)) => eprintln!("image error: {}", msg),
    Err(BoxliteError::Execution(msg)) => eprintln!("execution error: {}", msg),
    Err(BoxliteError::Config(msg)) => eprintln!("config error: {}", msg),
    Err(e) => eprintln!("other error: {}", e),
}
# Ok(())
# }

A non-zero exit code was not reported as an error

Even when the command fails, execution.wait() still returns Ok(ExecResult): a non-zero exit code is not turned into an Err. Check it yourself:

let result = execution.wait().await?;
if !result.success() {
    eprintln!("Command failed, exit code: {}", result.exit_code);
}

Compile error: missing `StreamExt` / `.next()` not found

error[E0599]: no method named `next` found for struct `ExecStdout`

Reading the streaming output requires importing the futures::StreamExt trait, and the futures dependency must be present:

use futures::StreamExt; // .next() is unavailable without this line

cargo add futures

Mixing async and synchronous methods

error: `await` is only allowed inside `async` functions

BoxliteRuntime::default_runtime() / with_defaults() / new(), and litebox.id() / litebox.info(), are synchronous; do not .await them. Only create / start / exec / wait / stop / metrics are async.

Startup failure: no hardware virtualization (environment constraint)

On Linux without KVM (or a container/CI that does not pass through /dev/kvm), create / start fail:

engine reported an error: ... /dev/kvm ...

Linux: confirm /dev/kvm exists and the current user is in the kvm group (ls -l /dev/kvm).
macOS (Apple Silicon): uses Hypervisor.framework and does not need /dev/kvm; runs directly.
WSL2: enable nested virtualization and install KVM.

This kind of failure is an environment constraint; the process does not crash. Catch the Err with the match above to handle it cleanly.

The first run stalls while pulling the image

The first use of an image (such as alpine:latest) downloads it from a registry, which can be slow depending on the network; a failure usually surfaces as BoxliteError::Image(...) or BoxliteError::Network(...), which is retryable.

Next Steps

Run any language’s code inside a box, mount volumes, or configure networking: replace BoxCommand with your target command and RootfsSpec::Image(...) with the image you need (such as python:3.11-slim).
For stronger isolation, configure the security options under BoxOptions.advanced.
Other languages: see the Python quickstart, the Node.js quickstart, and the Go quickstart.

​Prerequisites

​Quick Example

​Parameters and Returns (Core API)

​BoxliteRuntime (runtime handle)

​LiteBox (box handle)

​BoxCommand (command builder)

​Execution / ExecResult (execution handle and result)

​BoxOptions (common fields)

​Troubleshooting

​Method run not found / BoxliteError::Run

​A non-zero exit code was not reported as an error

​Compile error: missing StreamExt / .next() not found

​Mixing async and synchronous methods

​Startup failure: no hardware virtualization (environment constraint)

​The first run stalls while pulling the image

​Next Steps