Quickstart

pip install boxlite

# Verify
python3 -c "import boxlite; print(boxlite.__version__)"

npm install @boxlite-ai/boxlite

cargo add boxlite
cargo add tokio --features macros,rt-multi-thread
cargo add futures

go get github.com/boxlite-ai/boxlite/sdks/go

# One-time: fetches the prebuilt native library for your platform
go run github.com/boxlite-ai/boxlite/sdks/go/cmd/setup

# The C SDK is built from source; see the C track on Installation.
git clone https://github.com/boxlite-ai/boxlite && cd boxlite
make sdk-c

# hello.py — your first BoxLite sandbox
import asyncio
import boxlite

async def main() -> None:
    try:
        # async with: the box is created and started on entry, and stopped and cleaned up on exit (auto_remove defaults to True)
        async with boxlite.SimpleBox(image="python:alpine") as box:
            print(f"Sandbox started: {box.id}")

            # exec does not raise on a non-zero exit code; check exit_code yourself
            result = await box.exec("python", "-c", "print('Hello from BoxLite!')")

            print("stdout:", result.stdout.strip())
            print("exit_code:", result.exit_code)
            if result.exit_code != 0:
                print("stderr:", result.stderr.strip())
    except RuntimeError as exc:
        # Image pull failure / startup failure without virtualization both raise a standard RuntimeError
        print(f"Sandbox failed to run: {exc}")

if __name__ == "__main__":
    asyncio.run(main())

// hello.mjs — your first BoxLite sandbox
import { SimpleBox } from "@boxlite-ai/boxlite";

async function main() {
  // alpine:latest is small and quick to pull, suitable for smoke tests.
  // Without cpus/memoryMib, the runtime's default VM size applies.
  // Pass cpus/memoryMib explicitly to control the footprint.
  const box = new SimpleBox({ image: "alpine:latest" });

  try {
    // exec(cmd, ...args) -> { exitCode, stdout, stderr }
    const result = await box.exec("echo", "Hello from BoxLite!");

    // Important: a non-zero exit code does not raise; check exitCode yourself.
    if (result.exitCode !== 0) {
      throw new Error(`Command failed (exit ${result.exitCode}): ${result.stderr}`);
    }

    console.log("stdout:", result.stdout.trim());
    console.log("exitCode:", result.exitCode);
  } catch (err) {
    // Image pull failure / missing command, etc. raise a standard Error (not necessarily a BoxliteError).
    console.error("Execution error:", err);
    process.exitCode = 1;
  } finally {
    // The box is lazily created; stop() stops and cleans up (autoRemove defaults to true).
    await box.stop();
  }
}

main();

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(())
}

package main

import (
	"context"
	"fmt"
	"log"

	boxlite "github.com/boxlite-ai/boxlite/sdks/go"
)

func main() {
	ctx := context.Background()

	// 1. Get the runtime (synchronous construction; no .Close() needed until you're done with it)
	rt, err := boxlite.NewRuntime()
	if err != nil {
		log.Fatal(err)
	}
	defer rt.Close()

	// 2. Create a box (default rootfs is set by the image argument)
	box, err := rt.Create(ctx, "alpine:latest")
	if err != nil {
		log.Fatal(err)
	}
	defer box.Close()

	// 3. Execute a command — Exec implicitly starts the box on first call
	res, err := box.Exec(ctx, "echo", "Hello from BoxLite!")
	if err != nil {
		// A nil res accompanies a non-nil err: check err before touching res
		log.Fatal(err)
	}

	// 4. A non-zero exit code does not become an error — check it yourself
	if res.ExitCode != 0 {
		fmt.Printf("command failed (exit=%d): %s", res.ExitCode, res.Stderr)
		return
	}
	fmt.Print(res.Stdout)
}

#include <stdio.h>
#include "boxlite.h"

int main(void) {
    CBoxliteSimple *box = NULL;
    CBoxliteError error = {0};  /* must be zero-initialized */

    /* Create and automatically start a box. Passing 0 for cpus/memory = use defaults. */
    BoxliteErrorCode code =
        boxlite_simple_new("python:slim", 0, 0, &box, &error);
    if (code != Ok) {
        fprintf(stderr, "create box failed (code %d): %s\n",
                error.code, error.message ? error.message : "unknown");
        boxlite_error_free(&error);  /* free error.message on the failure path too */
        return 1;
    }

    /* Run inside the box: python -c "print('Hello from BoxLite!')" */
    const char *args[] = {"-c", "print('Hello from BoxLite!')"};
    CBoxliteExecResult *result = NULL;
    code = boxlite_simple_run(box, "python", args, 2, &result, &error);
    if (code == Ok) {
        printf("exit code: %d\n", result->exit_code);
        printf("stdout: %s", result->stdout_text ? result->stdout_text : "");
        if (result->stderr_text && result->stderr_text[0]) {
            fprintf(stderr, "stderr: %s", result->stderr_text);
        }
        boxlite_result_free(result);  /* free the result (includes stdout/stderr strings) */
    } else {
        fprintf(stderr, "exec failed (code %d): %s\n",
                error.code, error.message ? error.message : "unknown");
        boxlite_error_free(&error);
    }

    boxlite_simple_free(box);  /* automatically stop + remove + free the runtime */
    return 0;
}

python hello.py

node hello.mjs

cargo run

go run hello.go

./hello

Sandbox started: mgu4zgTIGXLL
stdout: Hello from BoxLite!
exit_code: 0

stdout: Hello from BoxLite!
exitCode: 0