bsdkrun

Gleam SDK for bsdkrun — a Firecracker-style microVM launcher for BSD and Linux guests on macOS and Linux, built on libkrun.

The SDK is a thin, stateless wrapper around the bsdkrun binary: it builds argv, shells out through an Erlang port, and decodes the JSON output.

import bsdkrun
import bsdkrun/args
import bsdkrun/types

pub fn main() {
  let assert Ok(box) = bsdkrun.create(args.linux("alpine"))
  let assert Ok(res) = bsdkrun.exec(box, ["uname", "-a"])
  echo types.text(res)
  let assert Ok(Nil) = bsdkrun.stop(box)
}

This module holds the shortest path to a running machine. Everything else lives in the submodules:

bsdkrun/sandbox — create, inspect, and drive microVMs.
bsdkrun/args — the create options and their builders.
bsdkrun/images — list downloaded images.
bsdkrun/volumes — list and remove persistent volumes.
bsdkrun/networks — global networks; reach machines by name.
bsdkrun/system — probe, fetch BSD images, list versions, grow disks.
bsdkrun/types — the decoded records and CommandResult helpers.
bsdkrun/binary — override or inspect binary discovery.
bsdkrun/error — the single Error type and its renderer.

The binary is resolved from bsdkrun/binary.set_binary_path, $BSDKRUN_BIN, bsdkrun on $PATH, or an in-repo dev build — in that order.

Values

create

</>

pub fn create(
  opts: args.CreateOptions,
) -> Result(sandbox.Sandbox, error.Error)

Boot a new microVM (detached) and return a handle to it. See bsdkrun/args for the option builders.

exec

</>

pub fn exec(
  box: sandbox.Sandbox,
  command: List(String),
) -> Result(types.CommandResult, error.Error)

Run a command in the guest with the default options. Use bsdkrun/sandbox.exec when you need env vars, a TTY, stdin, or a cwd.

get

</>

pub fn get(id: String) -> Result(sandbox.Sandbox, error.Error)

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

is_running

</>

pub fn is_running(box: sandbox.Sandbox) -> Bool

Whether the machine is currently running.

list

</>

pub fn list() -> Result(List(types.SandboxInfo), error.Error)

List running machines.

list_all

</>

pub fn list_all(
  all: Bool,
) -> Result(List(types.SandboxInfo), error.Error)

List machines, including exited ones when all is True.

logs

</>

pub fn logs(box: sandbox.Sandbox) -> Result(String, error.Error)

Read the machine’s console log.

remove

</>

pub fn remove(
  box: sandbox.Sandbox,
  force: Bool,
) -> Result(Nil, error.Error)

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

start

</>

pub fn start(box: sandbox.Sandbox) -> Result(Nil, error.Error)

Restart a stopped machine in place.

status

</>

pub fn status(
  box: sandbox.Sandbox,
) -> Result(option.Option(types.SandboxInfo), error.Error)

This machine’s current status row, or None if it is gone.

stop

</>

pub fn stop(box: sandbox.Sandbox) -> Result(Nil, error.Error)

Stop the machine.