Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,12 @@ jobs:
grep -qx "URUNC_PINNED=true" "$p" || { echo "pins.env does not say URUNC_PINNED=true"; exit 1; }
grep -qx "ASSETS_URUNC_REF=$want" "$p" \
|| { echo "pins.env does not carry ASSETS_URUNC_REF=$want"; exit 1; }
# hull is built from a pinned commit the same way.
want="$(sed -n 's/^HULL_REF_DEFAULT=\([0-9a-f]\{40\}\)$/\1/p' scripts/build-bundle.sh)"
[ -n "$want" ] || { echo "no HULL_REF_DEFAULT in build-bundle.sh"; exit 1; }
grep -E "^HULL_(REF|PINNED)=" "$p"
grep -qx "HULL_REF=$want" "$p" || { echo "pins.env does not carry HULL_REF=$want"; exit 1; }
grep -qx "HULL_PINNED=true" "$p" || { echo "pins.env does not say HULL_PINNED=true"; exit 1; }
# hvi is fetched from the release the script pins; fetch-hvi.sh
# fails the build unless its signature and sums check out.
grep -E "^HVI_(VERSION|COMMIT)=" "$p"
Expand All @@ -193,6 +199,56 @@ jobs:
grep -E "^URUNIT_(REPO|REF)=" "$p"
grep -qx "URUNIT_REF=$want" "$p" || { echo "pins.env does not carry URUNIT_REF=$want, urunc's pin"; exit 1; }

# brig tells the Linux hull from the macOS one by the platform at the end
# of hull --version, and reads the version before it: a v0.0.0 hull,
# which a build without hull's tags gives, is one too old to pin boot
# images by digest. The launcher has to hand brig the binary of the
# runtime it asked for: nerdctl by default, hull when BRIG_RUNTIME=hull.
# The launcher is sourced as this runner's user, so a rootless bundle
# takes its non-root branch.
- name: Check hull and the launcher
run: |
set -eu
d="$(mktemp -d)"
tar -xzf "$(ls dist/*.tar.gz)" -C "$d"
t="$(echo "$d"/*)"
v="$("$t/bin/hull" --version)"
echo "$v"
case "$v" in
*"linux/${{ matrix.arch }})") ;;
*) echo "hull --version does not end in linux/${{ matrix.arch }}"; exit 1 ;;
esac
case "$v" in
"hull v0.0.0"*|"hull dev"*) echo "hull has no version from its tags"; exit 1 ;;
esac
# The tree is unpacked here, not at the prefix it was built for, and
# the launcher's paths name that prefix.
prefix="$(sed -n 's/^PREFIX=//p' dist/*.pins.env)"
launcher() {
env -i HOME="$HOME" PATH=/usr/bin:/bin "$@" \
sh -c ". '$t/etc/brig-env.sh'; echo \"\$BRIG_RUNTIME \$BRIG_RUNTIME_BIN \$NETCONFPATH\""
}
case "${{ matrix.rootless }}" in
rootless) net="$HOME/.config/brig/cni/net.d" ;;
*) net="$prefix/etc/cni/net.d" ;;
esac
got="$(launcher)"
[ "$got" = "nerdctl $prefix/bin/nerdctl $net" ] \
|| { echo "default launcher: got '$got'"; exit 1; }
got="$(launcher BRIG_RUNTIME=hull)"
[ "$got" = "hull $prefix/bin/hull $net" ] \
|| { echo "BRIG_RUNTIME=hull launcher: got '$got'"; exit 1; }
got="$(launcher BRIG_RUNTIME=hull BRIG_RUNTIME_BIN=/opt/hull NETCONFPATH=/opt/net)"
[ "$got" = "hull /opt/hull /opt/net" ] \
|| { echo "the launcher overrode the caller's values: got '$got'"; exit 1; }
# Sourced again after a switch of runtime, as a second eval of
# brig-ctl env does, the launcher drops the binary it set the first
# time and names the new runtime's.
got="$(env -i HOME="$HOME" PATH=/usr/bin:/bin \
sh -c ". '$t/etc/brig-env.sh'; BRIG_RUNTIME=hull; . '$t/etc/brig-env.sh'; echo \"\$BRIG_RUNTIME \$BRIG_RUNTIME_BIN\"")"
[ "$got" = "hull $prefix/bin/hull" ] \
|| { echo "the launcher re-sourced for hull kept nerdctl: got '$got'"; exit 1; }

- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: bundle-${{ matrix.arch }}-${{ matrix.rootless }}
Expand Down
4 changes: 2 additions & 2 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,9 @@ now done and is what `install.sh` and `scripts/build-bundle.sh` produce.
fetches nothing else. Because the config files carry the fixed layout, the paths
above are not configurable at install time.
- **Why urunc is built (at release).** Most components are upstream release
artifacts, hvi among them (`brig-sh/hvi-vmm` `v0.1.0-rc.2`, cosign-verified).
artifacts, hvi among them (`brig-sh/hvi-vmm` `v0.1.0-rc.3`, cosign-verified).
urunc has no release that carries what brig needs, so the build compiles it
from `urunc-dev/urunc` at commit `3c00b69`, on `feat/linux-hvi-v050` (CGO
from `urunc-dev/urunc` at commit `5c6bc70`, on `feat/linux-hvi-v050` (CGO
static, so native per arch under qemu/binfmt). The source is pinned to a
commit, since a branch tip moves with every push. The README's build section
says how to move the pin.
Expand Down
51 changes: 46 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ $ sha256sum -c checksums.txt --ignore-missing
data/ immutable, unpacked from the tarball:
bin/ brig, brigd, brig-broker (from a brig release that carries it),
urunc, containerd-shim-urunc-v2, containerd, ctr,
runc, nerdctl, cosign, oras, hvi, firecracker,
runc, nerdctl, hull, cosign, oras, hvi, firecracker,
cloud-hypervisor, solo5-hvt, solo5-spt, brig-ctl,
brig-pool-up, brig-uninstall.sh
libexec/ virtiofsd
Expand Down Expand Up @@ -186,6 +186,38 @@ $ curl -fsSL https://raw.githubusercontent.com/NOFireAI/brig-standalone-linux/ma
[docs/rootless.md](docs/rootless.md) has the detail, including the two things
that still need root once per host, and what a home install gives up.

### hull beside nerdctl

nerdctl is brig's runtime here. The bundle also carries hull, the runtime brig
drives on macOS, built for Linux: a containerd client that boots the same urunc,
monitors and guest assets. `BRIG_RUNTIME=hull` selects it, and the launcher then
points brig at the bundle's hull rather than its nerdctl:

```console
$ BRIG_RUNTIME=hull brig doctor
```

It needs a brig that drives hull on Linux, which the `v0.5.0` in this bundle
does not. Even then, hull on Linux boots a sandbox on the shared bridge or with
no network, and brig refuses what it cannot enforce there yet: an egress policy,
a route, `network: isolated` and a published port. The shipped agent profiles
ask for an isolated network, so they stay on nerdctl for now. Every value the
launcher sets still defers to the environment, so `BRIG_RUNTIME_BIN` points brig
at another hull.

The launcher works out the binary each time it is sourced. A shell that has run
`eval "$(brig-ctl env)"` has the bundle's `bin/` first on its `PATH`, so `brig`
there is the binary itself and nothing sources the launcher again: set
`BRIG_RUNTIME` before the eval, or run the eval again after changing it.

```console
# export BRIG_RUNTIME=hull
# eval "$(/var/lib/brig/data/bin/brig-ctl env)"
```

hull takes no snapshotter from the environment, so `CONTAINERD_SNAPSHOTTER`
reaches nerdctl only: hull uses the namespace's default unless brig passes one.

## Driving the runtime by hand

`brig-ctl` wraps the private stack for when you want `ctr` or `nerdctl`
Expand Down Expand Up @@ -280,14 +312,15 @@ the install does not. Running `build-bundle.sh` by hand to cross-build the other
architecture needs qemu/binfmt instead of a native runner.

`build-bundle.sh` fetches the components that have upstream releases and builds
urunc, which has none:
urunc and hull, which have none for Linux:

| Component | Source | In the tarball |
| --- | --- | --- |
| brig, brigd, brig-broker | `brig-sh/brig` release | fetched, verified against its signed `checksums.txt` |
| urunc, containerd-shim-urunc-v2 | built from `urunc-dev/urunc` at commit `3c00b69` (branch `feat/linux-hvi-v050`) | CGO-static, built in a Go container |
| hvi | `brig-sh/hvi-vmm` release `v0.1.0-rc.2` (commit `2ed8f61`), the one hull ships on macOS | fetched, musl-static; its `SHA256SUMS` cosign-verified against hvi-vmm's release workflow, the tarball pinned by sha256 |
| guest kernel, container-initrd | `ghcr.io/nofireai/hull-assets` `0.1.11` | fetched by digest once its cosign signature checks out; the initrd is urunit. urunc's `packaging/container-initrd/urunit.pin` names `48a61bd`; hull-assets `0.1.11` does not record its urunit, so the bundle records that commit as `urunit_expected`. The build refuses a hull-assets bundle built from another urunc |
| urunc, containerd-shim-urunc-v2 | built from `urunc-dev/urunc` at commit `5c6bc70` (branch `feat/linux-hvi-v050`) | CGO-static, built in a Go container |
| hull | built from `brig-sh/hull` at commit `4bf76a6` (branch `main`), which publishes no Linux release | static (`CGO_ENABLED=0`), built in a Go container, with no telemetry endpoint |
| hvi | `brig-sh/hvi-vmm` release `v0.1.0-rc.3` (commit `bde7c58`), the first whose Linux build takes `--net-gateway`; hull pins its own hvi for macOS (`hvi.pin`) and does not check this one | fetched, musl-static; its `SHA256SUMS` cosign-verified against hvi-vmm's release workflow, the tarball pinned by sha256 |
| guest kernel, container-initrd | `ghcr.io/nofireai/hull-assets` `0.1.12` | fetched by digest once its cosign signature checks out; the initrd is urunit. urunc's `packaging/container-initrd/urunit.pin` names `48a61bd`; hull-assets `0.1.12` does not record its urunit, so the bundle records that commit as `urunit_expected`. The build refuses a hull-assets bundle built from another urunc |
| monitors, virtiofsd | `urunc-dev/monitors-build` | fetched, pinned by sha256 |
| containerd, runc, nerdctl, CNI | upstream releases | fetched, upstream checksums |
| cosign | `sigstore/cosign` | fetched, pinned by sha256 |
Expand Down Expand Up @@ -341,6 +374,14 @@ A branch given without a ref is refused, since it is unclear which of the two
was meant. A tip build also has to match the guest assets (below), so it fails
unless `ASSETS_VERSION` names a hull-assets release built from that tip.

hull is pinned the same way, with `HULL_REF_DEFAULT` and `HULL_BRANCH_DEFAULT`,
recorded in `pins.env` as `HULL_REF` and `HULL_PINNED`, and `HULL_REF` and
`HULL_BRANCH` work as their urunc counterparts do. The two pins move together:
hull on Linux writes urunc's annotations, and hull checks them against one urunc
commit (its `internal/urunckeys`), which has to be this bundle's urunc. The
build reads that commit from the hull checkout and refuses a hull written against
another urunc.

### The initrd comes from hull-assets, checked against urunc

brig execs into a guest through the exec agent in urunit, whose wire protocol
Expand Down
8 changes: 4 additions & 4 deletions docs/variants.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ by `build-bundle.sh` and packed into the tarball. The installer just unpacks the

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
(`5c6bc70`, on branch `feat/linux-hvi-v050`), in a
`golang:1.26.8` container:

```console
Expand Down Expand Up @@ -161,12 +161,12 @@ refuses a stock binary, rather than printing a table of zeroes.
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
(`5c6bc70`, 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
4. Settled: `build-bundle.sh` fetches hvi from a signed `brig-sh/hvi-vmm`
release (`v0.1.0-rc.3`). `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?
Expand Down
6 changes: 3 additions & 3 deletions nix/urunc.nix
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@
# commit is the one the bundle release records in its pins.env as URUNC_REF.
buildGoModule (finalAttrs: {
pname = "urunc";
version = "0-unstable-2026-10-29";
version = "0-unstable-2026-11-10";

src = fetchFromGitHub {
owner = "urunc-dev";
repo = "urunc";
rev = "3c00b69ff9ac1b8bb260975cdc63d18a7043558b";
hash = "sha256-NbH+6nQWLEgcI2VBmtA/50EHbMB8Q1k4RJk67miYXtU=";
rev = "5c6bc7060d4f6d33b0d4e8fd388f9f04cc88510b";
hash = "sha256-XKgvsGtmKeJfDAyDmJ4YtJyC4tkjTHv8nZEcWjKro2I=";
};

vendorHash = "sha256-08PC8ethomYCZTBfP1PVCCXgXeyrSHHoozcVsWmqJUE=";
Expand Down
Loading