About Barn

• 1: Design
• 2: Status
• 3: Engineering

1 - Design

One useful abstraction

Barn boots one Pigsty Inventory as one local QEMU deployment. It deliberately has no project marker, project registry, lease model, provider layer, or second configuration format.

State lives under BARN_HOME (default ~/.barn) for one Unix user. The product assumes one active Pigsty deployment per computer; this is not a root-enforced cross-user singleton.

Node-level convergence

Barn extracts only the documented VM and Pigsty-native fields, computes per-node hashes, and keeps applied state plus process identity. Additions are incremental. Changes require an explicit per-node recreate. up also starts selected existing stopped nodes; already-running peers keep their processes while unfinished guest setup and managed hosts/SSH entries are refreshed. Unrecognized or confirmed damaged test data filesystems may be reset, including persistent disks; see Data disks. Absence never authorizes deletion.

Runtime selection

Guest architecture is deployment-wide desired state. Omitted/native follows the host; explicit amd64 or arm64 selects that Catalog artifact exactly. Native HVF/KVM remains the default. A foreign architecture or one catalogued image/host incompatibility selects a fixed TCG profile; there is no user accelerator argument and no arbitrary failure fallback.

The effective architecture and accelerator are persisted in each QEMU invocation and exposed by status. Before destructive recreate, Barn proves the selected QEMU binary and version, network backend, image bytes, boot mode, and firmware. A later binary changing runtime policy cannot mix new nodes with old invocations: runtime drift requires whole-deployment recreation.

Two NICs, one fixed subnet

The management NIC supplies DHCP, DNS, egress, and loopback SSH. The fixed-IP NIC supplies host/peer/Ansible traffic. macOS uses socket_vmnet. Linux follows active NetworkManager; otherwise it uses systemd-networkd and connects through the distribution bridge helper. Inactive networkd is started only after an activation-safety scan proves existing units cannot claim a real host link.

On Debian, the helper is temporarily and reversibly scoped to a group the caller actually belongs to. A real unprivileged QEMU bridge smoke must pass before setup accepts the network; failure rolls the install back automatically.

Storage and configuration have different lifetimes

The Inventory records desired VM definitions. Applied state records what was created, including the exact base-image identity and runtime invocation. Changing a Catalog channel does not rewrite an existing root disk.

Verified base images are shared read-only; each VM writes to its own root overlay. Data disks have a separate preservation contract: normal destroy retains persistent disks, while explicit disk deletion or purge removes them. Cache pruning has another boundary and also protects the active Catalog and registered local aliases. See Storage and access and Images.

Safety boundary

QEMU and all guest artifacts run as the caller. Root is limited to host package installation, network setup, and the optional hosts publisher. Destruction requires matching ownership, containment, node identity, QMP/process identity, and an allowlist of artifacts. Ambiguity stops the operation.

2 - Status

Barn 0.9.0 is the first release candidate under the new name and is not yet published. Source checks, local builds, packages, CI, releases, and the public site are verified separately. Renamed source alone does not establish public delivery. Installation instructions are in the Quick Start.

Documentation baseline

Stop old internal environments and preserve needed data before creating a fresh Barn installation. Do not simply rename an old state directory. The final release commit, artifact digests, Homebrew and public endpoints will be recorded after verification. Historical 0.2–0.8 records keep the Farrow name and do not establish Barn 0.9.0 publication or acceptance.

macOS guests

barn mac runs macOS 27 guests on Apple Silicon; see the guide and reference. Its component is Barn Mac.app, with signing identifier io.pgsty.barn.mac-runner. It uses independent $BARN_HOME/mac state and has no command to migrate earlier development data.

After the rename on 2026-09-29, local CLI/hosts-helper tests, native Bridge/image/exit-prompt/menu tests, the runner build, ad-hoc signature checks and probe passed. These checks started no VM and did not repeat the complete Mac native lifecycle. Earlier native results retain their original identity below.

Remaining release checks

• The full source, archives, DEB/RPM, installer and cross-platform checks at the final Barn commit;
• Fresh host setup and Linux/macOS VM lifecycle and cleanup under the new names;
• Mac Developer ID signing, notarization and publication;
• The live GitHub repository, Homebrew, both image repositories and barn.pgsty.com.

