Farrow

RC6 development candidate: owner-scoped Tier-1 delivery

Tue, 25 Aug 2026 00:00:00 +0800

Caution

Pre-Farrow historical record. It preserves the predecessor candidate’s exact identity and does not establish support for current Farrow bytes or paths. See current status.

Piglet 1.0.0-rc.6 is the owner-scoped local development candidate for the single native-QEMU path. It closes the requested Quick and exact four-node full scenarios on both Tier-1 hosts and adds durable privileged-network transactions. It is deliberately not a public release.

Warning

No Homebrew operation, public tag, remote push, GitHub Release, package repository, production signature, attestation, or support commitment was created. The hashes below identify retained local artifacts; this site does not provide them as downloads.

Development snapshot: the Go 1.27 product surface

Mon, 24 Aug 2026 00:00:00 +0800

Caution

Pre-Farrow historical record. Names, commands, paths, hashes, and claims on this page describe the predecessor snapshot only. Use the current Farrow status and guides for present behavior.

Piglet’s 2026-08-24 source snapshot has moved well beyond an initial QEMU spike. It now presents one coherent local-VM product: zero-configuration Quick, fixed-address private labs, 13 Piglet-owned profiles, an audited Pigsty inventory boundary, explicit persistence/state migration, diagnostics, and a reproducible release toolchain.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Discovery

Configuration lookup order is explicit -f, then farrow.yml, farrow.yaml, pigsty.yml, and pigsty.yaml in the current directory. Every name uses the same Pigsty-compatible YAML Inventory format.

The retired top-level version:/nodes: format is rejected with migration guidance.

For plan, up, reload, and recreate, absence of a file falls back to the applied spec when a deployment exists. validate has no fallback. A configuration must be a regular non-symlink file no larger than 4 MiB.

Design

Mon, 01 Jan 0001 00:00:00 +0000

One useful abstraction

Farrow 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 ~/.farrow 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

Farrow 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 remain untouched. Absence never authorizes deletion.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Supported path today

Build from the current checkout:

cd /path/to/farrow
make build
export PATH="$PWD/bin:$PATH"
farrow version
farrow doctor

There is no published v1 package yet. Do not substitute an unofficial binary for the matching farrow and farrow-hosts-helper build.

The source build requires Go 1.27.x. macOS also needs an existing Homebrew installation; Farrow can install QEMU through Homebrew but never bootstraps Homebrew itself. The current compiled image repository is the development host https://m0/farrow; use FARROW_REPO or --repo when another reachable mirror is required.

CLI

Mon, 01 Jan 0001 00:00:00 +0000

farrow [--json|--yaml] [--verbose] <command> [flags] [node...]

The installed binary is the authoritative reference for its own version. Every visible command includes its operational boundary and copyable examples:

farrow --help
farrow setup --help
farrow image pull --help

In text mode, bare farrow and namespaces such as farrow image display contextual help and exit successfully. In JSON/YAML mode a bare namespace is a structured usage error; explicit --help always renders human help.

Status

Mon, 01 Jan 0001 00:00:00 +0000

Farrow is pre-1.0. Source tests, dated native replays, packages, release, CI, and the public site are separate gates.

Last recorded native replay — 2026-08-27

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

Host	Path	Result
macOS 26.6.2 arm64	HVF, QEMU 11.1, socket_vmnet	one node and additive four nodes passed
Ubuntu 26.04 amd64 (`mx`)	KVM, QEMU 10.2.1, NetworkManager	setup, one node, additive four nodes, and uninstall passed

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

Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

1. Create the lab

mkdir -p ~/lab
cd ~/lab
export FARROW_REPO=https://m0/farrow   # replace outside the development network
farrow setup --dry-run
farrow setup --yes
farrow up

With no existing file, setup writes farrow.yml for one node:

all:
  vars:
    admin_ip: 10.10.10.10
  children:
    nodes:
      hosts:
        10.10.10.10: { nodename: meta }

