Skip to content

Latest commit

 

History

History
173 lines (135 loc) · 8.35 KB

variants.md

File metadata and controls

173 lines (135 loc) · 8.35 KB

Three variants, one tarball each

A variant is a build-time choice, not an install-time one. install.sh fetches one tarball and unpacks it; whichever variant that tarball was built as is the variant you get. scripts/build-bundle.sh builds them:

$ scripts/build-bundle.sh --arch amd64 --version v0.1.0                      # generic-boot (default)
$ scripts/build-bundle.sh --arch amd64 --version v0.1.0 --variant stock
$ scripts/build-bundle.sh --arch amd64 --version v0.1.0 --variant introspection

The released tarball is a generic-boot build, so the plain

# curl -fsSL https://raw.githubusercontent.com/NOFireAI/brig-standalone-linux/main/install.sh | sh -

installs generic-boot. introspection needs more than the build gives today; the list is below.

What each variant is

generic-boot (default) boots an ordinary OCI image, ubuntu:latest included. urunc starts a VM, so it needs a kernel, and a stock container image has none: on ubuntu:latest the whole of /boot is empty. The tarball carries a kernel and an initrd from outside the image, named per run by annotation. This is the runtime brig drives on Linux for claude-code, codex, gemini, grok, opencode and ubuntu — six of the eight shipped profiles.

stock boots unikernels. A released urunc, the four monitors, containerd, nerdctl. This is what boots a rumprun or Mirage image, and it is the one variant whose urunc is fetched (--urunc-version) rather than built.

introspection is generic-boot plus the Option-C work: a sidecar spawned per container by the shim, a telemetry kernel, and the com.urunc.vmi.* annotations that tie them together.

How generic-boot is built

The two parts a generic boot needs, the runtime and the assets, are both produced by build-bundle.sh and packed into the tarball. The installer just unpacks them.

The runtime is built, then packed

No urunc release publishes a binary that boots a generic container. So the build compiles one, from urunc-dev/urunc at the commit build-bundle.sh pins (3c00b69, on branch feat/linux-hvi-v050), in a golang:1.26.8 container:

# docker run --rm -v <urunc>:/app -w /app -e HOME=/tmp golang:1.26.8 \
    sh -c "git config --global --add safe.directory /app && make static"

The static urunc binary is cgo, so it is built native to the target architecture rather than cross-compiled. The release builds each arch on its own native runner (amd64 on ubuntu-24.04, arm64 on ubuntu-24.04-arm), so no emulation is involved; only a hand cross-build on one host falls back to qemu/binfmt. The result, urunc and its shim, goes into the tarball. install.sh never builds; it unpacks what the build produced.

The kernel and the initrd are fetched

The two files a generic boot names are the guest kernel and the initrd. Both are fetched from hull-assets on both arches, the OCI artifact hull and brig already boot from, one tag per platform, pulled with the bundled oras:

ghcr.io/nofireai/hull-assets:<version>-linux-<arch>   immutable
ghcr.io/nofireai/hull-assets:linux-<arch>             moving

The build resolves the <version> tag once. The bundled cosign checks the signature on the digest it names, against the identity brig checks: the build-assets.yml workflow in NOFireAI/hull-assets. The build then pulls that digest. The artifact's layers are the files themselves, each named by its org.opencontainers.image.title, so each file's sha256 is its layer digest in the signed manifest.

The kernel is generic and not brig-specific. On arm64 it is the same file hull boots on macOS. pins.env records the bundle as KERNEL_SOURCE and INITRD_SOURCE, by the digest the build pulled. share/guest/SHA256SUMS holds the sha256 of the kernel and the initrd, and each release publishes it as <bundle>.boot-assets.sha256: see the README.

The initrd has to match urunc. brig execs into a guest through the exec agent in urunit, whose wire protocol (pkg/agentproto) is a contract with the urunc shim. Since hull-assets 0.1.11, its initrd is one binary:

  • /urunit, static, from NOFireAI/urunit at the commit urunc pins in packaging/container-initrd/urunit.pin. It is the early init (/init, /vz-init and /urunit-agent are links to it), the PID 1 supervisor and the exec agent.

