Rust SDK

a3s-box-sdk calls A3S Box runtime components directly. It is the best choice for Rust management applications that need typed local state and lifecycle operations without spawning the CLI.

Install

Install the matching A3S Box runtime, then add the crate:

cargo add a3s-box-sdk

Create a Sandbox

use a3s_box_sdk::Sandbox;

#[tokio::main]
async fn main() -> Result<(), a3s_box_sdk::ClientError> {
    let sandbox = Sandbox::create("python:3.12-alpine").await?;

    let result = sandbox
        .commands
        .run("python -c 'print(6 * 7)'")
        .await?;
    println!("{}", result.stdout);

    sandbox
        .files
        .write("/workspace/note.txt", "hello")
        .await?;
    println!(
        "{}",
        sandbox.files.read_text("/workspace/note.txt").await?
    );

    sandbox.kill().await?;
    Ok(())
}

MicroVM isolation is the default. Select the shared-kernel Sandbox only on a certified Linux host:

use a3s_box_sdk::{ExecutionIsolation, Sandbox, SandboxCreateOptions};

#[tokio::main]
async fn main() -> Result<(), a3s_box_sdk::ClientError> {
    let sandbox = Sandbox::create_with_options(
        SandboxCreateOptions::new("alpine:3.20")
            .isolation(ExecutionIsolation::Sandbox)
            .cpus(2)
            .memory_mb(1024),
    )
    .await?;

    let result = sandbox.commands.run("id").await?;
    println!("{}", result.stdout);

    sandbox.kill().await?;
    Ok(())
}

Build and test inside Box

use a3s_box_sdk::A3sBoxClient;

#[tokio::main]
async fn main() -> Result<(), a3s_box_sdk::ClientError> {
    let client = A3sBoxClient::new();
    let image = client
        .image("./ci")
        .dockerfile("Dockerfile")
        .tag("local/rust-ci:latest")
        .build_arg("RUST_VERSION", "stable")
        .build()
        .await?;

    let sandbox = client
        .sandbox(image.reference)
        .cpus(4)
        .memory_mb(4096)
        .workdir("/workspace")
        .start()
        .await?;

    let result = sandbox
        .script("cargo test --all-targets\n")
        .interpreter(["/bin/sh", "-se"])
        .env("CI", "true")
        .run()
        .await?;

    sandbox.kill().await?;
    if result.exit_code != 0 {
        return Err(a3s_box_sdk::ClientError::Guest(result.stderr));
    }

    Ok(())
}

Scripts are sent through standard input to the selected guest interpreter. They are not interpolated into a host shell command.

Lower-level management

A3sBoxClient exposes typed image, volume, network, box, snapshot, log, stats, diagnostics, and disk-usage operations. Use A3sBoxClient::from_home(path) for tests that must use an isolated runtime state directory.

Lifecycle requests share the same generation-fenced execution manager as the CLI. The SDK does not create a second record or infer state by scraping process output.

Error handling

Return ClientError with context from application boundaries. Avoid panicking on production runtime failures: host admission, image resolution, guest exit, and stale-generation conflicts are all expected operational errors.

See the complete crate guide and API reference.

#Rust SDK

#Install

#Create a Sandbox

#Build and test inside Box