up downloads and verifies the image, creates the disks and cloud-init seed, starts QEMU, and waits for the guest readiness record.

Engineering

Mon, 01 Jan 0001 00:00:00 +0000

Repository boundary

The Farrow source repository contains code, tests, build/package definitions, legal notices, and a short landing README. This site is the authoritative home for user, design, operator, and release documentation. Raw review transcripts, historical scratch inventories, demo directories, generated binaries, and release output trees are not source inputs and must not be committed.

Generated output is disposable:

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

Build and source gates

make build
make test
make race
make vet
make staticcheck
make vuln
make cross-check
make image-pipeline-test
make license-check

make check combines these gates. A source gate is not native VM evidence; macOS HVF, Linux KVM/networking, package consumption, release publication, and the public render remain separate gates.

Images

Mon, 01 Jan 0001 00:00:00 +0000

Farrow uses a signed static-file Catalog plus immutable qcow2 artifacts. A Catalog update does not require a new Farrow binary, but the binary decides which signing keys and image safety rules are trusted.

Warning

EL7 is deprecated; every other built-in image is currently testing, not supported. The warning printed by up is intentional: a successful pull is an integrity result, not a production-support promise.

Aliases and pull order

The embedded Catalog contains 9 families and 17 artifacts: el7 is amd64-only; el8, el9, el10, d12, d13, u22, u24, and u26 have amd64 and arm64 artifacts. u24 is the VM default.

Operations

Mon, 01 Jan 0001 00:00:00 +0000

Inspect and access

farrow status
farrow ssh meta
farrow exec node-1 -- hostname
farrow logs meta --source serial
farrow ss                         # install SSH aliases; then: ssh meta

Applied state is under ~/.farrow; these commands work from any directory. Status includes the persisted Guest architecture and accelerator, so TCG is never an invisible fallback. plan, up, reload, and recreate prefer -f, then a discovered Inventory, then the applied spec when no file exists. validate always needs a file.

Image Pipeline

Mon, 01 Jan 0001 00:00:00 +0000

packaging/image-pipeline/ accepts one already-downloaded immutable qcow2 and an independently obtained SHA-256. It never downloads, uploads, touches Farrow runtime/network state, reads signing keys, or marks an image supported.

Modes

validate: copy/re-hash, force qcow2 inspection, validate the single backing chain, run qemu-img check, and emit an explicitly unpublishable evidence bundle. Guest credentials are not changed.
offline: additionally use libguestfs virt-customize --no-network and virt-cat on the staged copy. It rejects unrelated UID/GID 88 occupants, normalizes the locked dba/admin identity, disables password/root SSH, removes keys/history/host identity/cloud-init cache, restores targeted SELinux labels, and reads back a deterministic marker.

SOURCE_DATE_EPOCH=1787486400

./packaging/image-pipeline/build.sh \
  --mode validate \
  --source /absolute/source.qcow2 \
  --expected-sha256 <digest> \
  --output /absolute/new/evidence-directory \
  --name u24 --release 20260801.0.0 --arch amd64 \
  --source-user ubuntu --boot uefi \
  --source-uri https://immutable.example/source.qcow2 \
  --artifact-url 'https://images.example/u24/{sha256}.qcow2' \
  --license NOASSERTION \
  --source-date-epoch "$SOURCE_DATE_EPOCH" \
  --manifest-version 2026082801

Source/output paths must be absolute; source is canonical, regular, non-symlinked, stable while copied, and at most 16 GiB. Output must not exist. The builder uses an exclusive adjacent lock, mode-0700 staging, and one final rename. Failure removes only its guarded staging directory.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Start read-only:

farrow doctor --json
farrow network status --json
farrow status --json

No configuration found

For the first deployment, run plan, up, or validate beside farrow.yml/pigsty.yml, or pass -f /path/to/file. Once state exists, plan, up, reload, and recreate can fall back to its applied spec. Status, start, stop, SSH, and destroy always use applied state. If status prints the same message, the selected FARROW_HOME has no applied state.