Concepts

Runtimes

Brig does not boot a sandbox. A runtime does: hull on macOS, nerdctl on Linux. Under hull, vz, hvi and qemu are hypervisor backends, called backends below.

Platform comparison #

On Linux, install.sh installs nerdctl, containerd and urunc from the runtime bundle described in Install. The nerdctl and containerd in that bundle are upstream releases. For its urunc, see Runtime requirements.

Components #

The licences were read from each repository's LICENSE file on 2026-08-26, and not checked again after that date.

nerdctl, containerd and urunc predate Brig. Brig passes them only flags that any other caller can pass.

Architecture shows how hull, hvi and the network gateway fit together on macOS.

macOS backends #

Six of the eight shipped profiles set hypervisor: hvi, network: isolated and genericBoot: true (internal/profile/specs). Each new sandbox of those profiles uses hvi and gets a separate network. This path needs the hvi binary beside hull, a working gateway, and the boot bundle.

hull accepts three values for its --hypervisor flag. Brig always passes the flag. The value is BRIG_HYPERVISOR if that is set, and otherwise the backend the profile names.

hull does not ship QEMU. Install it with brew install qemu. hull's backends page says what else each backend needs.

Note brig doctor's Hypervisor.framework available line does not report on these three backends. It is the pass string of one kern.hv_support sysctl read, which shows only whether this Mac can back a microVM. It never gates the exit status.

The boundary #

Brig decides the following:

• which image, and whether its signature verified (internal/verify)
• which host directory is the guest home
• which credentials are resolved, which are denied for billing safety, and which are handed in by name and not by value
• the sandbox name, memory, CPU count, network mode, pull policy, root filesystem type, hypervisor backend and shared directories
• on macOS, the kernel and initrd paths for an image that carries no kernel, and the gateway address each sandbox takes

The runtime decides the following:

• how the image is pulled and stored
• how the sandbox is configured and booted
• how a command gets into the guest
• what a stopped instance means

Brig links no runtime code. It runs each runtime, cosign and oras as a subprocess. Brig has three direct Go dependencies:

Runtime commands #

hull --version                          # does this hull boot a digest?
hull assets pull                        # HULL_BOOT_ASSETS=<dir> in the environment
hull assets dir
hull ps
hull ps -a                              # falls back to `hull ps` if -a is refused
hull run --detach --name <name>
     --hypervisor <vz|hvi|qemu> --net <shared|none>   # none is --network offline
     --pull <missing|always|never> --mem <MB> --cpus <n>
     [--rootfs-type <block|virtiofs|9pfs>]
     [--annotation com.urunc.unikernel.bootKernel=<path>]
     [--annotation com.urunc.unikernel.bootInitrd=<path>]
     [--gateway-sock <path> --gateway-cidr <cidr>]
     [--shared-dir <host>:<guest>[:ro]]...
     [--gui [--gui-title <title>]]
     [--env <NAME>|<NAME>=<value>]... <image>
hull exec [-t] [--cwd <dir>] [-u <user>] [--env <NAME>|<NAME>=<value>]... <name> -- <cmd>...
hull logs [--follow] [--tail <n>] <name>
hull stop <name>
hull rm <name>
hull network-gateway --help             # does this hull enforce a policy? (--egress-default)
hull network-gateway --socket <path> --qemu-socket <path>.qemu
     --subnet 198.18.0.0/24 --gateway-ip 198.18.0.1   # internal/runtime/gateway.go
hull network-gateway --socket <path> --qemu-socket <path>.qemu
     --subnet <a /30 of its own> --gateway-ip <first address on it>
     [--egress-default <allow|deny>]                  # an isolated sandbox, or one
     [--egress-allow <rule>]... [--egress-deny <rule>]...   # carrying a policy

nerdctl image inspect --format {{index .RepoDigests 0}} <ref>   # the digest to pin
nerdctl ps --filter name=^<name>$ --format {{.Names}}
nerdctl ps -a --format {{.Names}}\t{{.Status}}
nerdctl network ls --format {{.Name}}
nerdctl network create <name>            # --network isolated: a network per sandbox
nerdctl network rm <name>                # with the sandbox, and by rm --all
nerdctl run --detach --name <name>
     --runtime io.containerd.urunc.v2         # BRIG_CONTAINERD_RUNTIME overrides
     --memory <MB>m --cpus <n>
     [--pull <missing|always|never>]
     [--network none | --network <name>]      # offline, or isolated
     [--annotation com.urunc.unikernel.bootKernel=<path>]
     [--annotation com.urunc.unikernel.bootInitrd=<path>]
     [--annotation com.urunc.unikernel.hypervisor=cloud-hypervisor]
     [-v <host>:<guest>[:ro]]... [--tmpfs <path>:<options>]...
     [-e <NAME>|<NAME>=<value>]... <image> sleep infinity
