Rust SDK reference

[dependencies]
boxlite = "0.10"            # the crate name is boxlite
tokio = { version = "1", features = ["full"] }
futures = "0.3"           # required for streaming reads of stdout/stderr

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1) Get the runtime (synchronous construction, not async). with_defaults uses ~/.boxlite as home.
    let runtime = BoxliteRuntime::with_defaults()?;

    // 2) Create a box (default rootfs = alpine:latest). create is async.
    //    Note: the default deletes the box on stop; auto_delete: Some(0) keeps it for an explicit remove later.
    let options = BoxOptions { auto_delete: Some(0), ..Default::default() };
    let litebox = runtime
        .create(options, Some("hello-box".to_string()))
        .await?;
    println!("created box id = {}", litebox.id());

    // 3) Run a command: exec returns an Execution handle; wait() blocks until the process exits.
    let execution = litebox.exec(BoxCommand::new("echo").arg("hello from boxlite")).await?;
    let result = execution.wait().await?;
    println!("exit code = {}", result.exit_code);   // 0 = success

    // 4) Cleanup: stop terminates the VM; remove is called on the [runtime], not the box.
    //    (Under the default policy stop() has already deleted it, so remove is unnecessary and should not be called.)
    litebox.stop().await?;
    runtime.remove("hello-box", false).await?;

    Ok(())
}

use boxlite::BoxCommand;
use std::time::Duration;

let cmd = BoxCommand::new("python3")
    .args(["-c", "print('hello')"])
    .env("PYTHONPATH", "/app")
    .timeout(Duration::from_secs(30))   // Note: the argument is a Duration
    .working_dir("/workspace")
    .user("nobody")                      // Same format as docker --user: <name|uid>[:<group|gid>]
    .tty(true);

use boxlite::{BoxliteRuntime, BoxOptions, BoxCommand};
use futures::StreamExt;   // provides .next()

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = BoxliteRuntime::with_defaults()?;
    let litebox = runtime.create(BoxOptions::default(), None).await?;

    let mut execution = litebox
        .exec(BoxCommand::new("sh").args(["-c", "echo line1; echo line2"]))
        .await?;

    // stdout is a Stream<Item = String>; take it and read line by line.
    if let Some(mut stdout) = execution.stdout() {
        while let Some(line) = stdout.next().await {
            println!("stdout: {line}");
        }
    }

    let result = execution.wait().await?;
    if !result.success() {
        eprintln!("command failed, exit code = {}", result.exit_code);
        if let Some(msg) = &result.error_message {
            eprintln!("diagnostic: {msg}");
        }
    }

    litebox.stop().await?;
    Ok(())
}

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = BoxliteRuntime::with_defaults()?;
    let litebox = runtime.create(BoxOptions::default(), None).await?;

    let mut execution = litebox.exec(BoxCommand::new("cat")).await?;

    if let Some(mut stdin) = execution.stdin() {
        stdin.write(b"hello stdin\n").await?;
        stdin.write_all(b"more data\n").await?;
        stdin.close();   // Explicit close = send EOF to the process (dropping also closes it)
    }

    let result = execution.wait().await?;
    println!("exit code = {}", result.exit_code);
    litebox.stop().await?;
    Ok(())
}

pub struct ExecResult {
    pub exit_code: i32,                  // 0=success; negative signal number when terminated by a signal
    pub error_message: Option<String>,   // Diagnostic when the process dies abnormally (None on normal exit)
}
// Methods: success() -> bool (exit_code==0), code() -> i32

use boxlite::runtime::options::{PortSpec, VolumeSpec};  // not re-exported at the crate root
use boxlite::{AdvancedBoxOptions, BoxOptions, NetworkSpec, RootfsSpec, SecurityOptions};

