Struct Sandbox 

pub struct Sandbox { /* private fields */ }

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

Create one with the per-kind builders (Sandbox::linux, Sandbox::freebsd, …), reconnect with Sandbox::get, or enumerate with Sandbox::list.

Implementations

impl Sandbox

pub fn fs(&self) -> FileSystem

Read and write files in the guest.

pub fn cache(&self) -> Cache

Save and restore guest directories under a key.

pub fn linux(image: impl Into<String>) -> LinuxBuilder

Boot an OCI image as a Linux microVM.

pub fn freebsd() -> FreebsdBuilder

Boot FreeBSD (EFI on macOS, PVH on Linux/amd64).

pub fn netbsd() -> NetbsdBuilder

Boot NetBSD (direct-kernel boot everywhere).

pub fn firmware( firmware: impl Into<String>, disk: impl Into<String>, ) -> FirmwareBuilder

Boot a raw disk through its UEFI loader.

pub fn kernel(kernel: impl Into<String>) -> KernelBuilder

Boot a kernel directly, no bootloader.

pub fn nanos(image: impl Into<String>) -> NanosBuilder

Boot a Nanos image (a path, or a bare name in ~/.ops/images).

pub fn osv(image: impl Into<String>) -> OsvBuilder

Boot an OSv image (an aarch64 loader.img, or on x86_64 the loader ELF plus a OsvBuilder::disk).

pub fn unikraft(path: impl Into<String>) -> UnikraftBuilder

Boot a Unikraft unikernel (a kraft project dir or a built image).

pub fn solo5(path: impl Into<String>) -> Solo5Builder

Boot a Solo5 (MirageOS) unikernel (a .hvt binary or a project dir whose dist/ holds one).

pub fn from_id(id: impl Into<String>) -> Sandbox

Wrap an already-known machine id without checking it exists.

pub fn get(id: &str) -> Result<Sandbox>

Reconnect to an existing machine by id (a unique prefix is enough).

pub fn list(all: bool) -> Result<Vec<SandboxInfo>>

List machines. all includes exited ones (otherwise: running only).

pub fn id(&self) -> &str

The machine’s Docker-style short id.

pub fn ssh_port(&self) -> Option<u16>

Host port forwarded to the guest’s SSH, if the boot banner reported one.

pub fn command(&self, program: impl Into<String>) -> CommandBuilder

Start building a guest command: program first, everything else chained.

let out = sandbox
    .command("node")
    .args(["-e", "console.log(1)"])
    .env("X", "hi")
    .cwd("/app")
    .run()?;

pub fn exec<I, S>(&self, argv: I) -> Result<ExecResult>

where I: IntoIterator<Item = S>, S: Into<String>,

Run an argv in the guest through its exec agent — the shorthand for Sandbox::command with no extra options.

A non-zero exit is reported in the ExecResult, not raised; chain ExecResult::ok_or_err to turn it into an error.

pub fn logs(&self) -> Result<String>

Read the machine’s console log.

pub fn boot_logs(&self) -> Result<String>

Read bsdkrun’s boot log for the machine.

pub fn shell(&self) -> Result<i32>

Attach an interactive shell to the machine (inherits the terminal).

Blocks until the shell exits and returns its exit code.

pub fn status(&self) -> Result<Option<SandboxInfo>>

Fetch this machine’s current status row, or None if it’s gone.

pub fn is_running(&self) -> Result<bool>

Whether the machine is currently running.

pub fn stop(&self) -> Result<()>

Stop the machine (BSD: clean power-off; Linux: SIGTERM).

pub fn start(&self) -> Result<()>

Restart a stopped machine in place — same id, disk/rootfs, network.

pub fn remove(&self, force: bool) -> Result<()>

Remove the machine and its state. force stops it first if running.

pub fn update(&self) -> UpdateBuilder

Change the recorded vCPU / RAM; applies on the next Sandbox::start.

sandbox.update().cpus(4).mem(2048).apply()?;

pub fn connect_network(&self, network: &str) -> Result<()>

Join or switch this machine to a global network (next start).

pub fn disconnect_network(&self) -> Result<()>

Detach this machine from its network. Applies on the next start.

pub fn ssh_setup(&self) -> SshSetupBuilder

Install SSH keys in the guest (ssh setup, via the agent).

With no key, the CLI installs your local ~/.ssh/*.pub keys.

sandbox.ssh_setup().user("tsiry").key("~/.ssh/work.pub").run()?;

pub fn tailscale_up(&self) -> TailscaleUpBuilder

Put the guest on your tailnet (tailscale setup, via the agent).

sandbox.tailscale_up().authkey("tskey-auth-...").hostname("web").run()?;

Trait Implementations

impl Clone for Sandbox

fn clone(&self) -> Sandbox

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Sandbox

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.