hull-assets records the urunc it built from in its signed bundle.json, as sources.urunc.ref. scripts/check-assets.sh refuses the bundle unless that is the urunc this tarball carries. hull-assets does not record its urunit commit yet; when it does, the check requires the commit urunc pins. hull-assets' own build checks that urunit is built for the target architecture. The installer just fetches and unpacks the tarball; it never builds an initrd.

The initrd must not be compressed, and the build and the runtime both check it. The runtime appends the container's argv, environment and network identity to a copy of it, and concatenated cpio works only while both halves are uncompressed. A gzipped one accepts the append and boots without it.

The annotations that carry the pair are com.urunc.unikernel.bootKernel and com.urunc.unikernel.bootInitrd, pointing into share/guest/. hull takes the same pair on its command line on macOS, and urunc reads it out of the container's OCI spec on Linux. That pair is the whole contract between brig and urunc.

Why introspection is not a one-liner yet

Further off, for four reasons.

The patches are not upstream. Thirteen of them, kept locally under option-c-patches/urunc, based on bef4a2e rather than main. Until they are on a branch somewhere fetchable, there is nothing to build from. Upstream urunc ignores annotations it does not recognise, so a stock binary given the Option-C annotations boots nothing and reports no error worth reading.

The artifacts are large. The matrix consumes four products of one kernel build, and they are not interchangeable:

artifact annotation consumed by
arch/x86/boot/bzImage com.urunc.vmi.boot_kernel hvi, qemu
vmlinux.btf com.urunc.vmi.boot_kernel firecracker, cloud-hypervisor
vmlinux (~392MB) com.urunc.vmi.kernel the symbol and BTF source
vmlinux.BTF com.urunc.vmi.btf hvi's in-VMM walk

boot_kernel differs per monitor, an ELF for the loaders that want one and a bzImage for the rest. And vmlinux at 392MB does not belong in a tarball that is otherwise ~106MB, so these stay host inputs rather than becoming tarball content.

The sidecar is a second binary with its own lifecycle. The shim spawns and reaps it per container. build-bundle.sh would install it as bin/sidecar; where its build comes from is unsettled.

hvi is a fifth monitor from a different repo. The matrix scores hvi beside firecracker, but hvi is released by brig-sh/hvi-vmm, not by the monitors release the build draws from. build-bundle.sh fetches it as a second source.

Running the matrix

scripts/optc-matrix.sh drives the introspection variant and scores what came up. It checks the installed urunc for com.urunc.vmi.boot_kernel first and refuses a stock binary, rather than printing a table of zeroes.

# KBUILD=~/kbuild/linux-6.18.34-telem-builtin scripts/optc-matrix.sh

Open questions

  1. Does generic-boot ship as its own tarball, or as one tarball with the guest assets optional? A separate build keeps a stock tarball small.
  2. Where do the Option-C patches live once they are pushed? A branch is enough to build from; upstream is better.
  3. Settled: the guest kernel is fetched from hull-assets, by the same tags hull uses, and checked against its signature; the runtime is built from urunc-dev/urunc at a pinned commit (3c00b69, on feat/linux-hvi-v050); and the initrd comes from the same hull-assets bundle as the kernel, which the build refuses unless it was built from that urunc. urunc is pinned to a commit because a branch tip moves with every push; the README's build section says how to move it.
  4. Settled: build-bundle.sh fetches hvi from the brig-sh/hvi-vmm release hull ships on macOS (v0.1.0-rc.2). scripts/fetch-hvi.sh checks the cosign signature on its SHA256SUMS, the pinned sha256 of the tarball and the commit its manifest names.
  5. Is introspection a variant at all, or generic-boot plus an opt-in flag? Everything it adds is additive, which argues for the flag.