let options = BoxOptions {
    cpus: Some(2),                                       // None = the runtime default of 1 vCPU (see note in 4.1)
    memory_mib: Some(1024),                              // None = the runtime default of 1024 MiB (see note in 4.1)
    rootfs: RootfsSpec::Image("python:3.11-slim".into()),
    env: vec![("PYTHONPATH".to_string(), "/app".to_string())],
    volumes: vec![VolumeSpec {
        host_path: "<YOUR_PROJECT_PATH>".to_string(),  // <-- replace with an absolute host path
        guest_path: "/app".to_string(),
        read_only: false,                               // bool, not a "ro"/"rw" string
    }],
    network: NetworkSpec::Enabled { allow_net: vec!["api.github.com".into()] },
    ports: vec![PortSpec { host_port: Some(8080), guest_port: 80, ..Default::default() }],
    auto_delete: Some(0),                               // keep the box after stopping
    advanced: AdvancedBoxOptions {
        security: SecurityOptions::enabled(),           // enabled by default
        ..Default::default()
    },
    ..Default::default()
};

pub enum RootfsSpec {
    Image(String),       // Pull/resolve an image reference, e.g. "python:3.11-slim"
    RootfsPath(String),  // Use a prepared host rootfs path
}
// Default = Image("alpine:latest")

pub struct VolumeSpec {
    pub host_path: String,
    pub guest_path: String,
    pub read_only: bool,   // true=read-only, false=read-write. Not a "ro"/"rw" string.
}

pub enum NetworkSpec {
    Enabled { allow_net: Vec<String> },  // empty = all outbound; non-empty = allowlist only (supports exact host/wildcard/IP/CIDR)
    Disabled,                            // fully removes the guest network interface
}
// Default = Enabled { allow_net: vec![] }

pub struct PortSpec {
    pub host_port: Option<u16>,    // None = same as guest_port (source comment: None => same as guest_port)
    pub guest_port: u16,           // required: the guest port to expose
    pub protocol: PortProtocol,    // defaults to Tcp
    pub host_ip: Option<String>,   // None = 0.0.0.0
}
pub enum PortProtocol { Tcp, Udp }  // defaults to Tcp

pub struct Secret {
    pub name: String,           // human-readable name (e.g. "openai_api_key")
    pub hosts: Vec<String>,     // injection hosts, supports wildcards (e.g. ["api.openai.com", "*.example.com"])
    pub placeholder: String,    // required, no default. Conventional form: <BOXLITE_SECRET:openai>
    pub value: String,          // real value, never enters the guest; redacted in Debug/Display
}
// Note: Secret has no Default / new(); all four fields must be set explicitly.

pub struct SecurityOptions {
    pub jailer_enabled: bool,          // Master switch: jailer isolation (Linux: seccomp/namespaces; macOS: sandbox-exec)
    pub seccomp_enabled: bool,         // Linux only: seccomp syscall filtering
    pub uid: Option<u32>,              // Linux only: UID to drop to. None = auto-allocate
    pub gid: Option<u32>,              // Linux only: GID to drop to. None = auto-allocate
    pub new_pid_ns: bool,              // Linux only: create a new PID namespace
    pub new_net_ns: bool,              // Linux only: create a new network namespace
    pub chroot_base: PathBuf,          // Linux: base directory for chroot jails
    pub chroot_enabled: bool,          // Linux only: enable chroot isolation
    pub close_fds: bool,               // Close inherited file descriptors
    pub sanitize_env: bool,            // Sanitize environment variables
    pub env_allowlist: Vec<String>,    // Environment variables preserved through sanitization
    pub resource_limits: ResourceLimits, // RLIMIT_* caps for the jailed process (see 5.1.2)
    pub sandbox_profile: Option<PathBuf>, // macOS only: custom sandbox profile
    pub network_enabled: bool,         // macOS only: allow network inside the sandbox
}

pub struct ResourceLimits {
    pub max_open_files: Option<u64>,  // RLIMIT_NOFILE. Default (enabled): Some(1024)
    pub max_file_size:  Option<u64>,  // RLIMIT_FSIZE (bytes). Default (enabled): Some(1 GiB)
    pub max_processes:  Option<u64>,  // RLIMIT_NPROC. Default (enabled): Some(100)
    pub max_memory:     Option<u64>,  // RLIMIT_AS (bytes). Default: None (VM config handles this)
    pub max_cpu_time:   Option<u64>,  // RLIMIT_CPU (seconds). Default: None (VM config handles this)
}

