Crate bsdkrun_sdk 

bsdkrun — a Rust SDK for bsdkrun, a Firecracker-style microVM launcher for BSD, Linux, and unikernel guests.

A thin, blocking wrapper: locally it builds argv, shells out to the bsdkrun binary, and parses the JSON output; remotely, Client drives the same operations against a bsdkrund daemon’s GraphQL API. No async runtime anywhere.

use bsdkrun_sdk::Sandbox;

let sandbox = Sandbox::linux("alpine")
    .cpus(2)
    .mem(1024)
    .port("8080:80")
    .command(["sleep", "300"])
    .create()?;

println!("{}", sandbox.exec(["uname", "-a"])?.text());
sandbox.stop()?;

Host-level operations live in the images, volumes, networks and system modules; the remote client in Client.

Re-exports

pub use cache::Cache;

pub use cache::CacheEntry;

pub use cache::RestoreResult;

pub use transport::normalize_url;

pub use transport::ws_url;

pub use transport::TOKEN_ENV;

pub use transport::URL_ENV;

Modules

cache

Cached guest directories — Sandbox::cache, plus host-level listing.

ci

CI workflows defined in code instead of YAML.

images

Host-level image operations.

networks

Global-network operations — reach machines by name on a shared subnet.

system

Host toolchain / image operations that aren’t tied to a single machine.

transport

The GraphQL transport for talking to a remote bsdkrund.

volumes

Host-level volume operations.

Structs

AiAgent

A coding agent bsdkrun can sandbox.

AiSession

One agent sandbox. It is a machine, so logs/stop work on id.

AiStartBuilder

An aiStart mutation being assembled — see Client::ai_start.

BinaryResult

Like RawResult, but stdout is left as bytes.

BranchBuilder

A branchSnapshot mutation being assembled — see Client::branch.

Client

A client for a remote bsdkrund’s GraphQL API.

CommandBuilder

A guest command being assembled — see Sandbox::command.

CommandResult

The outcome of a remote lifecycle mutation (stop/start/remove/update/commit).

DockerContainer

A container in the Docker engine VM — a trimmed docker ps row.

DockerStartBuilder

A dockerStart mutation being assembled — see Client::docker_start.

DockerStatus

The Docker engine VM: whether it is up, and how to reach it.

ExecResult

The captured result of running a command in a guest through the local CLI.

FileSystem

Read and write files inside a running microVM.

FirmwareBuilder

Boots a raw disk through its UEFI loader (bsdkrun firmware).

FollowLogsBuilder

A live log stream being assembled — see Client::follow_logs.

FreebsdBuilder

Boots FreeBSD (bsdkrun freebsd).

ImageInfo

An image as reported by bsdkrun images --json.

KernelBuilder

Boots a kernel directly, no bootloader (bsdkrun kernel).

LinuxBuilder

Boots an OCI image as a Linux microVM (bsdkrun linux).

NanosBuilder

Boots a Nanos unikernel image (bsdkrun nanos).

NetbsdBuilder

Boots NetBSD (bsdkrun netbsd).

NetworkInfo

A global network as reported by bsdkrun network ls --json.

OsvBuilder

Boots an OSv unikernel image (bsdkrun osv).

PortForward

A host to guest TCP port forward.

RawResult

The buffered result of a bsdkrun invocation.

RemoteExecResult

The captured result of crate::Client::exec against a remote daemon.

RunBsdBuilder

A runBsd mutation being assembled — see Client::run_bsd.

RunFlavorBuilder

A runFlavor mutation being assembled — see Client::run_flavor.

RunLinuxBuilder

A runLinux mutation being assembled — see Client::run_linux.

RunNanosBuilder

A runNanos mutation being assembled — see Client::run_nanos.

RunOsvBuilder

A runOsv mutation being assembled — see Client::run_osv.

RunSolo5Builder

A runSolo5 mutation being assembled — see Client::run_solo5.

RunUnikraftBuilder

A runUnikraft mutation being assembled — see Client::run_unikraft.

Sandbox

A handle to a running (or stopped) bsdkrun microVM.

SandboxInfo

A machine as reported by bsdkrun ps --json (or the daemon’s machines query).

ShellBuilder

An openShell mutation being assembled — see Client::shell.

ShellSession

A live interactive session opened by Client::shell.

ShellSessionInfo

A shell session as reported by openShell / shellSessions.

SnapshotInfo

A machine snapshot: one machine’s disk state, captured under a name.

Solo5Builder

Boots a Solo5 (MirageOS) unikernel under the solo5-hvt tender (bsdkrun solo5).

SshSetupBuilder

An ssh setup invocation being assembled — see Sandbox::ssh_setup.

Subscription

A raw subscription handle returned by Client::subscribe. Dropping it does not unsubscribe — call Subscription::unsubscribe, matching the Python SDK’s explicit unsubscribe function.

TailscaleUpBuilder

A tailscale setup invocation being assembled — see Sandbox::tailscale_up.

UnikraftBuilder

Boots a Unikraft unikernel (bsdkrun unikraft).

UpdateBuilder

Pending vCPU / RAM changes — see Sandbox::update.

VolumeInfo

A volume as reported by bsdkrun volume ls --json.

Enums

BsdOs

The BSD to boot with Client::run_bsd.

Error

Every error the SDK raises.

Functions

reset_binary_cache

Reset cached discovery state and any override (mainly for tests).

resolve_binary

Resolve (and cache) the path to the bsdkrun binary.

run

Run bsdkrun <args> quietly (log level 0) and capture the result.

run_binary

Run bsdkrun <args> and keep stdout as raw bytes.

run_checked

Like run, but a non-zero exit becomes Error::CommandFailed tagged with label.

set_binary_path

Force the SDK to use a specific bsdkrun binary, bypassing discovery.

spawn

Run bsdkrun <args> inheriting the parent’s stdio (interactive).

Type Aliases

Result

Result alias used across the SDK.