The records below describe pre-rename checkpoints. Their old commands, paths, versions and links are historical evidence only.

Farrow Mac native record: 2026-09-29

The pre-rename Farrow development tree was validated on 2026-09-29 on an Apple Silicon Mac running macOS 27.0 (26A428), with an ad-hoc signed development build. No macOS image was downloaded for the run: every test home used an APFS clone of a base prepared on 2026-09-26 from Apple’s pinned 27.0 restore image.

• Source gates: complete make check, native component tests, and the Mac bundle build with extracted-archive checksum, signature, and probe checks passed.
• Automated live acceptance: all 16 phases passed in 244.9 s: creation from the base, a named machine with a shared folder, independent identities and sshd policy, disk isolation, per-machine networks isolated from each other, DNS and public HTTPS, exit codes and argument boundaries, bidirectional shared-folder writes, normal stop/start, configure, refusal of a third running VM, recreate rotating identities, desktop and two-way clipboard, repeated up leaving the base unchanged, and destroy.
• Manual checks: creation to SSH-ready in 22 s from a prepared base; normal stop 6.5 s; start to SSH-ready 6–12 s; forced stop 0.7 s; macOS Recovery boot; a subnet change keeping the pinned host key; ssh mac1 through the installed OpenSSH entries.

Still open for macOS guests: Developer ID signing, notarization, and a published release; downloading and installing macOS through the current CLI (a first up without a prepared base, or image update); the desktop’s Restart… and Shut Down… menu actions; other Apple Silicon models and macOS 27 updates; and physical-host reboot.

Pre-rename Linux validation summary

The 0.8 run covered Rocky Linux 9.8/10.2, Debian 12.15/13.7, and Ubuntu 22.04.5/24.04.5/26.04.1 on each host: 28 successful guest instances in total. The temporary acceptance VMs were subsequently cleaned up. Both public Catalogs have SHA-256 23e8dbf6c19bd192d56c6d71eb30901f17945b3487e427a43abe108463780306. Isolated farrow update runs at both endpoints verified the signatures and activated revision 2026092001. The public image check used HEAD/content lengths for ten new objects at each endpoint, not a fresh download/hash of every public artifact.

Coverage left open at the earlier checkpoint

• EL9 hosts with NetworkManager and firewalld, and a current systemd-networkd replay;
• physical-host reboot persistence;
• macOS amd64 and Linux arm64 native runs, beyond their build/package checks;
• EL7 through the current native Linux/amd64 lifecycle;
• macOS directory sharing: the tested QEMU cannot reopen Farrow’s securely held directory descriptor;
• a complete current Pigsty configure → farrow up → install.yml run;
• a native replay of the corrected fresh Homebrew socket_vmnet authentication path;
• clean-host setup and VM creation through the public installer, Homebrew, or published DEB/RPM packages.

Current built-in versions are supported, except EOL EL7 and the retained compatibility versions EL9 9.3/9.6 and EL10 10.0, which are deprecated. Active and standby Catalog public keys are embedded. Private-key custody and rotation, together with release custody, must be formalized before 1.0.

Farrow verification history

Each entry belongs to the exact checkpoint exercised that day. Later source or documentation edits do not inherit native proof without another replay.

Farrow 0.8.0 — 2026-09-21

Release tag v0.8.0 points to 320a32afa8f6fca02592215aa0d5607ca4e852b2. The source CI, independent packaging snapshot, and tag workflow passed. The tag workflow produced 20 assets, including 19 checksummed payloads. The publication commit changes only README and release notes relative to the tested runtime below; a new local build at the tag passed the archive/package checks.

The release became public on 2026-09-21. All 20 assets were downloaded anonymously through the host’s configured proxy, without GitHub credentials. Every request returned HTTP 200 and the full-body SHA-256 matched both the API digest and inspected draft; all 19 checksummed payloads matched the manifest. Public installers succeeded in isolated user directories on macOS arm64 and Linux amd64. Both reported 0.8.0 / 320a32a and installed exactly the CLI/helper bytes from their verified public archives. Linux downloads used a temporary SSH loopback forward to the existing proxy, removed afterward. Default installations and VM/network state stayed unchanged. These checks verify binary installation; fresh-host setup and VM creation through the public installer remain untested.