use boxlite::{BoxliteRuntime, BoxOptions, BoxCommand, RootfsSpec};
use boxlite::{AdvancedBoxOptions, SecurityOptions};

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

    // Start from enabled, adjust a few limits, then build (builder methods take &mut self, so declare mut first).
    let mut builder = SecurityOptions::builder();
    builder
        .seccomp_enabled(false)
        .max_open_files(2048)
        .max_processes(100)
        .allow_env("MY_VAR");
    let security = builder.build();

    let options = BoxOptions {
        rootfs: RootfsSpec::Image("alpine:latest".into()),
        auto_delete: Some(0),                      // keep the box so the explicit remove below is the only deletion
        advanced: AdvancedBoxOptions {
            security,                              // custom security options
            ..Default::default()
        },
        ..Default::default()
    };

    let litebox = runtime.create(options, Some("secured".to_string())).await?;
    let result = litebox.exec(BoxCommand::new("id")).await?.wait().await?;
    println!("exit = {}", result.exit_code);

    litebox.stop().await?;
    runtime.remove("secured", false).await?;
    Ok(())
}

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = BoxliteRuntime::with_defaults()?;
    let litebox = runtime.create(BoxOptions::default(), None).await?;
    litebox.exec(BoxCommand::new("true")).await?.wait().await?;

    let box_metrics = litebox.metrics().await?;
    println!("cpu%   = {:?}", box_metrics.cpu_percent);
    println!("mem B  = {:?}", box_metrics.memory_bytes);
    println!("boot ms= {:?}", box_metrics.guest_boot_duration_ms);

    let rt_metrics = runtime.metrics().await?;   // returns BoxliteResult, needs ?
    println!("running boxes = {}", rt_metrics.num_running_boxes());

    litebox.stop().await?;
    Ok(())
}

use boxlite::{BoxliteRuntime, BoxliteOptions, ImageRegistry};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let options = BoxliteOptions {
        home_dir: PathBuf::from("<YOUR_PATH>/boxlite-home"),  // replace with a real path
        image_registries: vec![
            ImageRegistry::https("ghcr.io/myorg").with_search(true),
            ImageRegistry::https("docker.io").with_search(true),
            ImageRegistry::http("registry.local:5000").with_search(true),
            ImageRegistry::https("registry.example.com")
                .with_skip_verify(true)
                .with_basic_auth("user", "<YOUR_REGISTRY_PASSWORD>"),  // replace
        ],
    };

    let runtime = BoxliteRuntime::new(options)?;
    println!("runtime ready, version = {}", boxlite::VERSION);
    let _ = runtime;
    Ok(())
}

pub enum BoxStatus {
    Unknown,      // Cannot be determined (error recovery)
    Configured,   // Created and persisted, VM not started
    Running,      // Running, accepting commands
    Stopping,     // Gracefully shutting down (transient)
    Stopped,      // Stopped, VM terminated, rootfs preserved — can be restarted
    Paused,       // VM frozen via SIGSTOP; used during export/snapshot for a consistent point in time
    Failed,       // Init pipeline failed; record and rootfs are preserved so you can retry or destroy.
                  // BoxState::error_reason carries the cause
}

pub struct BoxState {
    pub status: BoxStatus,                  // Current lifecycle status
    pub pid: Option<u32>,                   // Process ID (None if not running)
    pub container_id: Option<ContainerID>,  // Container ID (64-char hex; see 9.2)
    pub last_updated: DateTime<Utc>,        // Last state-change timestamp (UTC)
    pub lock_id: Option<LockId>,            // Allocated on first initialization, not at creation
    pub health_status: HealthStatus,        // Current health state + consecutive failure count
    pub error_reason: Option<String>,       // Why the box entered Failed; cleared on a successful transition
    pub exit_code: Option<i32>,             // Init process exit code, set when the box stopped
}                                           // because its main command exited (Docker semantics)

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = BoxliteRuntime::with_defaults()?;
    let litebox = runtime.create(BoxOptions::default(), None).await?;

    let info = litebox.info().await?;   // async and fallible (status is a direct field)
    println!("id={} image={} status={:?}", info.id, info.image, info.status);

    if info.status == BoxStatus::Configured {
        litebox.start().await?;
    }

    litebox.stop().await?;
    Ok(())
}