nerdctl exec -i [-t] [-w <dir>] [-u <user>] [-e <NAME>|<NAME>=<value>]... <name> <cmd>...
nerdctl logs [--follow] [--tail <n>] <name>
nerdctl stop <name>
nerdctl rm <name>

Verification and fetch commands #

Brig also runs two commands that are not aimed at a runtime:

oras pull ghcr.io/nofireai/hull-assets:<os>-<arch> --output <dir>
                                                # internal/runtime/bootfetch.go
cosign verify --certificate-identity-regexp <identity>
     --certificate-oidc-issuer <issuer> <image> # internal/verify/verify.go

Command environment #

Every runtime command carries HULL_TELEMETRY_PRODUCT=brig and HULL_TELEMETRY_SUPPRESS=1 in its environment. Brig lifts the suppression only for the operations a user asked for, so one Brig command counts once. DO_NOT_TRACK and HULL_TELEMETRY_DISABLED pass through untouched and win.

Only the bare variable name of a forwarded value goes in argv, so nothing readable in ps carries a secret.

See Security model.

Runtime discovery #

Brig finds the runtime in this order (internal/runtime/runtime.go):

1. BRIG_RUNTIME names the runtime, hull or nerdctl. Brig refuses any other value by name. If the variable is unset, the runtime is hull on macOS and nerdctl everywhere else.
2. BRIG_RUNTIME_BIN is the executable to run. Brig takes a path as it stands, and looks up a bare name on PATH. Brig reports a missing or non-executable one against the variable before anything runs.
3. A profile's runtimeBin does the same thing without a variable per shell. It loses to BRIG_RUNTIME_BIN. Brig expands a leading ~. Brig reports a missing or non-executable path against the profile that named it.
4. Otherwise PATH: hull for the hull runtime, and nerdctl then docker for the other one.

brig info <ref> prints the result, as runtime hull (/opt/homebrew/bin/hull). brig doctor reports the runtime's version beside the rest of the host.

Capability checks #

Brig asks the runtime four questions:

hull --version is the only version Brig reads. A current hull release boots a digest reference from its store, so Brig pins the image it verified. An unreadable answer counts as pinning.

Before Brig boots a sandbox that carries a policy, it reads network-gateway --help for one word, --egress-default. A sandbox with no policy runs no probe. See Policy enforcement.

With an old build, Brig degrades one feature at a time:

Runtime requirements #

Policy enforcement #

A run path is a runtime with one backend. Before a run that carries an egress policy, Brig asks whether the run path enforces the policy. The answer comes from one table, shown in Policies.

Brig boots a policy-bound run only on enforced. The refusal names the property, the runtime and the backend.

On hvi, the probe can give two other answers. Brig refuses the run on both.

Versions and pins #

Brig's source pins no version of hull, nerdctl, containerd or urunc, and verifies no digest of any of them. The pin is on the install path.

Boot bundle digests #

On both platforms Brig compares the kernel and initrd with a list of digests before it boots them. The list comes from the verified bundle, or from the signed record in the Linux runtime bundle. See Security model.

Brig fetches the boot bundle by the digest whose signature it verified, not by the tag. hull gets repo@sha256:... as HULL_BOOT_ASSETS_REF, and oras pulls the same. A tag that moves between the verification and the fetch cannot deliver an unverified bundle.

Swaps #

These swaps need no code:

Any shim that reads the two boot annotations can replace urunc with no change in Brig. The envelope's ISOLATION row names the shim. If Brig cannot place a shim other than urunc's, the row calls the boundary unknown and not a microVM.

A third runtime needs a code change. BRIG_RUNTIME accepts only hull and nerdctl. Make two changes in internal/runtime/runtime.go:

1. Implement the Runtime interface.
2. Add a case to DetectFor.

The interface lists kind, binary, running, list, run, probe, output, feed, replace, stop, remove, and logs hint. Brig needs nothing else from a runtime.

A replacement for hull must boot an OCI image as a microVM and exec into it. Guest homes, credentials and profiles do not change.

Shared components #

Hull from source #

This section applies only if you work on hull, and only on macOS.

The released hull is signed, notarized and stapled, so brew install --cask brig needs none of the steps below. A build of Brig from source needs none of them either. Brig holds no entitlement and drives the hull it finds.

A from-source hull cannot boot a microVM unless it is signed with an Apple identity. Two binaries need an entitlement:

macOS honours an entitlement only on a binary signed with a real Apple identity: an Apple Development or Developer ID Application certificate.

An ad-hoc signature (codesign --sign -) gets the entitlement honoured only with AMFI disabled. To disable AMFI, you must disable SIP and set a boot argument.

A copy of an entitled binary loses its signature. Re-sign the binary after every build and every copy.

If you give hull's make macos a CODESIGN_IDENTITY, it builds and signs all three binaries. hull's README documents the entitlement plists. The shipped Brig profiles ask for the hvi backend, so a from-source build needs a signed hvi binary as well as a signed vz-runner.