The Homebrew tap now selects 0.8.0 for all four targets with the public archive digests. Local syntax, updater tests, consistency/style/platform checks, strict online audit, and native arm64 brew fetch passed. Its macOS and Linux CI jobs also passed metadata, updater, style, platform, and audit checks. There was no new brew install, upgrade, relink, or brew test in this release verification.

The clean initialization baseline was 6d7870e26cb2f4082a00c188f746783fc027687e. On each of four hosts, the run removed the owned old lab and network, started from an empty Farrow user state/cache, and created the seven-system pro inventory using one LAN repository. Linux used the actual DEB; macOS used a complete checksum-verified user installation of the archive’s paired CLI/helper.

The runtime candidate 1c054a027420b5410c6f6feb344e27e001ae1af1 added the Homebrew authentication-order fix and passed complete local make check and release archive/package verification. It was installed in place on all four hosts, then passed healthy up, two rounds of guest SSH, stop/start, and Ansible configuration reads. Both Macs also passed Ansible ping on every node. VM UUIDs, image identities, and root/data disk paths and inodes were retained; healthy up also kept the running processes. All runs checked real data-disk access, Debian locales/XFS, and control-node SSH to the other guests.

This is a clean 6d baseline followed by a final 1c in-place lifecycle replay, not a second clean initialization at 1c. The new Homebrew ordering has a regression that fails before the fix and passes after it; the native clean runs used the pinned backend archive, so they do not exercise a new Homebrew formula install. No physical host was rebooted, and no full Pigsty installation or macOS shared folder was included. The release notes include the measured lifecycle samples and image versions.

Farrow 0.7.0 release — 2026-09-16

Release commit 9c6d4896d93733d1cb60a7e5d8591e9a06659c9d passed the complete source CI and independent packaging snapshot before tagging. The tag workflow repeated the gates and published a draft with 20 assets. After inspection, the release was made public; all 20 anonymous downloads returned HTTP 200 and matched the inspected bytes, including all 19 checksummed payloads. Public installers on macOS arm64 and Ubuntu amd64 installed the exact archive binaries. Download tests used the host’s configured proxy; m3 reached it through a temporary loopback tunnel. The pgsty/infra/farrow formula was refreshed to v0.7.0; a local Homebrew upgrade and brew test passed, while a clean-host formula install remains open.

The Ubuntu amd64/KVM recovery matrix covered corrupt ext4/XFS filesystems, retained disks, failed probes, busy mounts, read-only shares, and repeated healthy up without process replacement. A public 0.6.0 bootstrap failed its egress probe; 0.7.0 resumed that same VM in 3.3 seconds. Probe failure left existing disk data and UUID intact. The old 0.6.0 CLI still completed status, stop, start, and destroy after upgrade, including with a cached optional warning. A fresh VM from the final 0.7.0 archive booted without warnings and ignored the old VM’s cache.

The publicly installed Linux binary also reset a deliberately damaged disposable ext4 disk in 3.2 seconds, reported discarded data, and retained the running VM’s process. Stop, start, and purge then passed.

That interrupted 0.6.0 bootstrap had already deleted its staged control-node SSH key. Management access recovered, but missing peer SSH remained an explicit control-ssh limitation; see the upgrade notes. This release adds no guest images: Catalog 2026090501 remains unchanged. There was no new macOS HVF, host reboot, or complete Pigsty replay.

Farrow 0.6.0 release — 2026-09-05

The lifecycle and UX changes passed two adversarial Claude Code Fable 5.1 reviews at xhigh effort; release metadata and the CI test fixture received follow-up approvals. Release commit 057774e3a13477782a2ae07bd71127d03c0f1ae7 passed the complete Go 1.27.1 source CI. The latest packaging changes passed the independent snapshot and package checks at 13d9d70. The tag workflow repeated source checks and verified four platform archives, four Linux packages, eight SPDX documents, the installer, Homebrew formula, release metadata, and all 19 checksummed payloads before creating the 20-asset release. The release is public. All asset digests match the checksum manifest. An isolated macOS arm64 installation upgraded from public 0.5.0 to public 0.6.0; both installed executables match the verified release archive. The released binary also passed init and a fresh U24 plan.

