Bsdkrun.Sandbox (bsdkrun_ex v0.2.1)

A handle to a running (or stopped) bsdkrun microVM. Create one with create/1, reconnect with get/1, or enumerate with list/1.

{:ok, box} = Bsdkrun.Sandbox.create(os: :linux, image: "alpine")
{:ok, res} = Bsdkrun.Sandbox.exec(box, ["uname", "-a"])
:ok = Bsdkrun.Sandbox.stop(box)

Every fallible function returns {:ok, value} or {:error, %Bsdkrun.Error{}}, with a bang counterpart that unwraps or raises. Functions that act on a machine accept either a %Bsdkrun.Sandbox{} struct or a bare id string.

The bang lifecycle functions (stop!/1, start!/1, remove!/2, update!/2, connect_network!/2, disconnect_network!/1) return ref itself — not :ok — so they chain with |>:

Bsdkrun.create!(os: :linux, image: "alpine")
|> Bsdkrun.exec!(["apk", "add", "curl"])
|> Bsdkrun.stop!()

exec!/3, logs!/2, status!/1, ssh_setup!/2 and tailscale_up!/2 return their unwrapped value instead (a Result, a string, ...), since that value — not the sandbox — is the point of calling them. Reach for tap/2 to run one mid-chain without losing the sandbox:

Bsdkrun.create!(os: :linux, image: "alpine")
|> tap(&(Bsdkrun.exec!(&1, ["uname", "-a"]) |> Bsdkrun.Types.Result.text() |> IO.puts()))
|> Bsdkrun.stop!()

Summary

Types

ref()

A sandbox handle or a bare machine id.

t()

Functions

connect_network(ref, network)

Join or switch this machine to a global network. Applies on next start/1.

connect_network!(ref, network)

Like connect_network/2, but raises on failure and returns ref (for chaining).

create(opts)

Boot a new microVM (detached) and return a handle to it.

create!(opts)

Like create/1, but returns the sandbox or raises Bsdkrun.Error.

disconnect_network(ref)

Detach this machine from its network. Applies on next start/1.

disconnect_network!(ref)

Like disconnect_network/1, but raises on failure and returns ref (for chaining).

exec(ref, command, opts \\ [])

Run a command in the guest through its exec agent.

exec!(ref, command, opts \\ [])

Like exec/3, but returns the Result or raises Bsdkrun.Error.

get(id)

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

get!(id)

Like get/1, but returns the sandbox or raises Bsdkrun.Error.

id(id)

Extract the machine id from a sandbox struct or a bare id string.

list(opts \\ [])

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

list!(opts \\ [])

Like list/1, but returns the list or raises Bsdkrun.Error.

logs(ref, opts \\ [])

Read the machine's console log. Pass boot: true for bsdkrun's own boot log.

logs!(ref, opts \\ [])

Like logs/2, but returns the log or raises Bsdkrun.Error.

new(opts \\ [])

Start building create/1 options via |> (with_*/2 calls), finished with create/1 or create!/1. See Bsdkrun.Sandbox.Builder.

remove(ref, opts \\ [])

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

remove!(ref, opts \\ [])

Like remove/2, but raises on failure and returns ref (for chaining).

running?(ref)

Whether the machine is currently running (false if it can't be found).

shell(ref)

Attach an interactive shell to the machine, inheriting the current terminal. Blocks until the shell exits; returns its exit status.

ssh_setup(ref, opts \\ [])

Install SSH keys in the guest via the agent (ssh setup). With no :key, the CLI installs your local ~/.ssh/*.pub. Opts: :user, :key (a literal key string or .pub path, or a list of them).

ssh_setup!(ref, opts \\ [])

Like ssh_setup/2, but returns the Result or raises Bsdkrun.Error.

start(ref)

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

start!(ref)

Like start/1, but raises on failure and returns ref (for chaining).

status(ref)

Fetch this machine's current status row, or nil if it's gone.

status!(ref)

Like status/1, but returns the row (or nil) or raises Bsdkrun.Error.

stop(ref)

Stop the machine (BSD guests clean-poweroff; Linux is SIGTERM'd).

stop!(ref)

Like stop/1, but raises on failure and returns ref (for chaining).

tailscale_up(ref, opts \\ [])

Put the guest on your tailnet via the agent (tailscale setup). The :authkey is forwarded as TS_AUTHKEY (kept off the arg list). Opts: :authkey, :hostname, :args (passthrough).

tailscale_up!(ref, opts \\ [])

Like tailscale_up/2, but returns the Result or raises Bsdkrun.Error.

update(ref, opts)

Change the recorded vCPU / RAM (:cpus, :mem). Applies on next start/1.

update!(ref, opts)

Like update/2, but raises on failure and returns ref (for chaining).

with_command(b, cmd)

Set the command run after -- (Linux / firmware / kernel guests).

with_cpus(b, n)

Set the vCPU count.

with_disk(b, path)

Attach an extra raw disk as virtio-blk (repeatable) — a path, optionally "path:ro".

with_mem(b, mb)

Set the guest RAM, in MiB.

with_mount(b, spec)

Add a host<->guest mount (repeatable) — "~/project:/src" or "~/data:/data:ro".

with_mounts(b, specs)

Add several mounts at once — see with_mount/2.

with_name(b, name)

Set the machine's name.

with_network(b, network)

Join a global network on boot (like --network; see Bsdkrun.Networks).

with_opt(b, key, value)

Set an arbitrary create/1 option — the escape hatch for anything not wrapped above.

with_port(b, port)

Add a host<->guest port forward (repeatable) — "8080:80", {2222, 22}, or %{host: 2222, guest: 22}.

with_ports(b, ports)

Add several port forwards at once — see with_port/2.

with_volume(b, name)

Set the persistent volume to boot from/into (-v).