bsdkrun - v1.0.0

bsdkrun/args

Create options and the argv builder behind sandbox.create.

Ported from the TypeScript SDK’s args.ts; every path ends with -d so create yields a detached machine to hold a handle to.

Options are a CreateOptions record built from one of the per-guest constructors (linux, freebsd, netbsd, firmware, kernel) and refined with the with_* helpers:

args.linux("alpine")
|> args.with_name("web")
|> args.with_cpus(2)
|> args.with_ports([args.Port(8080, 80)])

Types

CreateOptions

</>

Everything sandbox.create needs: the guest, plus the options every guest kind shares.

pub type CreateOptions {
  CreateOptions(
    guest: Guest,
    name: option.Option(String),
    cpus: option.Option(Int),
    mem: option.Option(Int),
    volume: option.Option(String),
    persist: Bool,
    attach_disk: List(String),
    no_net: Bool,
    ports: List(Port),
    mac: option.Option(String),
    network: option.Option(String),
    log_level: Int,
  )
}

Constructors

Guest

</>

Guest-kind-specific options. One of these sits inside every CreateOptions.

pub type Guest {
  Linux(
    image: String,
    kernel: option.Option(String),
    kernel_version: option.Option(String),
    initramfs: Bool,
    entrypoint: option.Option(String),
    console: option.Option(String),
    mounts: List(String),
    command: List(String),
  )
  Freebsd(
    version: option.Option(String),
    firmware: option.Option(String),
    force: Bool,
  )
  Netbsd(version: option.Option(String), force: Bool)
  Firmware(firmware: String, disk: String)
  Kernel(
    kernel: String,
    format: option.Option(String),
    initramfs: option.Option(String),
    cmdline: option.Option(String),
    disk: option.Option(String),
  )
}

Constructors 

  • Linux(
  image: String,
  kernel: option.Option(String),
  kernel_version: option.Option(String),
  initramfs: Bool,
  entrypoint: option.Option(String),
  console: option.Option(String),
  mounts: List(String),
  command: List(String),
)

    Run an OCI image as a microVM.

  • Freebsd(
  version: option.Option(String),
  firmware: option.Option(String),
  force: Bool,
)

    Boot FreeBSD — via EFI on macOS, via PVH direct kernel on Linux/amd64.

  • Netbsd(version: option.Option(String), force: Bool)

    Boot NetBSD via direct kernel.

  • Firmware(firmware: String, disk: String)

    Boot an arbitrary disk through a UEFI firmware image.

  • Kernel(
  kernel: String,
  format: option.Option(String),
  initramfs: option.Option(String),
  cmdline: option.Option(String),
  disk: option.Option(String),
)

    Boot an arbitrary kernel directly, with no bootloader.

Port

</>

A host-to-guest TCP port forward.

pub type Port {
  Port(host: Int, guest: Int)
}

Constructors 

  • Port(host: Int, guest: Int)

Values

build_create

</> 
pub fn build_create(
  opts: CreateOptions,
) -> Result(List(String), error.Error)

Build the create argv — everything after the binary and its global flags.

firmware

</> 
pub fn firmware(firmware: String, disk: String) -> CreateOptions

Boot disk through the UEFI firmware image firmware.

freebsd

</> 
pub fn freebsd() -> CreateOptions

Boot a FreeBSD guest.

kernel

</> 
pub fn kernel(kernel: String) -> CreateOptions

Boot kernel directly, with no bootloader.

linux

</> 
pub fn linux(image: String) -> CreateOptions

Run the OCI image image as a microVM.

netbsd

</> 
pub fn netbsd() -> CreateOptions

Boot a NetBSD guest.

new

</> 
pub fn new(guest: Guest) -> CreateOptions

Wrap a Guest in CreateOptions with every shared option at its default.

with_attach_disk

</> 
pub fn with_attach_disk(
  opts: CreateOptions,
  disks: List(String),
) -> CreateOptions

Attach extra raw disk images.

with_command

</> 
pub fn with_command(
  opts: CreateOptions,
  command: List(String),
) -> CreateOptions

Set the command to run in the guest (Linux guests only; ignored elsewhere).

with_cpus

</> 
pub fn with_cpus(opts: CreateOptions, cpus: Int) -> CreateOptions

Set the vCPU count.

with_entrypoint

</> 
pub fn with_entrypoint(
  opts: CreateOptions,
  entrypoint: String,
) -> CreateOptions

Override the image’s entrypoint (Linux guests only).

with_force

</> 
pub fn with_force(
  opts: CreateOptions,
  force: Bool,
) -> CreateOptions

Re-download the image even if it is already cached (FreeBSD / NetBSD only).

with_log_level

</> 
pub fn with_log_level(
  opts: CreateOptions,
  level: Int,
) -> CreateOptions

Set the --log-level used for the create invocation itself.

with_mac

</> 
pub fn with_mac(
  opts: CreateOptions,
  mac: String,
) -> CreateOptions

Pin the guest’s MAC address.

with_mem

</> 
pub fn with_mem(opts: CreateOptions, mem: Int) -> CreateOptions

Set the RAM in MiB.

with_mounts

</> 
pub fn with_mounts(
  opts: CreateOptions,
  mounts: List(String),
) -> CreateOptions

Bind-mount host paths into the guest as HOST:GUEST (Linux guests only).

with_name

</> 
pub fn with_name(
  opts: CreateOptions,
  name: String,
) -> CreateOptions

Name the machine, so it can be addressed as --name instead of by id.

with_network

</> 
pub fn with_network(
  opts: CreateOptions,
  network: String,
) -> CreateOptions

Join a global network at boot, so peers can reach this machine by name.

with_no_net

</> 
pub fn with_no_net(
  opts: CreateOptions,
  no_net: Bool,
) -> CreateOptions

Boot with networking disabled.

with_persist

</> 
pub fn with_persist(
  opts: CreateOptions,
  persist: Bool,
) -> CreateOptions

Persist the machine’s disk across restarts.

with_ports

</> 
pub fn with_ports(
  opts: CreateOptions,
  ports: List(Port),
) -> CreateOptions

Forward host TCP ports into the guest.

with_version

</> 
pub fn with_version(
  opts: CreateOptions,
  version: String,
) -> CreateOptions

Pin the release to fetch (FreeBSD / NetBSD guests only).

with_volume

</> 
pub fn with_volume(
  opts: CreateOptions,
  volume: String,
) -> CreateOptions

Back the machine with a named persistent volume.

✨ Search Document