An isolated macOS arm64/HVF U24 lab passed initial boot, expansion without restarting the control node, control-to-peer SSH, stop/start, normal reload, selected recreation, scale-in, and guest-name refresh. Invalid-image reload and conflicting selected recreation stopped before disrupting the existing VMs. Partial status kept the healthy peer visible, and SSH exit 255 passed through. Effective OpenSSH configuration tests covered the final guest SSH scope correction. The test lab was removed after validation.

Published Catalog 2026090501 defaults to u24:stable and incorporates the Debian/Rocky image updates already published in Catalog 2026090302. All 27 artifacts passed repository byte verification. Both official endpoints now serve the exact embedded catalog and its production signature; isolated clients completed farrow update against each endpoint. This application release builds no new guest images. Linux-host VM lifecycle, host reboot, and a complete Pigsty installation were not replayed for 0.6.0.

Farrow 0.5.0 release — 2026-09-03

Exact commit fc85b65ff6a24b0933b56ae1179be9ada2ba91b1 passed both main-branch workflows before tagging: the complete Go 1.27.1 source gate and the independent GoReleaser snapshot/package path. The exact tag workflow then repeated the source/toolchain checks, built and verified four platform archives, four native Linux packages, eight SPDX documents, the Homebrew formula, installer, release.json, and the 19-entry checksum manifest before creating the 20-asset pre-release.

0.5.0 adds no-confirmation whole-deployment purge/rm, makes the global repo.pigsty.io default and China --mirror explicit, removes hidden Catalog upstream fallback, and adds the digest-pinned eight-target Debian/Rocky official image candidate builder. The builder results remain unsigned testing candidates; no image Catalog or native VM lifecycle result is promoted by this application release.

Farrow 0.4.0 release — 2026-09-02

The exact tag commit passed make check and the release workflow’s archive, DEB/RPM, SBOM, checksum, installer, Homebrew-formula, and package-parity gates. up now runs setup itself on an unprepared terminal host, vm_disks[].fs defaults to auto, readiness failures carry the guest’s last error line, and every command shares one output style. The first-run path was not replayed on a fresh host; no new native VM replay is claimed here.

Farrow 0.3.0 release — 2026-09-02

The exact tag commit passed make check and the release workflow’s archive, DEB/RPM, SBOM, checksum, installer, Homebrew-formula, and package-parity gates. Catalog refresh is now explicit (farrow update for the configured repository, image sync for an exact source), and guest readiness failures carry per-node stages and next-step log commands. No new native VM replay is claimed here.

Farrow 0.2.0 release — 2026-09-01

Source commit 59d1b62aebb3d044a317e4006cc8a0bf56f4feaf is tagged v0.2.0. Its source CI and independently dispatched packaging workflow passed the exact commit. The stable local release path also built and verified all four platform archives, amd64/arm64 DEB and RPM packages, eight SPDX documents, paired helper digests, archive/package parity, Homebrew formula, installer, release metadata, and 19 checksummed final assets.

The macOS arm64/HVF replay ran with MonoProxy’s covering 10.0.0.0/8 exclusion present. Selected u24-1 create/SSH/stop/start, incremental cached el9-1 create, whole status with five absent desired peers, both SSH connections, and whole destroy/SSH-fragment cleanup passed. On Ubuntu 26.04 amd64/KVM, the Linux binary audited an existing four-node Farrow deployment as live and reached its control guest without mutating that host.

The compiled default image repository remains the signed COS-backed https://repo.pigsty.cc/farrow. The independently checked https://repo.pgsty.com/farrow source endpoint serves identical Catalog, authoring metadata, checksums, and image bytes with a read-only Nginx worker.

Schema-3 Catalog closure — 2026-08-29

