SPEC records the two macOS facts the code bends around (bare-soname
dlopens needing startup-time DYLD paths; the hypervisor entitlement)
and the packaging decisions; README gains the brew install and the
from-source sign step.
CI runs fmt/clippy/test plus a real alpine boot on a macos-26 runner
with libkrun from the krun tap; the release workflow ships a signed
darwin-arm64 tarball beside the snaps. The formula installs from the
tap, carries the runtime kegs (libkrun, e2fsprogs, libarchive), and
codesigns the binary with the hypervisor entitlement — Hypervisor
.framework grants VM creation only to entitled binaries on current
macOS, the same requirement krunkit's formula signs for.
The engine's dlopen of libkrunfw and mke2fs's of libarchive use bare
sonames, and dyld reads DYLD_FALLBACK_LIBRARY_PATH once, at process
startup — a setenv afterwards is invisible to it. When the variable
is unset and the brew kegs exist, the CLI sets it and execv's itself:
exec restarts dyld, which reads the variable fresh. Library consumers
set the variable before their process starts instead (SPEC.md).
The cache-seeding tests seeded entry names under amd64 but resolved
the request against the host arch, so on an arm64 host the lookup
missed and the tests walked into the network path. Requests now pin
arch, matching the seeded names on any host. The tool gate uses
find_tool: on macOS the e2fsprogs binaries are keg-only, never on
PATH.
mke2fs built against libarchive populates an ext4 from a tarball in
one pass; Homebrew's bottle is not built that way, so when the found
mke2fs cannot take a tarball the builder unpacks the rootfs with the
library's own tar decoder and populates from the directory — slower,
and the run says so. The mkfs child is exec'd fresh, so it reads
DYLD_FALLBACK_LIBRARY_PATH (libarchive's keg) at startup.
The engine is libkrun.1.dylib, dlopen'd from the Homebrew kegs when
the loader's own search fails (bare sonames never reach the brew
prefix); the probe becomes a per-platform hypervisor probe — KVM on
Linux, sysctl + a real hv_vm_create on macOS, so an entitlement
denial (HV_DENIED) names the re-sign fix instead of surfacing as an
opaque krun_start_enter EINVAL. Tool lookup (mke2fs, debugfs) gains
the same keg fallback, and dyld_fallback_dirs() collects the kegs the
bare-soname dlopens (libkrunfw, libarchive) need in
DYLD_FALLBACK_LIBRARY_PATH. The machine child's parent-death contract
moves to a kqueue NOTE_EXIT watcher: macOS has no PR_SET_PDEATHSIG,
and SIGKILL-on-parent-exit is what keeps a killed caller from
stranding a booted machine.
The payload's stdout is a serial console, so fastfetch reads a tty
and decorates its output with cursor escapes; the ^OS: anchor
matched nothing and would have failed a green run. --pipe --logo
none prints a plain key-value list, and a sed strips anything left
before the grep. SPEC records the first measured apt wall time: 24 s
cache-warm, boot included.
The snap only got built at tag time, so the pack rotted between
releases; ci now packs it on every change, the same action the
release workflow uses, and boots it twice: an alpine uname check
that proves the machine virtualized under strict confinement, and
apt update + install fastfetch on ubuntu, which is T8 — a real
package install through the TSI proxy, the staged e2fsprogs, and
the exit-code path, with the wall time as the standing
re-measurement of the ln driver's throughput.
utils::detect_shell lost to the image probe; krun_set_root and
krun_set_env have had no caller since the root crossed as a block
device. Unused FFI bindings rot where they stand.
The early return keyed on files alone, so an unlink-only call was a
silent no-op. No caller passes an empty file set today, but the
signature invites one, and the control-file unlink is the case that
must never vanish.
The fork contract lived in a comment inside run_prepared; an
embedder meeting it first in the public API docs, with the
fork-with-threads hazard spelled out, has a chance of honoring it.
Resolution ran before the cache was consulted, so every run of
alpine:3.23, ubuntu or any floating alias hit the CDN or
changelogs.ubuntu.com, and an offline run of a cached image died in
resolution instead of booting. The boot path now asks the cache
first: an alias boots the newest cached entry of its distro, within
the series or the edge flavor it floats in, and resolves upstream
only on a miss; pull and --no-cache still resolve upstream.
Exactly-named references (Ubuntu YY.MM, known codename, Alpine X.Y.Z)
resolve offline on every path; resolve_source folds into the policy,
which lives with the cache it consults.
Only :latest was treated as floating; any other unpinned tag skipped
the registry digest check, so a moved :v1.2 kept booting stale. Tags
are mutable pointers, that is what digest pins exist for; the pin
skip stays, the tag skip goes.
mke2fs creates and sizes the output file before it populates it, so a
build that failed mid-way left a recent-looking image full of zeros at
the final name - newer than the tarball, and trusted by the freshness
check forever after. The first run after the libarchive fix booted
exactly that wreckage: EXT4-fs "Can't find ext4 filesystem".
The build now lands in a sibling .part file and renames over the image
only on success, and the freshness check additionally requires the
ext4 superblock magic (s_magic, at byte 1080) before trusting an
existing image - caches already carrying wreckage rebuild over it on
the next run instead of needing a manual clean.
Same dlopen as the snap stages for: the runner has e2fsprogs but not
the lib, and the first cold pull would fail. The t64 name with a
fallback keeps it honest if the runner image changes base.
Populating an ext4 image from a tarball is a runtime dlopen of
libarchive in mke2fs, not a linked dependency: the deb does not pull
it in, the stage set did not have it, and the first snap build failed
with "you need libarchive to be able to process tarballs". Stage
libarchive13t64 next to e2fsprogs.
The design paragraphs follow the code: the rootfs crosses as a raw
ext4 image built from the tarball, ownership is real inside the
machine, provisioning rides debugfs, and the control file mints the
exit code because the engine's own channel is virtiofs-root only.
The confinement budget admits the e2fsprogs children and cp, the
snap section stages e2fsprogs and names the blk feature, and the
boot-economics row counts an image copy instead of an extraction.
The run path shells out to mkfs.ext4 and debugfs from e2fsprogs; a
host without them fails at the first pull, so probe names them up
front like it names KVM and the engine.
The T6 run boots from a block device now; an engine without the blk
feature fails the lookup for krun_add_disk and the audit never sees a
machine. Same feature set as the snap ships.
The rootfs boots from a virtio-blk disk now, and the blk feature is
what compiles the device into libkrun - without it krun_add_disk and
krun_set_root_disk_remount have no symbols and every run fails at
lookup. e2fsprogs joins the stage set for mkfs.ext4 (the cache image
build) and debugfs (per-run provisioning and the control-file read);
core26 ships 1.47.4, which knows how to build from a compressed
tarball.
The rootfs was a virtiofs share over an extracted tree, and that
showed: the tree's owners were the host user's, because an
unprivileged extract cannot chown to a tar's uid, and every chown
inside the machine failed with EPERM against the host side.
The rootfs crosses as a raw ext4 image now. mke2fs builds the cache
image straight from the entry tarball (-d takes gz, xz and zst, and
bakes each entry's recorded uid, gid and mode), the run copies it
into a scratch directory with cp --reflink=auto --sparse=auto, and
the engine attaches it with krun_add_disk +
krun_set_root_disk_remount; the init blob mounts /dev/vda at / and
chroots. The OCI layer bundle merges into one plain tar first, with
whiteouts applied across layers and headers passed verbatim, so
registry images keep their ownership too.
Per-run provisioning rides debugfs: the generated init lands at
/ecrou-init, the host resolver overwrites /etc/resolv.conf (unlink
first - resolver-bearing images ship it as a symlink), a stale
control file goes. The exit-code control file now outranks the
machine child's exit code: with a block root the engine's exit-code
channel (an ioctl through the virtiofs root device) never fires, so
decode_status reads the file first and treats the child's code as
machinery talk. Shell detection and the rare control-file read are
debugfs stats, no extracted tree to walk.
extract.rs keeps what the image build consumes (the tar decoder and
the OCI merge) and drops the extraction-to-disk path it once carried;
the module is private now. The engine needs the blk feature from here
on: the snap and the CI engine build follow in their own commits.
The summary takes the README tagline. The description now leads with
an Install section, shows a first run that opens a shell, and leaves
the XDG redirection internals out of the listing.
The version: key in snapcraft.yaml was a second number to bump by
hand, and between releases it read whatever it was left at. The ecrou
part now sets its version from [workspace.package] at pull time —
the same value clap reports with --version — so Cargo.toml is the
only place a version lives, and the release workflow stamps only
that. A missed match fails the pack loudly.
The pack lint flagged five empty metadata fields. They render on the
snapcraft.io listing, and contact is asked for at publish time. The
repo answers for website, source-code, and contact (the issue tracker,
since the listing is public); title matches the binary name.
The list view now says what each command does in the plainest verbs:
run boots a command from an image, pull downloads one, probe checks
the requirements. The long help keeps the contracts — freshness
semantics, what probe actually tests.
The runtime runs images; building them belongs to the OCI ecosystem —
CI builds, digests, scanning — and a keyed local layer could never
offer a digest. Provision also installed packages through TSI, whose
per-stream throughput makes a real package install crawl exactly at
first use, and the bare-command shape mutated the shared cache entry
under the image's own name.
0.1 runs images: run, pull, probe — distro aliases, OCI references
with digest pins, local rootfs archives. The one honest idea provision
carried stays in SPEC's Later: provision by booting, for locked-down
hosts that cannot run any builder.
The keyed-layer design shipped: provision --spec hashes the spec with
its base reference and --layer names the entry for run --layer. The
row was describing the past as the future; what remains is eviction.
Each command keeps a crisp one-liner in the command list and carries
its contract in the long help: how an image reference resolves, what
provision's two shapes do, why pull exists (run never contacts a
registry on a cache hit), and what probe checks. Flag help states the
real constraints instead of the shortest noun phrase: the guest path
of a share must be absolute, the host environment is never inherited,
--capture is refused with --tty, --quiet silences engine and kernel
messages.
The code is the source of truth now; what stays is the part code
cannot carry — the founding rule and confinement budget (fixed: the
budget said no child process, the machine child is one), the run
contracts (exit codes rewritten to match the engine-failure and
reserved-code semantics), the trust model, the falsification tests,
and the roadmap.
Cut: the engine call list, the RunOptions listing, the CLI flags
table, the cache layout tree, the workspace/module map, the ecr
porting table, and the open questions — all answered or all mirrors
of code that answers them faster.
libkrunfw5 ships for riscv64 in ubuntu-ports, not the main archive
(archive.ubuntu.com carries amd64 and arm64 binaries); the part now
maps each target arch to its pool and a pinned digest.
The remediation hard-coded kvm_intel, wrong on arm64 and riscv64
which the snap now ships. x86_64 keeps the vendor split (kvm_intel,
kvm_amd) and the nested-virt parameter file; everywhere else KVM is
one module and the nested pointer is not actionable.
A parent-side failure after the fork (a console stat or read that
went wrong, a wait that could not complete) used to return and leave
the VM booting unattended. PDEATHSIG only fires when the caller's
process exits; a library consumer that catches the error keeps
running, and the scratch rootfs goes away under the machine.
kill_machine is best effort: a machine that already exited reaps
through ECHILD. Also drops a duplicated fork-error block left behind
by the supervise split.
Only the guest init can mint a guest code: it reports the payload's
code through the control file and the VMM exits the child with it. A
signal on the machine child therefore means the VMM or the engine
died; mapping it to 128+n masqueraded an OOM-killed VMM as the
payload having died by that signal (T3).
125 and 126 keep their two-sided reading: the child bails with 125 on
a boot failure and the init refuses with 126 on a failed share or a
missing workdir, but a payload may genuinely exit either code — the
control file is the arbiter, and a run that never reached the payload
is an error naming the cause.
The SPEC bar for T6 is failure on a single hit from the denied set;
the errno-based check only caught attempts the snap's seccomp
allowlist had already denied, so a host mount that succeeded would
have passed. Exact-name matching over the traced call also stops
"mount" matching "umount2" lines.
The test has been declared as CI-only since it landed and never ran
anywhere. The job builds the engine from the tag the snap bundles,
takes libkrunfw from the pool, opens /dev/kvm, and runs the ignored
test with ECROU_BIN and LD_LIBRARY_PATH pointed at them.
The arm64 runner leg builds that platform natively, where libkrun
compiles and the libkrunfw part picks the arm64 pool .deb on its own.
Both snaps upload as artifacts and publish to stable from one job.
The pool carries an arm64 libkrunfw5 next to the amd64 one, so the
part now picks the flavor and the install path from the target arch
(CRAFT_ARCH_BUILD_FOR / CRAFT_ARCH_TRIPLET_BUILD_FOR) with the
checksum pinned per arch. riscv64 goes: the pool has no libkrunfw5
build for it, and libkrun does not target it.
Fetch or refresh an image's cache entry without booting it. The
command is the CLI face of the run/pull split: runs never contact a
registry on a cached image, pull does - reporting the entry path
and whether anything transferred. --no-cache forces a redownload.
SPEC documents the command and the run/pull trust model.
prepare was a freshness hybrid: runs of an unpinned OCI tag contacted
the registry on every boot, and only ":latest" was checked - :main
floated in name only. Docker's split is cleaner, so it is the model
now: prepare (and run) trust a present entry and never touch the
network on a hit - a cold cache pulls by default, since there is
nothing to boot otherwise. RootfsCache::pull is the refresh
operation: re-check any unpinned tag against the registry digest,
re-resolve floating distro aliases, download only what moved,
extract nothing. Digest pins stay immutable to both. The trade, as
in docker: a stale :latest boots until someone pulls.
Local archives are not pullable - the error says so.
A run blocked on the cache-entry flock was silent: the wait went to
the log sink, which renders nowhere by default, so the CLI read as
a hang. The Progress trait gains message() - a status line outside
the counted-operation protocol, defaulting to a no-op so existing
sinks keep compiling - and the flock wait reports what it is
waiting for. The CLI renders messages on the active bar and spins
one up when no operation is active.
generate_cache_filename derived a distro tarball's extension by
resolving its URL - a naming function with a network dependency and
a silent unwrap_or_default degradation. Naming is now pure string
shaping: distro artifacts are gzipped tarballs, so the name says
.tar.gz, and a future artifact format changes extraction and this
line together. Same filenames as before for every existing entry;
a caller skipping resolve_source now gets a deterministic key
instead of a lookup.
The cache stopped being an implementation detail of the rootfs
lifecycle: entry naming, the advisory lock, digest freshness,
provisioned-layer pointers, and extraction-to-scratch are a store
in their own right. cache.rs now owns RootfsCache's paths, pointers
and extraction products; rootfs.rs keeps the lifecycle API
(PrepareRequest, PreparedRootfs, prepare, prepare_provisioned).
resolve_source moves next to its inputs in distro. Pure movement -
naming still derives its extension from the URL, next commit
changes that.
entry_path spliced the layer key into the cache filename raw: the
guard lived at the write/extract/prepare boundaries, so a library
consumer deriving paths through resolved_entry_path could get a
path outside the cache directory instead of the named error.
entry_path now returns Result and validates, prepare drops its now
redundant pre-check.
Ubuntu tarballs came from the daily/current directories - moving
targets, no published checksums guarantee, gone when a release
EOLs. resolve_ubuntu_url now builds the cdimage release URL:
ubuntu-base/releases/<YY.MM>/release/ubuntu-base-<YY.MM>-base-<arch>.tar.gz,
whose SHA256SUMS the existing checksum verification consumes.
Resolution returns the YY.MM number (the cache key follows), and
accepts the codename interchangeably: a static table maps the
known codenames offline - ubuntu:resolute and ubuntu:26.04 are the
same image and the same entry - with meta-release as a fallback
for codenames newer than the table. Floating aliases (latest/lts)
still consult meta-release; explicit numbers never touch the
network, which also removes the per-cache-path network lookup
generate_cache_filename used to trigger for codename inputs.
URLs verified live: tarball and SHA256SUMS both 200.
vhaudiquet