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 an unreleased candidate. Source checks, local builds, packages, CI, releases, and the public site are verified separately. Installation instructions are in the Quick Start.

Documentation baseline

The final release commit, artifact digests, and installation channels will be recorded after publication and download verification.

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 and independent $BARN_HOME/mac state.

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 do not establish complete Mac lifecycle acceptance.

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;
• Mac Developer ID signing and notarization;
• Barn 0.9.0 publication and download verification, including Homebrew.

Linux image Catalog: 2026-09-29

Signed Catalog 2026092902 is published at both official /barn endpoints: nine families and 39 artifacts. The normalized Debian and Rocky Linux images use Barn configuration and metadata throughout.

The six Debian 13 and Rocky Linux images passed UEFI boot, SSH, dual-NIC, UID/GID 88, Python, cloud-init, and XFS data-disk checks. The amd64 images used KVM; Debian 13 and Rocky Linux 9 arm64 used HVF. Rocky Linux 8 arm64 used TCG because its upstream 64 KiB kernel is incompatible with Apple HVF. Rocky Linux 8 uses its shipped RHEL chrony template and chronyd service.

The Debian 12 and Ubuntu images passed native KVM/HVF boot, SSH, dual-NIC, UID/GID 88, locale, and XFS data-disk checks. Debian images include the locked XFS tools and en_US.UTF-8, retaining C.UTF-8 as the default; Ubuntu keeps the original Canonical bytes. These image checks used isolated QEMU user networks; full host networking and VM lifecycle acceptance remains a separate release check.

The embedded and published Catalog bytes match. Both official endpoints pass signature verification, and the new objects pass public download checks. See Images for version selection and update behavior.

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. 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

Design explains the implementation choices; Status records validation. Each status claim names its date, host, path, and remaining checks. Source changes need their own validation.