Catalog revision 2026082903 was the source and development-repository checkpoint on that date: 9 families and 27 architecture-specific artifacts. The embedded Catalog and published catalog.json have the same SHA-256 571b1ff9c7d4d42355df3392ea62a339471c2d01d868669a7625fac8b93f245d; the published repo.yaml also matches the source-controlled authoring file. Fresh HTTP and HTTPS clients accepted the detached signature from production key 4686B39A40F9B562.

All 27 published qcow2 files (19 GiB total) passed a full SHA-256 sweep against the Catalog. A clean temporary Farrow home then downloaded the complete 409.3 MiB Darwin/arm64 default d13:stable artifact, rehashed it, and accepted its qcow2 structure and virtual size. These are publication-integrity and client-path checks, not a replacement for the native lifecycle matrix; no existing VM was recreated for this Catalog check.

0.1.0 candidates — 2026-08-28 and 2026-08-29

Two isolated v0.1.0 candidates passed the stable local release path before 0.2.0 superseded them. Two facts from those runs still stand on their own: the Darwin/arm64 binary repaired two live nodes whose QMP sockets had been removed externally by stopping and starting only those nodes, both reaching readiness in 13.7 seconds while the two untouched peers kept their boot IDs; and a full macOS factory reset exposed a source-test dependency on an installed qemu-img, so catalog-only image list could not run on a blank host. The store is resolved lazily only when local qcow2 bytes need validation, regression tests explicitly remove QEMU from PATH, and make check passes with QEMU, Farrow, and network state absent.

EL7/EL8 compatibility — 2026-08-28

Commit 7c666c7 restored EL7/EL8 after two independent adversarial reviews. The first review blocked on destructive runtime preflight ordering and signed-Catalog baseline migration; both were fixed, regression tested, and the second review returned PASS with no required fixes.

At that checkpoint, Catalog 2026082801 was signed and active on the development repository: 9 families, 17 image artifacts, and 19 SHA-verified repository payloads including the two socket_vmnet archives. A clean client accepted the public signature and exact embedded digest.

An isolated macOS arm64 lifecycle replay booted Rocky Linux 8.10 arm64 with the built-in TCG compatibility rule, passed stop/start and readiness in 44.2 seconds, and verified NetworkManager, fixed IP/no-route/no-DNS, dba UID/GID 88, and the generation/spec marker. EL7 bytes, qcow2 structure, BIOS layout, and 4K XFS root are verified; the native Linux/amd64 Farrow lifecycle replay remains open.

Native replay — 2026-08-27

Both hosts in the summary table passed fixed IP, SSH readiness, default CPU/memory/root/data disk, cloud-init, stop/start, cross-directory commands, unchanged control-node boot ID during scale-out, control-to-peer SSH, ignored unconsumed Pigsty changes, absence-never-destroys, and explicit destroy.

Linux additionally proved valid NOPASSWD automation, caller-accessible Debian helper policy, unprivileged bridge smoke, refusal to uninstall with four tap members, and exact restoration after destroy.

Interactive host-network and hosts commands invoke sudo themselves; an external sudo -v is optional. Darwin cleanup can reconstruct an uninstall-only ownership plan from byte-identical interface evidence, the exact launchd plist, and installed binary digests when network.json is missing.

On 2026-08-28 the post-calibration tree passed unit, race, vet, staticcheck, govulncheck, all four cross-builds, the simulated image-pipeline boundary, license verification, and GoReleaser configuration validation. An isolated local GoReleaser snapshot also built and verified all four archives, both DEB/RPM architectures, SPDX documents, checksums, dependencies, modes, and archive/package parity. Nothing was published, and those results do not extend the native matrix.

3 - Engineering

This page describes the Barn 0.9.0 release candidate. Build commands use your current checkout; record its commit and uncommitted changes. Source builds and local checks do not establish a published release.

Repository boundary

The Barn source repository contains code, tests, build/package definitions, legal notices, README.md, CHANGELOG.md, CONTRIBUTING.md, SECURITY.md, and bilingual application release notes. This site provides user, design, operator, and release documentation. Runtime behavior and command flags must be checked against the matching source and binary; an unpublished source change is not evidence that a public package has the same behavior.

Review transcripts, scratch inventories, generated binaries, and release output trees are not production source inputs.