use boxlite::runtime::types::Bytes;

// Constructors (all const fn)
let size = Bytes::from_bytes(1_000_000);
let size = Bytes::from_kib(512);   // 512 * 1024
let size = Bytes::from_mib(128);   // 128 * 1024^2
let size = Bytes::from_gib(2);     // 2 * 1024^3

// Accessors
let bytes = size.as_bytes();
let kib   = size.as_kib();
let mib   = size.as_mib();

// Display rounds down to the largest exact unit
println!("{}", Bytes::from_mib(512));  // "512 MiB"
println!("{}", Bytes::from_gib(2));    // "2 GiB"
println!("{}", Bytes::from_bytes(1500)); // "1500 bytes" (not an exact KiB)

use boxlite::runtime::types::Seconds;

// Constructors (all const fn)
let duration = Seconds::from_seconds(30);
let duration = Seconds::from_minutes(5);   // 300 seconds
let duration = Seconds::from_hours(1);     // 3600 seconds

// Accessors
let secs = duration.as_seconds();
let mins = duration.as_minutes();

// Display
println!("{}", Seconds::from_minutes(30));  // "30 minutes"
println!("{}", Seconds::from_seconds(45));   // "45 seconds"

use boxlite::runtime::id::{BoxID, BoxIDMint};

let id = BoxIDMint::mint();          // 12-char Base62 for locally started boxes
println!("Full:  {}", id.as_str());  // e.g. "aB3cD4eF5gH6"
println!("Short: {}", id.short());   // shortened prefix

// Parse / validate an existing string
let valid   = BoxID::parse("aB3cD4eF5gH6");
let invalid = BoxID::parse("");       // None

use boxlite::runtime::types::ContainerID;

let id = ContainerID::new();
println!("Full:  {}", id.as_str());  // 64 hex chars
println!("Short: {}", id.short());   // 12 hex chars

// Validation: exactly 64 lowercase hex characters
let ok = ContainerID::is_valid(&"a".repeat(64));  // true
let no = ContainerID::is_valid("abc123");          // false

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

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

    match runtime.create(BoxOptions::default(), None).await {
        Ok(litebox) => {
            println!("created: {}", litebox.id());
            litebox.stop().await?;
        }
        Err(BoxliteError::Image(msg))   => eprintln!("image error (pull/resolve failed): {msg}"),
        Err(BoxliteError::Config(msg))  => eprintln!("config error: {msg}"),
        Err(BoxliteError::Engine(msg))  => eprintln!("engine error (often due to missing virtualization): {msg}"),
        Err(BoxliteError::NotFound(msg))=> eprintln!("not found: {msg}"),
        Err(e)                          => eprintln!("other error: {e}"),
    }
    Ok(())
}

use boxlite::{BoxliteRuntime, BoxOptions, BoxliteError};
use std::sync::Arc;
use tokio::task;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = Arc::new(BoxliteRuntime::with_defaults()?);

    let mut handles = Vec::new();
    for _ in 0..4 {
        let rt = Arc::clone(&runtime);
        handles.push(task::spawn(async move {
            let litebox = rt.create(BoxOptions::default(), None).await?;
            let id = litebox.id().clone();
            litebox.stop().await?;
            Ok::<_, BoxliteError>(id)
        }));
    }

    for h in handles {
        match h.await? {
            Ok(id) => println!("created and stopped: {id}"),
            Err(e) => eprintln!("task error: {e}"),
        }
    }
    Ok(())
}