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

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,
)

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),
  )
  Nanos(
    image: String,
    kernel: option.Option(String),
    cmdline: option.Option(String),
  )
  Unikraft(
    path: String,
    cmdline: option.Option(String),
    initramfs: option.Option(String),
    mounts: List(String),
  )
  Osv(
    image: String,
    cmdline: option.Option(String),
    disk: option.Option(String),
    gic: 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.

```
Nanos(
  image: String,
  kernel: option.Option(String),
  cmdline: option.Option(String),
)
```
Boot a Nanos (NanoVMs) unikernel image. No agent (no exec/shell), but it does have a root disk, so the shared persist option is honored.

Arguments

image

A path, or a bare name in ~/.ops/images (what ops build -i makes).

kernel

Nanos kernel override (Linux hosts).
```
Unikraft(
  path: String,
  cmdline: option.Option(String),
  initramfs: option.Option(String),
  mounts: List(String),
)
```
Boot a Unikraft unikernel — the application linked into the kernel.

There is no disk and no userland, so the persist / volume / attach-disk options are ignored, and the resulting sandbox supports neither exec nor shell nor snapshots. Read its output with logs.

Arguments

path

A kraft project directory (the image is found under its .unikraft/build/) or a built unikernel image.

mounts

Persistent volumes over virtio-fs, each "HOST:GUEST" with an absolute guest path. The one disk-shaped option a unikernel takes: a share needs neither a disk nor an agent.
```
Osv(
  image: String,
  cmdline: option.Option(String),
  disk: option.Option(String),
  gic: option.Option(String),
)
```
Boot an OSv unikernel image.

Like the other unikernels there is no agent, so neither exec nor shell nor snapshots apply — read its output with logs. OSv does have a root filesystem, so the shared persist option is honored.

Arguments

image

An aarch64 loader.img (a capstan-composed image is both kernel and filesystem), or on x86_64 the loader ELF, which is kernel only and needs disk.

cmdline

The application to run and its arguments, e.g. "/hello.so".

disk

Root disk (raw). Required on x86_64.

gic

Interrupt controller, "v2" (default, what OSv v0.57.0 needs) or "v3". aarch64 only.

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.

nanos

</>

pub fn nanos(image: String) -> CreateOptions

Boot the Nanos image image — a path or a ~/.ops/images name.

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.

osv

</>

pub fn osv(image: String) -> CreateOptions

Boot the OSv image image — a loader.img, or on x86_64 a loader ELF paired with with_disk.

unikraft

</>

pub fn unikraft(path: String) -> CreateOptions

Boot the Unikraft unikernel at path — a kraft project directory or a built image. Pass "." for the current directory.

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.

Constructors

Constructors

Arguments

Arguments

Arguments

Constructors