Generated output is disposable:

• bin/ — development builds;
• dist/ and .goreleaser-* — release/snapshot staging;
• root barn, barn-hosts-helper, and catalogsign binaries;
• Hugo public/ and resources/.

Build and source gates

make check

make check runs module and shell checks, maintenance ownership, unit/race tests, Vet, Staticcheck, dead-code and errcheck checks, vulnerability scanning, four-target cross-builds, installer/image-pipeline tests, and license checks. The Makefile defines the exact list. CI additionally checks the pinned toolchain, Go formatting, whitespace, and GoReleaser configuration. Installation of the quality tools is covered in Build from Source.

Packaging changes have a separate snapshot gate:

make release-check
make release-snapshot SNAPSHOT_DIST=.goreleaser-review

Install the versions in packaging/toolchain.env, including GoReleaser, nFPM, and Syft. The snapshot target also needs the archive/package inspection tools used by the verification scripts. Choose a new output directory directly under the checkout; existing output is refused. A snapshot is local and does not upload a release.

A source gate is not native VM evidence. macOS HVF, Linux KVM/networking, package consumption, release publication, and public website rendering remain separate checks. make image-pipeline-native-test runs the separate native image-pipeline gate with QEMU/libguestfs and explicit image inputs; the required BARN_IMAGE_PIPELINE_NATIVE_* variables are documented in tests/image-pipeline-native-test.sh. It never downloads a test image.

Release and package contract

Release tooling under packaging/, .goreleaser.yaml, and .github/workflows is source, even though its generated directories are not. Archives and Linux packages contain the matching CLI and hosts-helper binaries, LICENSE, the source README, and exact upstream license bytes reconstructed from modules pinned by go.mod. Archives place the two binaries under bin/ and the license texts under licenses/. Linux packages install /usr/bin/barn, /opt/barn/libexec/barn-hosts-helper, and documentation under /usr/share/doc/barn/.

BUILD_INFO.json is included in Linux packages and the older development archive format. Formal GoReleaser archives carry build identity in the binary, with release metadata alongside the published assets; do not assume every archive contains that file. Generated dependency license files are staged at build time. Detailed user documentation stays on this site.

Application releases are built in GitHub Actions, with checksums.txt, release metadata, and SPDX SBOM assets. The current workflow does not produce a separate application-release signature or provenance/attestation bundle. Catalog Minisign signatures authenticate image catalogs and are a separate trust mechanism.

Commit, tag, archive/package verification, CI, draft upload, public release, and anonymous consumption are separate evidence. The tag workflow creates a draft; it does not publish it. Pre-1.0 versions are GitHub prereleases and the installer requires an explicit BARN_VERSION.

make release-local VERSION=<version> builds and verifies without publishing. It requires a clean checkout at the matching v<version> tag, an origin remote, pinned tools, and unused staging/output directories. Use the snapshot path for reviewing an untagged candidate.

Image normalization

The low-level packaging/image-pipeline/build.sh accepts an explicit local qcow2 source and never downloads or uploads. It copies and hashes the source, forces qcow2 parsing, rejects backing/external/encrypted/unknown features, runs qemu-img check, and can perform a no-network offline Guest mutation in an explicit QEMU sandbox. UID/GID 88 collisions are rejected rather than rewritten ambiguously.

build-official.py adds a fixed digest-pinned wrapper for Debian 12/13 and Rocky Linux 8/9 on amd64/arm64. It may fetch only the locked source and offline package inputs, then emits unsigned testing candidates and can assemble a separate candidate repository. Native smoke, repeat-build comparison, production signing, upload, and Catalog activation remain later gates.

Catalog bytes are exported with:

go run ./tools/catalogexport /absolute/new/catalog.json

The exporter is atomic and refuses an existing output path. make catalog-sign and make catalog-verify use the catalog Minisign key pair; production private keys stay outside source and CI. Application checksums do not replace catalog signatures.

Evidence policy

Historical M0–M4 notes were useful during implementation but are not product documentation. Their durable conclusions are condensed into Design and Status. A later source edit inherits no native proof; every status claim names its date, host, path, and remaining gates.