bsdkrun - v1.0.0

bsdkrun/sandbox

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

import bsdkrun/args
import bsdkrun/sandbox

let assert Ok(box) = sandbox.create(args.linux("alpine"))
let assert Ok(res) = sandbox.exec(box, ["uname", "-a"], sandbox.exec_options())
let assert Ok(Nil) = sandbox.stop(box)

Functions that act on a machine take a Sandbox; use from_id to build one from a bare id you already hold.

Types

ExecOptions

</>

How to run a command inside a guest. Build one with exec_options.

pub type ExecOptions {
  ExecOptions(
    env: List(#(String, String)),
    tty: Bool,
    stdin: option.Option(String),
    cwd: option.Option(String),
    fail_on_error: Bool,
    log_level: Int,
  )
}

Constructors 

  • ExecOptions(
  env: List(#(String, String)),
  tty: Bool,
  stdin: option.Option(String),
  cwd: option.Option(String),
  fail_on_error: Bool,
  log_level: Int,
)

Sandbox

</>

A handle to a machine. ssh_port is populated on create when bsdkrun reports a forwarded SSH port.

pub type Sandbox {
  Sandbox(id: String, ssh_port: option.Option(Int))
}

Constructors

Values

boot_logs

</> 
pub fn boot_logs(box: Sandbox) -> Result(String, error.Error)

Read bsdkrun’s own boot log for the machine.

connect_network

</> 
pub fn connect_network(
  box: Sandbox,
  network: String,
) -> Result(Nil, error.Error)

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

create

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

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

disconnect_network

</> 
pub fn disconnect_network(
  box: Sandbox,
) -> Result(Nil, error.Error)

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

exec

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

Run a command in the guest through its exec agent.

The Error case covers only failures to run the command (no binary, or fail_on_error with a non-zero exit); an ordinary non-zero exit is reported in the returned CommandResult.

exec_options

</> 
pub fn exec_options() -> ExecOptions

Default exec options: no env, no TTY, no stdin, no cwd, a non-zero exit returned as a CommandResult rather than an Error.

from_id

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

Build a handle from a machine id you already have. No lookup is performed — use get if you want the id validated.

get

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

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

is_running

</> 
pub fn is_running(box: Sandbox) -> Bool

Whether the machine is currently running. A machine that cannot be found counts as not 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) -> Result(String, error.Error)

Read the machine’s console log.

remove

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

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

shell

</> 
pub fn shell(box: Sandbox) -> Result(Int, error.Error)

Attach an interactive shell to the machine, inheriting this node’s stdio. Blocks until the shell exits and returns its exit status.

ssh_setup

</> 
pub fn ssh_setup(
  box: Sandbox,
  user: option.Option(String),
  keys: List(String),
) -> Result(types.CommandResult, error.Error)

Install SSH keys in the guest via the agent. With no keys, the CLI installs your local ~/.ssh/*.pub.

start

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

Restart a stopped machine in place: same id, disk, and resources.

status

</> 
pub fn status(
  box: 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) -> Result(Nil, error.Error)

Stop the machine — BSD guests get a clean poweroff, Linux gets SIGTERM.

tailscale_up

</> 
pub fn tailscale_up(
  box: Sandbox,
  authkey: option.Option(String),
  hostname: option.Option(String),
  extra: List(String),
) -> Result(types.CommandResult, error.Error)

Put the guest on your tailnet via the agent. The auth key is passed through the environment as TS_AUTHKEY, so it never lands in an argument list.

update

</> 
pub fn update(
  box: Sandbox,
  cpus: option.Option(Int),
  mem: option.Option(Int),
) -> Result(Nil, error.Error)

Change the recorded vCPU / RAM. Applies on the next start.

with_cwd

</> 
pub fn with_cwd(opts: ExecOptions, dir: String) -> ExecOptions

Run the command from dir inside the guest.

with_env

</> 
pub fn with_env(
  opts: ExecOptions,
  env: List(#(String, String)),
) -> ExecOptions

Set environment variables for the command.

with_fail_on_error

</> 
pub fn with_fail_on_error(
  opts: ExecOptions,
  fail: Bool,
) -> ExecOptions

Return Error(CommandFailed(..)) instead of a CommandResult when the command exits non-zero.

with_stdin

</> 
pub fn with_stdin(opts: ExecOptions, data: String) -> ExecOptions

Pipe data to the command’s stdin.

with_tty

</> 
pub fn with_tty(opts: ExecOptions, tty: Bool) -> ExecOptions

Allocate a pseudo-TTY for the command.

✨ Search Document