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 (create!/1, get!/1, list!/1) that unwraps or
raises. Functions that act on a machine accept either a %Bsdkrun.Sandbox{}
struct or a bare id string.
Summary
Functions
Join or switch this machine to a global network. Applies on next start/1.
Boot a new microVM (detached) and return a handle to it.
Like create/1, but returns the sandbox or raises Bsdkrun.Error.
Detach this machine from its network. Applies on next start/1.
Run a command in the guest through its exec agent.
Reconnect to an existing machine by id (a unique prefix is enough).
Like get/1, but returns the sandbox or raises Bsdkrun.Error.
Extract the machine id from a sandbox struct or a bare id string.
List machines. all: true includes exited ones (default: running only).
Like list/1, but returns the list or raises Bsdkrun.Error.
Read the machine's console log. Pass boot: true for bsdkrun's own boot log.
Remove the machine and its state. force: true stops it first if running.
Whether the machine is currently running (false if it can't be found).
Attach an interactive shell to the machine, inheriting the current terminal. Blocks until the shell exits; returns its exit status.
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).
Restart a stopped machine in place — same id, disk/rootfs, resources.
Fetch this machine's current status row, or nil if it's gone.
Stop the machine (BSD guests clean-poweroff; Linux is SIGTERM'd).
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).
Change the recorded vCPU / RAM (:cpus, :mem). Applies on next start/1.
Types
A sandbox handle or a bare machine id.
@type t() :: %Bsdkrun.Sandbox{id: String.t(), ssh_port: non_neg_integer() | nil}
Functions
@spec connect_network(ref(), String.t()) :: :ok | {:error, Bsdkrun.Error.t()}
Join or switch this machine to a global network. Applies on next start/1.
@spec create(keyword() | map()) :: {:ok, t()} | {:error, Bsdkrun.Error.t()}
Boot a new microVM (detached) and return a handle to it.
opts is a keyword list or map discriminated on :os
(:linux, :freebsd, :netbsd, :firmware, :kernel), plus the per-kind
keys accepted by Bsdkrun.Args. :log_level (default 1) controls boot
diagnostics.
Like create/1, but returns the sandbox or raises Bsdkrun.Error.
@spec disconnect_network(ref()) :: :ok | {:error, Bsdkrun.Error.t()}
Detach this machine from its network. Applies on next start/1.
@spec exec(ref(), String.t() | [String.t()], keyword()) :: {:ok, Bsdkrun.Types.Result.t()} | {:error, Bsdkrun.Error.t()}
Run a command in the guest through its exec agent.
command is an argv list, or a bare program name string (with :args). Opts:
:args— args whencommandis a bare program name.:env— environment variables (-e K=V).:tty— allocate a pseudo-TTY (-t).:stdin— data piped to the command's stdin.:cwd— working directory (emulated viash -c 'cd …').:throw_on_error— return{:error, _}on a non-zero exit (default false).:log_level— per-command bsdkrun log level (default 0).
Returns {:ok, %Bsdkrun.Types.Result{}}. With throw_on_error: true, a
non-zero exit yields {:error, %Bsdkrun.Error{}} instead.
@spec get(String.t()) :: {:ok, t()} | {:error, Bsdkrun.Error.t()}
Reconnect to an existing machine by id (a unique prefix is enough).
Like get/1, but returns the sandbox or raises Bsdkrun.Error.
Extract the machine id from a sandbox struct or a bare id string.
@spec list(keyword()) :: {:ok, [Bsdkrun.Types.SandboxInfo.t()]} | {:error, Bsdkrun.Error.t()}
List machines. all: true includes exited ones (default: running only).
@spec list!(keyword()) :: [Bsdkrun.Types.SandboxInfo.t()]
Like list/1, but returns the list or raises Bsdkrun.Error.
@spec logs( ref(), keyword() ) :: {:ok, String.t()} | {:error, Bsdkrun.Error.t()}
Read the machine's console log. Pass boot: true for bsdkrun's own boot log.
@spec remove( ref(), keyword() ) :: :ok | {:error, Bsdkrun.Error.t()}
Remove the machine and its state. force: true stops it first if running.
Whether the machine is currently running (false if it can't be found).
Attach an interactive shell to the machine, inheriting the current terminal. Blocks until the shell exits; returns its exit status.
@spec ssh_setup( ref(), keyword() ) :: {:ok, Bsdkrun.Types.Result.t()} | {:error, Bsdkrun.Error.t()}
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).
@spec start(ref()) :: :ok | {:error, Bsdkrun.Error.t()}
Restart a stopped machine in place — same id, disk/rootfs, resources.
@spec status(ref()) :: {:ok, Bsdkrun.Types.SandboxInfo.t() | nil} | {:error, Bsdkrun.Error.t()}
Fetch this machine's current status row, or nil if it's gone.
@spec stop(ref()) :: :ok | {:error, Bsdkrun.Error.t()}
Stop the machine (BSD guests clean-poweroff; Linux is SIGTERM'd).
@spec tailscale_up( ref(), keyword() ) :: {:ok, Bsdkrun.Types.Result.t()} | {:error, Bsdkrun.Error.t()}
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).
@spec update( ref(), keyword() ) :: :ok | {:error, Bsdkrun.Error.t()}
Change the recorded vCPU / RAM (:cpus, :mem). Applies on next start/1.