Barn documentation

• 1: Guides
  • 1.1: Download and Install Barn
  • 1.2: Linux Quick Start
  • 1.3: macOS Virtual Machines
  • 1.4: Daily Operations
  • 1.5: Storage, Files, and Service Access
  • 1.6: Image Repositories
  • 1.7: Automation and Guest Scripts
  • 1.8: Troubleshooting
  • 1.9: Build from Source
  • 1.10: Uninstall and Clean Up
• 2: Reference
  • 2.1: Command Reference
    • 2.1.1: Preparation and Utilities
    • 2.1.2: Linux Lifecycle
    • 2.1.3: Guest Access and Hosts
    • 2.1.4: Image Commands
    • 2.1.5: Repository Commands
    • 2.1.6: Host Network Commands
    • 2.1.7: macOS Commands
  • 2.2: Configuration
  • 2.3: CLI Contracts
  • 2.4: Mac Runtime Reference
  • 2.5: Images
  • 2.6: Image Pipeline
• 3: Project
  • 3.1: Platforms and Limits
  • 3.2: Design
  • 3.3: Security and Trust
  • 3.4: Contributing
  • 3.5: Shipping the Mac Component
  • 3.6: Validation History
  • 3.7: Barn 0.9.3 Changes
  • 3.8: Barn 1.1.0 Local Acceptance

1 - Guides

These guides cover Barn 1.2.0. The Barn 1.2.0 release notes summarize its changes and the upgrade from 1.1.0. You can run both Linux labs and isolated macOS VMs on the same Apple Silicon Mac—each workflow manages its own VMs under ~/.barn.

Get started

• Install Barn — Install the stable CLI on macOS or Linux, check host requirements, and upgrade existing installations.
• Linux Quick Start — Bring up an Ubuntu 24.04 VM, connect over SSH, and scale to a multi-node fixed-IP lab from one barn.yml.
• macOS Virtual Machines — Create and manage macOS 27 guests on Apple Silicon with a native desktop, SSH, shared folders, and clipboard sync.

Day-to-day Linux operations

• Daily Operations — Inspect status, stop and start nodes, preview inventory changes with plan, and recreate or destroy machines.
• Storage and Access — Configure persistent test data disks, transfer files over SSH, forward ports, and mount Virtio-9p host shares.
• Image Repositories — Pick from 9 distribution families, switch to the China mirror, build a static image repository, or import a local qcow2.
• Automation — Run unattended host setup, validate --json output with jq, execute scripts via barn provision, and pair with Pigsty.

Diagnostics, source builds, and cleanup

• Troubleshooting — Runbooks for host readiness, network repairs, guest stage warnings, SSH keys, and interrupted commands.
• Build from Source — Compile the v1.2.0 CLI, barn-hosts-helper, and native Barn.app bundle, and run contributor test gates.
• Uninstall and Clean Up — Tear down Linux and macOS VMs cleanly, prune image caches, remove host networking, and uninstall Barn.

1.1 - Download and Install Barn

Barn 1.2.0 ships archives for macOS and Linux on arm64 and amd64, along with DEB and RPM packages for Linux. Always run barn as your normal Unix user; after installing, continue with the Linux quick start or macOS VM guide.

Install the release

Choose the operating system of your host machine. Use Homebrew on macOS or the release installer script on Linux.

brew install pgsty/infra/barn
barn version

curl -fLO https://github.com/pgsty/barn/releases/latest/download/install.sh
bash install.sh
export PATH="$HOME/.local/bin:$PATH"
barn version

When you run barn up interactively for the first time, Barn checks for missing Linux-guest dependencies and host networking, shows the host-preparation plan, and asks once before installing anything; it requests administrator access (sudo) only when a step needs it. Without a terminal, barn up only reports what is missing, so run barn setup --yes for unattended preparation. To preview the host changes without applying them, run barn setup --dry-run.

System requirements

A default Linux VM uses 1 vCPU and 2 GiB of memory, backed by thin-provisioned qcow2 disks (64 GiB root disk and 128 GiB test data disk) that grow as data is written.

The first macOS VM requires roughly 65 GiB of free disk space to hold Apple’s ~25 GiB restore image, the ~27 GiB installed base image, and initial guest writes. By default, a Mac VM uses 4 vCPUs, 8 GiB of memory, and a 100 GiB APFS clone disk. Later Mac VMs inherit the prepared base image’s capacity unless you pass --disk. See Platforms and limits for guest-specific constraints.

Download Barn 1.2.0

The stable release was published on 2026-11-12. Select the host operating system and CPU architecture:

SHA-256 checksums · Release metadata · Installer script

Each archive and package has a matching .spdx.json dependency inventory on the GitHub Release. The Darwin arm64 archive includes the signed, notarized Barn.app.

Other installation methods

Linux packages

The DEB and RPM packages declare their QEMU, UEFI firmware, and OpenSSH dependencies automatically. On ARM64 hosts, replace amd64 with arm64:

barn_release=https://github.com/pgsty/barn/releases/download/v1.2.0
curl -fLO "$barn_release/barn_1.2.0_linux_amd64.deb"
curl -fLO "$barn_release/checksums.txt"
sha256sum --check --ignore-missing checksums.txt
sudo apt install ./barn_1.2.0_linux_amd64.deb
barn version

barn_release=https://github.com/pgsty/barn/releases/download/v1.2.0
curl -fLO "$barn_release/barn_1.2.0_linux_amd64.rpm"
curl -fLO "$barn_release/checksums.txt"
sha256sum --check --ignore-missing checksums.txt
sudo dnf install ./barn_1.2.0_linux_amd64.rpm
barn version

Manual archives

Download barn_1.2.0_<os>_<arch>.tar.gz (darwin or linux, arm64 or amd64) and checksums.txt from Barn 1.2.0 on GitHub, then verify the SHA-256 digest before extracting:

barn_release=https://github.com/pgsty/barn/releases/download/v1.2.0
curl -fLO "$barn_release/barn_1.2.0_darwin_arm64.tar.gz"
curl -fLO "$barn_release/checksums.txt"
shasum -a 256 -c checksums.txt --ignore-missing

Extract the archive and add its bin/ directory to PATH. Keep the packaged layout intact: barn and barn-hosts-helper must stay paired, and the Darwin arm64 archive also contains bin/Barn.app. The CLI verifies the helper’s embedded SHA-256 before invoking it and discovers the app beside the binary.

Build from source

To work on Barn or compile the native Barn.app bundle for macOS guests, see Build from Source.

Upgrade Barn

Upgrading from 1.1.0 to 1.2.0 preserves VM disks, SSH keys, state, and configuration under ~/.barn. Stop running Mac VMs before replacing the CLI, helper, and Barn.app together. Linux inventories that omit CPU/memory now resolve to 1 vCPU / 2 GiB; explicitly set vm_cpu: 2 and vm_mem: 4GiB to preserve the old defaults and inspect barn plan. Existing applied VMs keep their resources until a resource-changing operation is requested. See the 1.2.0 release notes.

Upgrade using the same channel you used to install Barn. On macOS with Homebrew:

brew update
brew upgrade pgsty/infra/barn
command -v barn
barn version

On Linux, re-run install.sh (it selects the latest stable release unless BARN_VERSION is set) or install the newer .deb / .rpm package, then run command -v barn and barn version to confirm the active binary. If both a user-directory install and a system package/Homebrew install exist, update the copy selected by PATH, or adjust PATH and verify the version again.

Barn decouples CLI upgrades from guest image updates so existing VMs never change OS versions unexpectedly:

For proxy or PATH issues, see Troubleshooting. To remove Barn and its host state, see Uninstall and Clean Up.

1.2 - Linux Quick Start

Create an Ubuntu 24.04 VM on your Mac or Linux host, connect over SSH, and scale it into a multi-node fixed-IP lab from a single YAML inventory. For macOS guests on Apple Silicon, see the macOS VM guide.

This walkthrough uses Barn 1.2.0, with 1 vCPU and 2 GiB per node by default. Set resource fields explicitly to customize the lab; see configuration defaults.

Before you start

Install Barn and make sure your host has at least 2 GiB of free memory for the guest. Run the commands below as your normal user in an interactive terminal: Barn asks once before it changes the host and prompts for sudo only for the steps that need it. For unattended CI runs, see Automation. In mainland China, add --mirror to the first barn up to download images from the China repository at repo.pigsty.cc.

Customize before the first start

The default lab is one Ubuntu node using the host architecture: arm64 on Apple Silicon, amd64 on Intel/AMD. No architecture setting is needed for normal use; see image and architecture settings for cross-architecture selection and precedence. To keep the defaults, skip to Start and connect. To choose the topology, subnet, or OS image first, write and edit the inventory before the first barn up:

1. Generate a starter barn.yml (dual, trio, or full creates 2, 3, or 4 nodes; -c 10.20.30.0/24 selects a custom subnet, -I el9 writes one image for every node, and -A amd64 sets vm_arch):

   mkdir -p ~/barn-lab && cd ~/barn-lab
   barn init

2. Edit barn.yml to choose your image and resources:

   barn.yml

   all:
     vars:
       admin_ip: 10.10.10.10
       vm_image: u24
       vm_cpu: 1
       vm_mem: 2GiB
     children:
       nodes:
         hosts:
           10.10.10.10: { nodename: meta }

3. Validate the YAML and preview the plan:

   barn validate
   barn plan

barn validate and barn plan resolve catalog metadata without requiring QEMU or host-network setup, and the next section’s barn up uses this barn.yml. See Linux Configuration for all inventory variables.

Start and connect

mkdir -p ~/barn-lab && cd ~/barn-lab
barn up

When neither an inventory file nor an active deployment exists, barn up prints a short setup plan before it changes anything. Only the rows that apply appear: dependencies lists missing packages (QEMU, UEFI firmware, OpenSSH) and the package manager, network names the fixed-IP subnet it prepares, config names the one-node barn.yml it writes, and sudo says which steps need root. On a host that already has QEMU:

ITEM     STATE    MESSAGE
network  planned  prepare 10.10.10.0/24
config   planned  create /home/alice/barn-lab/barn.yml
sudo: network (root-owned barn0 bridge)
Continue with this setup? [Y/n]

Answer once; sudo may then ask for your password. Barn downloads and verifies the base image, updates the live progress table on a terminal, and waits until SSH is ready:

NAME  ADDRESS      STATE  MESSAGE
meta  10.10.10.10  ready  SSH ready: barn ssh meta
boot 1/1 nodes: 39s [DONE]

If barn up stops with an error instead, run barn doctor to check the host and barn logs meta to read the guest console, fix the reported problem, and run barn up again. See Troubleshooting for common failures.

Log in to the guest:

barn ssh

barn ssh logs you in as dba with key-based SSH and passwordless sudo. barn up also installs SSH aliases, so plain ssh meta works too. Type exit to return to your host shell; the remaining commands run on the host.

Both disks are thin-provisioned qcow2 files that grow as data is written. If 10.10.10.0/24 conflicts with an existing route on your machine, first-run setup automatically picks a free private /24 for a fresh default template—check the generated barn.yml and barn status for the assigned IP.

Inspect and use the VM

barn status

NAME  ADDRESS      STATE    IMAGE             SPEC  ROOT
meta  10.10.10.10  running  u24@20261017.0.1  1c2g  64 GiB

barn status reports each node’s fixed address, recorded state, image release, and size. Run guest commands from the host by putting -- before the remote command:

barn exec meta -- hostname
barn exec meta -- df -h / /data

barn up verifies management SSH and reports guest-stage warnings such as an unavailable data disk or private interface. If setup is interrupted or you fix a host issue, run barn up again—healthy VMs stay running while Barn finishes the remaining steps.

Scale to a multi-node lab

To grow the lab to four nodes (8 GiB of guest memory at the default 2 GiB per node), add three host entries under all.children.nodes.hosts in your existing barn.yml. Use addresses from the same /24 as meta; if first-run setup chose another subnet, use that one:

all:
  vars:
    admin_ip: 10.10.10.10
  children:
    nodes:
      hosts:
        10.10.10.10: { nodename: meta }
        10.10.10.11: { nodename: node-1 }   # new
        10.10.10.12: { nodename: node-2 }   # new
        10.10.10.13: { nodename: node-3 }   # new

Preview the change and converge the new nodes:

barn plan
barn up

barn plan reports create: node-1, node-2, node-3, and barn up creates them without restarting meta.

If you change an existing node’s CPU or memory, apply the change with barn resize <node>; it preserves the VM identity and disks. Image changes still use barn recreate <node>, which replaces its root disk. Removing a host entry from barn.yml leaves the VM untouched on disk until you run barn destroy <node>.

Stop, resume, and clean up

barn stop
barn start

Both stop and start preserve all VM disks. When you finish with the lab, run barn destroy and type destroy to confirm. Barn deletes the VMs with their root overlays and non-persistent data disks, removes the deployment state and the SSH aliases it installed, and keeps persistent data disks, the deployment keys, cached base images, and the host network. Running barn up in ~/barn-lab again builds a fresh lab from barn.yml. For a full teardown, see Uninstall and Clean Up.

Next steps

• Daily Operations — Inspect logs, restart nodes, apply inventory changes, and destroy VMs.
• Storage and Access — Configure persistent disks, copy files with OpenSSH, and reach guest ports.
• Image Repositories — Select Debian, Rocky Linux, Ubuntu, or local qcow2 images.
• Automation — Run unattended setup --yes, parse --json output, run guest scripts, or pair pigsty.yml with Pigsty.

1.3 - macOS Virtual Machines

barn mac provisions disposable macOS VMs on Apple Silicon Macs for building, testing, and reproducing macOS-specific issues. Each VM comes with an administrator account, passwordless sudo, pinned SSH keys, and a dedicated private IP, running directly under your user account via Apple’s Virtualization framework without sudo.

Mac VMs are managed independently from the Linux lab: they do not read barn.yml, they store their state under $BARN_HOME/mac (default ~/.barn/mac), and Linux barn destroy or barn purge commands never touch them.

Requirements

• An Apple Silicon Mac running macOS 27 or later with an active logged-in desktop session (guests also run macOS 27).
• Roughly 65 GiB of free disk space for the first VM—covering Apple’s ~25 GiB restore image (.ipsw), the ~27 GiB installed base image, and initial guest writes. Each VM clones the base image on APFS and grows up to its configured capacity (100 GiB by default).
• The native Barn.app bundle paired with the CLI from the same release, included in the Apple Silicon release and Homebrew installation.
• No sudo privileges required.

Apple’s Virtualization framework allows at most two running macOS VMs at a time per Mac across all virtualization tools (including an active macOS base-image installation). You can keep additional stopped VMs on disk and start any two at once, subject to the Apple software license.

Install

Install the prebuilt release with Homebrew:

brew install pgsty/infra/barn
barn version
barn mac doctor

Homebrew installs the signed, notarized Barn.app and matching CLI/helper together. No Go or Xcode installation is needed. The download installer and manual archive also include the app on Apple Silicon. Stop running Mac VMs before upgrading or replacing the app.

To develop Barn itself, see Build the Mac component.

Create your first machine

barn mac up

When no macOS base image exists yet, barn mac up displays the download and disk requirements before asking for confirmation:

info: macOS 27.0 (26A428) is not prepared on this Mac yet.
download:  24.8 GiB from Apple (updates.cdn-apple.com)
then:      install macOS once into a reusable base (about 20 minutes)
free:      551.2 GiB
Download macOS from Apple now? [Y/n]

Once you confirm, Barn completes three steps:

1. Downloads the restore image from Apple (updates.cdn-apple.com), resuming any partial transfer and verifying Apple’s published SHA-256 digest.
2. Installs macOS once into an unbooted base image, temporarily using one of the two macOS VM slots during installation.
3. Clones mac1 from the base image using APFS copy-on-write, boots the guest, configures your user account, and waits until SSH and passwordless sudo are ready.

NAME  ADDRESS      STATE    MESSAGE
mac1  10.10.20.10  running  created and ready; macOS 27.0 (26A428), user alice
ready: barn mac ssh mac1
desktop: barn mac open mac1

Subsequent VMs clone the prepared base image in seconds without repeating the IPSW restore. Barn pins initial setup to macOS 27.0 (26A428); use barn mac image update when you want to adopt a newer macOS 27 build.

If you already have a local copy of Apple’s restore image, pass --ipsw to skip the download (Barn clones it without copying if it resides on the same APFS volume):

barn mac up --ipsw ~/Downloads/UniversalMac_27.0_26A428_Restore.ipsw

In non-interactive scripts, pass --yes to authorize the 25 GiB download, or run barn mac setup ahead of time to prepare the base image without creating a VM. If you start a new VM with --no-wait (which returns as soon as the VM process starts), run barn mac up NAME without --no-wait to finish SSH and sudo provisioning before calling ssh or exec.

Work in the machine

Shell and commands

barn mac ssh                                  # interactive shell
barn mac exec -- sw_vers                      # single program execution
barn mac ssh -- 'id; sudo -n true && echo sudo works'

ProductName:		macOS
ProductVersion:		27.0
BuildVersion:		26A428

By default, the guest administrator account matches your host macOS username (override with --user at creation time). Place -- before the remote command: ssh passes a command string to the guest shell, while exec passes the program and arguments directly (use sh -c for shell pipelines or redirection; see the SSH/exec contract). Both return the remote command’s exit status, and --json captures stdout, stderr, and exit_code:

barn --json mac exec -- sh -c 'echo out; exit 3'

{
  "command": "exec",
  "node": "mac1",
  "host": "10.10.20.10",
  "arguments": ["sh", "-c", "echo out; exit 3"],
  "success": false,
  "exit_code": 3,
  "stdout": "out\n"
}

See the Mac command reference for the complete JSON schema.

Desktop

barn mac open

barn mac open launches a native window that resizes the guest display dynamically (use View → Enter Full Screen for full-screen mode). Closing the window leaves the VM running in the background; run barn mac open again to reopen it, or to boot a stopped VM and open its display.

While the guest window has focus, keyboard shortcuts are sent to the guest OS, so use the macOS menu bar for host actions:

When you log out of or shut down the host Mac, Barn requests a clean guest shutdown and powers off the VM if it does not stop before the timeout.

Each VM also generates a random password for the macOS lock screen and GUI administrator prompts. Copy it directly to your host clipboard without printing it to the terminal:

barn mac password --copy

Clipboard

Clipboard sharing syncs plain text across focus changes over the VM’s SSH channel without installing extra guest agents: focusing the guest window syncs text copied on the host Mac, and switching back to a host app syncs text copied inside the guest. Concealed items from password managers, images, and files are never transferred.

To disable clipboard sharing persistently for a VM, run barn mac configure mac1 --clipboard off (applied on the next start).

Shared folders

Pass one or more --share flags when creating a VM to mount host directories inside the guest under /Volumes/My Shared Files/<name>:

barn mac up dev --cpu 8 --memory 16G --share ~/src --share docs=~/Documents:ro
barn mac exec dev -- ls "/Volumes/My Shared Files"

The share name defaults to the directory’s basename, and appending :ro mounts it read-only. Each shared path must resolve to an existing directory (symlinks are supported); Barn never creates or deletes shared host directories. To add or remove shares on an existing VM, stop it first and run barn mac configure:

barn mac stop dev
barn mac configure dev --share data=/Volumes/Work/data --unshare docs
barn mac start dev

Because VirtioFS on macOS guests can briefly cache file contents after host-side edits, use scp or rsync to copy files onto the guest disk when a build requires immediate byte-level consistency.

SSH from other tools

When the first Mac VM becomes ready, Barn adds a marked Include line to ~/.ssh/config so ssh mac1, scp, rsync, and IDE Remote-SSH extensions work out of the box using each VM’s dedicated key and pinned host key:

ssh mac1 'uptime'
rsync -a ./project/ mac1:project/
barn mac ssh-config              # print the generated SSH config entries
barn mac ssh-config --remove     # remove Barn's Include and disable auto-install

If ~/.ssh/config is a symlink managed by a dotfile tool, Barn leaves the file untouched and prints the Include line for you to add. Re-enable automatic integration after --remove with barn mac ssh-config --install. If your personal ~/.ssh/config already defines a Host alias with the same name as a VM, Barn preserves your alias and writes its managed entry by IP address only.

Multiple machines

Assign each VM a lowercase alphanumeric name (starting with a letter, with optional internal hyphens). Creation flags (--cpu, --memory, --disk, --user, --share) apply only when creating a new VM:

barn mac up dev --cpu 8 --memory 16G
barn mac ls

NAME  ADDRESS      STATE    SSH    USER   OS          CPU  MEMORY  DISK                 SHARED
dev   10.10.21.10  running  ready  alice  macOS 27.0  8    16 GiB  504.0 MiB / 100 GiB  src,data
mac1  10.10.20.10  running  ready  alice  macOS 27.0  4    8 GiB   4.7 GiB / 100 GiB
limit: 2 of 2 macOS VMs are running; stop one before starting another

When you omit the VM name, commands target the sole existing VM or mac1 (and ask you to disambiguate when multiple VMs exist). If you request a --disk size that differs from the prepared base image’s capacity, Barn installs a new base image at that capacity from the restore image first.

Each VM gets its own /24 private subnet starting at 10.10.20.0/24 (guest IP .10), automatically skipping subnets that overlap with your LAN, VPNs, the Linux lab, or other Mac VMs. If two Mac VMs are already running, starting a third fails immediately and suggests a VM to stop:

barn mac up build --user ci

error: dev and mac1 are running; macOS allows 2 macOS virtual machines at a time
next: barn mac stop mac1

Everyday lifecycle

barn mac stop dev               # clean guest shutdown (powers off after 2m timeout)
barn mac start dev              # boot and wait for SSH
barn mac restart dev            # stop then start, applying pending configure changes
barn mac stop --all             # stop all running Mac VMs

Use barn mac stop --force for an immediate power-off, or barn mac start --recovery to boot into macOS Recovery with the desktop window open.

barn mac up never mutates an existing VM’s specification—passing changed creation flags on an existing VM returns a hint pointing to barn mac configure:

error: dev already exists, so --cpu would not apply; its configuration and data were preserved
next: barn mac configure dev --cpu 4

Stop the VM before changing CPUs, memory, shared folders, or subnet with configure (clipboard settings can be toggled while running):

barn mac stop dev
barn mac configure dev --cpu 6 --memory 12G --subnet auto
barn mac start dev

To reset a VM’s disk to a clean clone of the base image while preserving its name, account, hardware settings, shares, and IP, run barn mac recreate. To delete the VM completely, run barn mac destroy. Both commands ask for typed confirmation on a terminal; pass --yes in non-interactive scripts:

barn mac recreate dev
barn mac destroy dev

macOS versions and disk space

barn mac image ls

KIND  OS          BUILD   STATE  ON DISK   CAPACITY  USED BY
base  macOS 27.0  26A428  ready  26.7 GiB  100 GiB   mac1,default

Run barn mac image update to query Apple for the newest supported macOS 27 build, download its IPSW, and prepare a new default base image for future VMs. Existing VMs stay on their current build until you run barn mac recreate NAME --update (if a VM uses a custom disk size such as 200G, prepare the matching base image first with barn mac setup --disk 200G).

Use barn mac image prune to inspect unused non-default base images, adding --installers to include downloaded .ipsw files and --yes to delete them:

barn mac image prune --installers         # preview reclaimable images
barn mac image prune --installers --yes   # delete them

Because APFS clones share physical storage blocks with the base image, ON DISK and per-VM disk figures overlap and do not sum linearly.

Troubleshooting

Run barn mac doctor to check host compatibility, the native Barn.app bundle, base images, and every VM, and use barn mac logs [name] to inspect startup, network, and Virtualization framework logs.

Apple Account sign-in inside macOS guests is not reliably supported by Apple’s Virtualization framework, and USB passthrough, snapshots, and VM suspend/resume are not supported.

Clean up

barn mac ls                                 # list existing Mac VMs
barn mac destroy mac1 dev                   # delete selected VMs
barn mac image prune --installers --yes     # delete cached IPSWs and unused base images

Destroying the last Mac VM automatically cleans up its ~/.ssh/config entries while keeping the default base image. For a complete removal of all Mac VM state:

1. Destroy all Mac VMs (barn mac destroy ...) and run barn mac ssh-config --remove.
2. Delete $BARN_HOME/mac (default ~/.barn/mac).
3. Optionally remove ~/Library/Preferences/com.pgsty.barn.plist (io.pgsty.barn.mac-runner.plist in 0.9.0), which stores desktop window geometry.

1.4 - Daily Operations

This guide covers day-to-day Linux lab management. For macOS guests, see the macOS VM guide.

Inspect and access

barn status
barn ssh meta
barn exec node-1 -- hostname
barn logs meta --source serial

These commands read the active deployment under BARN_HOME (default ~/.barn) and work from any directory when that path points to the same location. If you set BARN_HOME yourself, use an absolute path across working directories. barn status lists each node’s image and resource allocation (including any software-emulated tcg notice), while barn status --verbose adds guest architecture, accelerator, loopback SSH port, and QEMU PID.

When you run barn up (including on a subset of nodes), Barn refreshes the ~/.ssh/barn_config aliases for the entire applied deployment so ssh meta and peer aliases stay current. You can also regenerate those aliases at any time with barn ssh-config --install.

Commands that reconcile configuration—plan, up, reload, resize, and recreate—locate the inventory in this order:

1. An explicit -f /path/to/inventory.yml flag (required when both barn.yml and pigsty.yml exist in the same directory and you want pigsty.yml).
2. The first matching file in the current working directory (barn.yml, barn.yaml, pigsty.yml, then pigsty.yaml; parent directories are never searched).
3. The previously applied deployment specification in BARN_HOME (except barn validate, which always requires a file).

Re-running barn up retries any unfinished guest setup stages and updates guest helper scripts in place without restarting healthy VMs. Any remaining guest limitations or automatic test-disk repairs are surfaced in the terminal summary and under nodes[].warnings / nodes[].repairs in JSON/YAML output (see Data disks).

Stop and start

barn stop
barn start
barn restart node-1
barn reload -f barn.yml       # validate inventory, stop selected nodes, and run up

barn start boots stopped VMs, re-verifies running ones, and updates SSH aliases if any automatic loopback port was reassigned. barn reload validates the inventory and startup dependencies before stopping selected nodes, then runs barn up for that selection.

reload is a controlled stop-and-boot cycle. It can add new nodes and start stopped nodes, but it refuses existing-node changes to CPU, memory, image, disks, shares, addresses, or other VM definitions before stopping anything.

For CPU or memory changes, edit vm_cpu or vm_mem and run barn resize. Supported increases can use hotplug; decreases and unsupported backends use a stop/start fallback while preserving VM identity and disks. Barn 1.2.0 also supports in-place root growth with resize -D. Image, data-disk, network, and share changes require recreate.

If online resize is interrupted after hotplugging, barn status reports that live CPU and memory may differ from the applied configuration (reason: resize_incomplete). Run barn resize NODE again, or run barn restart NODE to return to the committed resources. Offline resize holds the deployment lock while stopping and updating the node.

Passing --no-wait to a start command returns as soon as QEMU starts, skipping readiness checks, guest recovery, and /etc/hosts or control-node SSH updates until your next barn up.

Change the deployment

barn plan
barn up                         # create/start selected nodes and refresh SSH aliases
barn resize node-1              # apply vm_cpu/vm_mem changes without recreation
barn recreate node-1            # rebuild a node whose VM specification changed

barn plan compares your inventory against the applied state and reports image selections, aggregate resources, drift reasons, and disk impact:

In JSON output, start, create, resize, recreate, and missing are node lists. The top-level action summarizes the plan as one of create, start, converge, resize, recreate, blocked-removal, repair, or none; blocked, when present, is an explanation string. whole_deployment: true marks a deployment-wide recreation; follow the suggested command so that new nodes are included alongside existing ones.

Editing or deleting YAML entries never destroys a VM automatically, and changes to service-level Pigsty variables that Barn does not consume report action: none. Interactive recreate and destroy prompt you to type the command name to confirm; pass --yes (or --force) in non-interactive scripts.

recreate is the explicit replacement path. Barn validates the new image, network, shares, and persistent-disk attachment contract first, then destroys the selected VM artifacts and boots a fresh VM from the desired inventory. Root and non-persistent data disks are replaced; compatible persistent disks remain attached. The replacement gets a new VM identity and refreshes SSH host-key state.

Without node names, recreate replaces every node in the deployment and lists them in the confirmation. It refuses an inventory that no longer lists an existing node before any VM stops (exit 4, reason: nodes_removed): remove that node explicitly with barn destroy <node> or add it back to the inventory. Barn checks the scope again under the destruction lock and reports deployment_changed if the applied state changed during preflight.

Apply changes to selected nodes

You can edit several nodes in the inventory and apply them in batches:

barn plan node-1 -f barn.yml
barn recreate node-1 -f barn.yml
barn plan node-2 -f barn.yml

plan, up, reload, recreate, and resize with explicit selectors retain every unselected peer’s applied definition, including peers changed or temporarily omitted in YAML. Images for uncreated, unselected nodes are resolved when you select those nodes. The entire inventory must still parse correctly, and selected changes must not conflict with applied addresses, aliases, control-node roles, or deployment-wide settings.

Without selectors, Barn evaluates the whole inventory: CPU and memory changes use resize, other changed existing VMs require recreate, and missing VMs require restoring their definitions or explicitly destroying them.

Concurrent commands

For parallel node work within one command, Barn 1.2.0 adds --parallel/-p with a CPU-based default; see Lifecycle concurrency for the supported commands and the difference from Barn 1.1.0.

Mutating commands (up, start, stop, restart, reload, resize, recreate, destroy, purge, and provision) acquire the deployment lock in BARN_HOME, waiting up to 10 minutes (provision --timeout can impose a shorter deadline) if another operation is in flight. While waiting, Barn prints the lock holder’s command, PID, and start time; if the wait times out, it exits with code 4 (error: conflict, reason: deployment_busy). The lock releases automatically when the holding process exits—never delete lock files manually.

Read-only and access commands (status, ssh, exec, ssh-config, and the state read in hosts) read the last published state without waiting on the lock. If a mutating command is currently running, barn status includes a note indicating the active operation. See Troubleshooting for interrupted runs.

Destroy

Pick the teardown command that matches the scope you want to remove:

barn destroy node-3

barn destroy

barn destroy --delete-persistent

barn purge

• barn destroy <node> deletes only the named node and refreshes SSH aliases for the remaining nodes. If it removes the control node, the first remaining node becomes the control node, so ssh-config, hosts, exec, and provision keep working; set admin_ip in the inventory to that node’s address (and remove the destroyed entry unless you want up to create it again), then run barn up to install its control SSH access.
• barn destroy removes all VMs along with their root overlays and non-persistent data disks, the deployment state, and the SSH aliases Barn installed, while retaining persistent disks, deployment keys, cached images, and host networking. Run barn up again to build a fresh lab from the inventory.
• barn destroy --delete-persistent and barn destroy --purge apply to the entire deployment (they cannot be combined with node names). --purge also removes persistent disks, SSH keys, and deployment state.
• barn purge immediately removes the entire Linux lab, verified retained persistent disks, keys, and deployment state; the image cache and host network remain. To review the node list and deletion scope first, use barn purge --ask: y/yes confirms; n/no, an empty line, or EOF cancels. It accepts no --yes, -y, or --force.

To remove the shared Linux host network after all VMs are gone:

barn network uninstall --yes

See Image Repositories for image cache management, or Uninstall and Clean Up for a full host teardown.

1.5 - Storage, Files, and Service Access

This guide covers disk configuration, file transfer, and service access for Linux labs. It builds on the Linux Quick Start using node meta at 10.10.10.10.

Configure disks before creating the VM

By default, every Linux node gets a 64 GiB root overlay disk and one 128 GiB non-persistent data disk mounted at /data. vm_disk sets the root disk capacity in GiB (as an integer like 64 or with a unit like 64GiB), while vm_disks replaces the default data-disk list (vm_disks: [] disables extra data disks).

For a new single-node lab, save the following inventory as storage.yml:

all:
  vars:
    admin_ip: 10.10.10.10
    vm_image: u24@20261017.0.1
  children:
    nodes:
      hosts:
        10.10.10.10:
          nodename: meta
          vm_cpu: 2
          vm_mem: 4096
          vm_disk: 64
          vm_disks:
            - {path: /data, size: 64, fs: auto, persistent: true}
            - {path: /scratch, size: 32, fs: ext4, persistent: false}

If meta already exists with a different disk layout, barn up reports drift; inspect barn plan and back up any needed files before running barn recreate meta (which replaces root and non-persistent disks).

Validate the inventory, provision the VM, and verify the mounted filesystems:

barn validate -f storage.yml
barn plan -f storage.yml
barn up -f storage.yml
barn exec meta -- findmnt /data
barn exec meta -- findmnt /scratch
barn exec meta -- df -h / /data /scratch

Disk sizes (size: 64 or size: 64GiB) are thin-provisioned virtual capacities that consume host space as data is written. With fs: auto, Barn formats new disks as XFS when mkfs.xfs is available in the guest and falls back to ext4 otherwise. Check barn up warnings and findmnt to confirm that every data disk mounted cleanly.

What survives each operation

Barn matches retained persistent disks by disk identity and specification: to reattach a retained disk across recreate or after destroy, keep the node name, mount path, size, and fs type identical. Barn rejects mismatched retained disks rather than attempting in-place resizing, renaming, or filesystem conversion.

Newly formatted data filesystems are owned by root. You can verify that data written to /data persists across a stop and start cycle:

barn exec meta -- sudo -n sh -c \
  'printf "retention check\n" > /data/barn-retention.txt'
barn stop meta
barn start meta
barn exec meta -- cat /data/barn-retention.txt

For macOS guest folder sharing, see the macOS VM guide.

Copy files over managed SSH

Export a standalone OpenSSH configuration from the running deployment to use ssh, scp, or rsync directly:

barn ssh-config > barn-ssh.conf
ssh -F ./barn-ssh.conf meta hostname
scp -F ./barn-ssh.conf ./storage.yml meta:/tmp/storage.yml
scp -F ./barn-ssh.conf meta:/data/barn-retention.txt ./barn-retention.txt

The exported fragment points to the current loopback SSH port, deployment key path, and instance-scoped known_hosts file without embedding private key material. Regenerate barn-ssh.conf if you recreate a node or its loopback port changes, or run barn ssh-config --install so ssh meta and scp work without -F.

Reach services inside the guest

When a service inside the guest listens on the node’s fixed private IP (for example, PostgreSQL on 10.10.10.10:5432) and the guest firewall permits it, your host and peer nodes can connect to that IP directly.

If a service binds only to 127.0.0.1 inside the guest, forward a local host port over SSH:

ssh -F ./barn-ssh.conf -N \
  -L 127.0.0.1:15432:127.0.0.1:5432 meta

While that command remains running, connect local clients on the host to 127.0.0.1:15432 (press Ctrl-C to close the tunnel).

SSH aliases (ssh meta) apply only to OpenSSH tools. If you also want browsers, psql, or other host applications to resolve node names and vm_alias entries via /etc/hosts, preview and apply the optional hosts integration:

barn hosts install --json
barn hosts install --yes

barn hosts install --yes updates /etc/hosts on the local host (requesting sudo when needed); re-run it after adding nodes or changing IPs.

Barn inventories do not use vm_ports or vm_forwards—connect via the fixed-IP network or OpenSSH port forwarding. Because management SSH runs over an independent loopback port, barn ssh and -L tunnels remain usable even if the fixed-IP bridge reports a limitation.

Host directory sharing

Linux and macOS hosts can share directories with Linux guests through QEMU Virtio-9p. Set vm_shares under all.vars or a host entry before the first barn up:

vm_shares:
  - host: ./src
    guest: /workspace
    readonly: true

host accepts paths relative to the inventory’s real file, ~/, and directory symlinks. The directory must exist, be accessible, and not overlap BARN_HOME; it need not belong to the Barn user. Multiple guests may write the same tree, with writes coordinated by the user.

Host QEMU and the guest kernel must support 9p. Writable shares also depend on guest permissions; failed writable mounts fall back to read-only with a warning without changing host ownership. After changing existing shares, run barn recreate <node>. Native macOS guests use VirtioFS through barn mac up --share or barn mac configure --share.

See Linux Configuration for the complete disk and share schema.

1.6 - Image Repositories

This guide covers Linux guest image selection, mirrors, static repositories, and cache management.

With the default inventory, barn up automatically resolves u24:stable for your host architecture and downloads the matching verified qcow2 image on demand. Barn starts with the signed image catalog embedded in the binary (revision 2026110502, 17 artifacts across 9 distribution families); run barn update whenever you want to fetch, verify, and activate the latest catalog from the repository (or barn image sync to load an exact catalog URL or local file).

Choose an image

Inspect the available distribution families and channels:

barn image list
barn image info u24
barn image info u24:stable

Barn provides nine built-in distribution families: el7, el8, el9, el10, d12, d13, u22, u24, and u26. A bare family name such as el9 selects the stable channel, name:channel selects an explicit channel, and name@version pins an exact immutable build. You can also set a numeric prefix in vm_version to pick the newest matching release along dot boundaries:

all:
  vars:
    vm_image: el9
    vm_version: "9.8"

Here "9.8" selects the newest 9.8.x build in the active catalog, while "9" selects the newest 9.x build (quote numeric vm_version values in YAML so they remain strings). Do not combine vm_version with a :channel or @version suffix in vm_image.

For strict reproducibility across catalog updates, pin the full version string reported by barn image info:

all:
  vars:
    vm_image: d13@20261103.2651.1

After changing vm_image or vm_version, preview the change with barn plan. Existing nodes keep their current root disk until you run barn recreate <node>; updating the catalog with barn update only affects newly created or recreated nodes.

Temporary overrides and architecture

Use -I (--image) and -A (--arch) to override image and architecture settings for one command invocation.

Guests default to the host architecture unless explicitly overridden by vm_arch or --arch/-A. Precedence is -A → vm_arch → host architecture. -A native overrides a fixed inventory architecture and follows the host again. amd64 accepts x86_64 and x64 aliases; arm64 accepts aarch64 and a64.

barn plan -I u24 -A amd64
barn up -I u24 -A amd64

-I u24 replaces selected nodes’ vm_image and vm_version without changing the architecture. These overrides leave the inventory intact. To keep them, set vm_image and all.vars.vm_arch, removing superseded vm_version, or generate a new inventory with barn init -I u24 -A amd64. Existing nodes still require recreate to change image or architecture; architecture changes must include all existing nodes. See the configuration reference.

barn image list displays all architectures. Standalone info and pull default to the host architecture without reading inventory vm_arch; use --arch/-A to override it (legacy -a also works). A missing architecture variant is an error, not a reason to select another architecture. Barn currently accepts only amd64 and arm64 guests:

• el7 is supported only on native linux/amd64 hosts.
• el8 on arm64 automatically runs under QEMU TCG software emulation on Apple Silicon because the stock RHEL/Rocky 8 arm64 kernel requires a 64 KiB page granule that macOS HVF does not support. See Runtime rules for foreign-architecture emulator requirements.

Use a mirror

Release builds default to https://repo.pigsty.io/barn. Pass --mirror to use the China mirror (https://repo.pigsty.cc/barn), or --repo to point at a custom repository URL or local directory:

barn image pull u24 --mirror
barn up --mirror
barn update --repo https://mirror.example/barn
barn image pull u24 --repo https://mirror.example/barn
barn up --repo https://mirror.example/barn

To set a default repository for your current shell session, export BARN_REPO:

export BARN_REPO=https://mirror.example/barn
barn update
barn up

Repository selection follows the precedence --repo → --mirror → BARN_REPO → global default (https://repo.pigsty.io/barn). Both official repositories and any plain http:// repository require a valid Minisign signature (catalog.json.minisig); explicit local directory paths and custom https:// endpoints may use an unsigned catalog.json. Every image download is verified against the catalog’s byte size, SHA-256 digest, and qemu-img structural checks.

When downloading from either official repository, Barn automatically retries transient network errors, resumes partial transfers, and falls back to the peer official mirror if an artifact is unreachable. Custom --repo endpoints never fall back to external servers.

Each repository root maintains its own active catalog state under BARN_HOME. When you point --repo at a custom repository that defines new image entries, run barn update --repo <root> first to activate its catalog before running plan or up.

Build a static repository

A Barn image repository is a plain directory that you can serve over static HTTP/HTTPS, copy with rsync, or read directly from a local path:

repo.yaml is the sole human-edited file. For the single arm64 image above, create /srv/barn/repo.yaml:

schema: 1
revision: 1
defaults: { image: d13, channel: stable, arch: native, boot: uefi }
images:
  d13:
    channels: { stable: "1" }
    versions:
      "1":
        status: testing
        variants:
          arm64:
            source_user: debian

Place your cloud-init-capable qcow2 image at /srv/barn/images/d13-1-arm64.qcow2 (relative roots, directory symlinks, and shared writable directories are supported), then generate and verify catalog.json on a host with qemu-img installed:

barn repo scan /srv/barn
barn repo build /srv/barn
barn repo verify /srv/barn

barn repo scan inspects the directory layout read-only, while barn repo build runs qemu-img check and writes catalog.json with exact filenames, SHA-256 digests, compressed sizes, and virtual capacities. Increment revision whenever you update repo.yaml or add images, and upload immutable .qcow2 files before publishing the updated catalog.json (and .minisig signature).

Activate and test the local repository:

barn update --repo /srv/barn
barn image info d13 --arch arm64 --repo /srv/barn
barn image pull d13 --arch arm64 --repo /srv/barn

Pass --repo /srv/barn (or export BARN_REPO=/srv/barn) to plan, up, and recreate, and set vm_image: d13@1 in your inventory. To revert /srv/barn back to the binary’s embedded catalog while keeping its anti-rollback high-water mark, run barn image reset --repo /srv/barn.

Import a local image and prune the cache

To use a single custom qcow2 image without creating a repository, import it into Barn’s local cache with a local- alias. The recorded architecture defaults to the host:

barn image import --name local-mybase --boot uefi \
  --source-user ubuntu --sha256 <digest> /path/to/base.qcow2

--name (must start with local-), --boot (uefi or bios), and --source-user are required together when registering an alias; omitting them caches the verified qcow2 bytes by content digest without creating an alias. The image must already include cloud-init support for Barn’s first-boot provisioning. Named local-* aliases are immutable—register a new local-* name whenever you rebuild the image, and reference it in barn.yml with vm_image: local-mybase.

Named imports accept -A, for example barn image import /path/to/arm64.qcow2 --name local-arm64 --boot uefi --source-user ubuntu -A arm64. This records your declaration; it does not convert the image or detect its guest CPU. Set inventory vm_arch or the lifecycle command’s -A to match when using it. -A requires --name on import.

To reclaim disk space from unreferenced images and interrupted download staging files:

barn image prune --dry-run
barn image prune --yes

barn image prune (which requires qemu-img) preserves all images listed in the selected repository’s active catalog, all base images used by existing nodes in BARN_HOME, and all registered local-* aliases.

See Linux Images for catalog signature rules, anti-rollback protection, and cache layout, or Image Pipeline for building new base images from upstream cloud releases.

1.7 - Automation and Guest Scripts

This guide shows how to drive Barn from unattended scripts and CI pipelines. Run all commands as the Unix user who owns the deployment, and pass the same -f <inventory> and BARN_HOME across invocations.

Prepare a predictable lab

Keep your inventory file in version control and pin vm_image to an exact version (such as vm_image: u24@20261017.0.1) so catalog updates never alter your base image mid-pipeline. Passing -f explicitly also prevents first-run setup from relocating an unedited default template to a different subnet. If you use a custom image repository, activate its catalog first with barn update --repo URL and pass the same --repo to setup and up.

Generate and validate the inventory before running host setup:

mkdir -p ~/barn-lab
cd ~/barn-lab
barn init dual
# Edit barn.yml to pin vm_image and node settings.
barn version
barn validate -f barn.yml
barn plan -f barn.yml
barn setup -f barn.yml --dry-run

Once you have reviewed the host plan and ensured non-interactive sudo credentials (or a NOPASSWD policy) are available, prepare the host and bring up the lab:

barn setup -f barn.yml --yes
barn up -f barn.yml --json > up.json

For a generated inventory, barn init [template] --image <reference> writes all.vars.vm_image, so every node inherits the same image. References can be catalog aliases (el9), channels (u24:stable), or version selectors (u24@20261017.0.1). barn setup [template] --image <reference> also selects an image during generation, but rejects this generation flag when using an existing inventory.

--image/-I and --arch/-A share consistent spellings: barn init full -I u24 -A amd64 saves both choices in a new inventory; the same flags on validate, plan, up, reload, recreate, and resize only override desired state for that invocation. For example, preview barn plan -f barn.yml -I u24 -A arm64 --json, then use the same overrides when applying it. Setup’s -I/-A remain limited to template generation.

The same commands also accept --cpu/-C, --mem/-M, --scale/-S, and --disk/-D. Each specification follows CLI flags → nonempty BARN_* environment variables → inventory → defaults. Reuse the same flags and environment for validate, plan, and the operation that applies the plan.

Without an architecture flag, Barn uses BARN_ARCH, then inventory vm_arch, falling back to the host when unset; -A native overrides both and follows the host. Existing VMs require recreate to change image or architecture. For repeatable CI, save vm_image, vm_arch, and an exact image version; see the configuration reference.

barn setup --yes accepts the host-preparation plan without asking. On a terminal, up, start, restart, and reload show the same plan and ask once before installing packages or the Barn network; without a terminal they only report what is missing, so run barn setup --yes before them.

Validate JSON output alongside the exit code

Barn writes structured JSON/YAML payloads to stdout and human diagnostics to stderr. Because barn up returns exit code 0 when management SSH is ready—even if an optional stage such as a secondary data disk, Virtio-9p share, or peer SSH config reported a limitation (nodes[].warnings) or reformatted a damaged test disk (nodes[].repairs)—automation scripts should inspect the JSON payload alongside the exit code:

#!/usr/bin/env bash
set -euo pipefail

if barn up -f barn.yml --json > up.json 2> up.stderr; then
  jq -e '
    (.nodes | type == "array" and length > 0) and
    all(.nodes[];
      .state == "running" and .ready == true and
      ((.warnings // []) | length == 0) and
      ((.repairs // []) | length == 0)) and
    ((.warnings // []) | length == 0)
  ' up.json || exit 1
else
  barn_exit=$?
  cat up.stderr >&2
  cat up.json
  exit "$barn_exit"
fi

When a subsequent pipeline step requires ready guests, omit --no-wait on barn up (barn status --json reads cached state without re-probing guest SSH).

Exit codes and command-specific payloads

Pair CLI exit codes with each command’s JSON schema:

• Exit 2 (usage): Missing inventory on first run, invalid flags, unknown image aliases, or destroy/recreate without --yes when stdin is not a terminal (purge runs without asking).
• Exit 4 (conflict): Inventory drift requiring explicit action (reason: recreate_required or nodes_removed), applied state that changed during a recreate preflight (reason: deployment_changed), or a deployment lock timeout (reason: deployment_busy after waiting up to 10 minutes).
• Exit 5 (partial): Multi-node up or provision where some nodes succeeded and others failed—inspect nodes[] or results[] before retrying.
• Exit 7 (integrity): A digest, signature, or identity check failed, including a catalog signature or signed revision that does not verify (reason: catalog_signature or catalog_equivocation).
• Command-specific reports:
  • barn doctor --json exits 0 when host compute passes even if a class: network check reports an error; check checks[] and barn network status --json before relying on the private bridge.
  • barn ssh and barn exec return the remote command’s exit status (or 255 on OpenSSH transport failure) and record success, exit_code, stdout, and stderr in --json mode.
  • network and hosts install/uninstall without --yes only print the plan and exit 0 when stdin is not a terminal or the output is --json/--yaml; check applied in the result, or pass --yes.

Run single commands or batch scripts

Always place -- between the node selector and the remote command, and put Barn flags (--json, --verbose) before --:

barn exec meta -- hostname
barn exec node-1 -- sh -c 'id; df -h /data'
barn exec meta --json -- uname -a > uname.json

Pass the program and its arguments as separate tokens to barn exec, using sh -c explicitly for pipes, redirection, or shell variables (see SSH passthrough and completion).

To run a health check or setup script across multiple running Linux nodes, save a local Bash script (a regular file or symlink to one, up to 4 MiB):

#!/usr/bin/env bash
set -euo pipefail
hostname
id
findmnt /data
test -d /data

Execute it with barn provision:

barn provision --script ./check-lab.sh meta node-1
barn provision --script ./check-lab.sh --parallel 2 --timeout 5m --json > provision.json

Omitting node selectors runs the script on every node in the deployment (all target nodes must already be running). Barn streams the verified script bytes directly to Bash over SSH without writing a temporary script file in the guest, and records the script’s SHA-256 in the audit result.

• Concurrency and timeouts: Serial by default; --parallel accepts positive integers, with workers capped at the selected node count. --timeout bounds the whole operation, defaults to 1h, and accepts any positive duration. --sudo uses non-interactive sudo -n.
• Output capture and idempotency: Each node captures up to 1 MiB of stdout and 1 MiB of stderr (setting stdout_truncated / stderr_truncated when exceeded). Because partial runs leave completed guest changes in place, write idempotent scripts that are safe to re-run.
• Exit codes: provision exits 5 when some nodes succeed and others fail, passes through a single target’s positive non-255 exit code on failure, and exits 1 otherwise.

Pair the lab with Pigsty

Barn and Pigsty share the same Ansible YAML format. While barn init generates VM hardware topology, Pigsty provides complete service inventories (pigsty.yml) for PostgreSQL, Redis, and monitoring stacks. Provision the VMs with Barn first:

barn validate -f pigsty.yml
barn plan -f pigsty.yml
barn up -f pigsty.yml
barn ssh

During barn up, Barn provisions the guest administrator account and installs the deployment private key on the control node designated by admin_ip, configuring its ~/.ssh/config so Ansible can reach all peer nodes over their fixed private IPs (see Security and Trust). Once barn up completes, SSH into the control node and run Pigsty’s deployment playbooks.

1.8 - Troubleshooting

This guide covers Linux lab diagnostics. For macOS guests, run barn mac doctor and see the Mac troubleshooting section.

Start by collecting the three JSON diagnostic reports (barn status also reconciles interrupted process state when no other command holds the lock):

barn doctor --json
barn network status --json
barn status --json

barn doctor exits 0 whenever host compute checks pass, even if a class: network check reports an error—inspect both checks[] and barn network status --json before assuming barn up can attach to the private network.

Download and PATH problems

The release installer downloads binaries from GitHub Releases (--mirror only selects the guest image repository). If your network requires a proxy to reach GitHub, export HTTPS_PROXY or ALL_PROXY in your terminal session (macOS System Settings proxy entries are not inherited by CLI tools automatically).

The user-scoped installer places binaries in ~/.local/bin. If barn is not found or runs an older version after installation, verify your PATH:

export PATH="$HOME/.local/bin:$PATH"
command -v barn
barn version

Always keep barn and its packaged barn-hosts-helper from the same release in their relative directory layout.

No inventory found

When neither an inventory file nor an applied deployment exists, an interactive barn up generates a starter barn.yml. To use an existing file, run plan, up, or validate in the directory containing barn.yml / pigsty.yml or pass -f /path/to/file (or generate a template first with barn init).

Without -f, plan, up, reload, resize, and recreate check the current directory for barn.yml, barn.yaml, pigsty.yml, and pigsty.yaml in that order, falling back to the applied specification in BARN_HOME only when none of those files exist. If the first matching file contains syntax errors, Barn fails immediately rather than falling back; pass -f pigsty.yml when an older barn.yml sits in the same directory.

If barn status reports no deployment state found, the active BARN_HOME has no applied deployment (either fresh or previously purged).

init output paths and symlinks

barn init and barn setup work through directory symlinks, and barn init -o ./lab/config/barn.yml creates missing parent directories. An existing output file requires --force. Barn never writes through an output-file symlink: with --force it reports will not overwrite …: it is a symlink, so pass the link’s target path instead:

barn init -o "$(readlink -f barn.yml)" --force

Setup needs sudo

Before prompting for a password, barn setup prints the exact host mutation it is about to perform and hands the interactive terminal directly to sudo. Passing --yes auto-confirms Barn’s plan prompt, while sudo authentication itself still requires an interactive terminal, cached credentials, or a NOPASSWD sudoers rule. Run barn setup --dry-run to preview the host plan without executing it.

On macOS, barn setup downloads and verifies the pinned socket_vmnet package before requesting sudo, so a network failure never prompts for a password.

Native acceleration or compatibility runtime is unavailable

Barn requires HVF on macOS or KVM on Linux for native hardware acceleration, and uses QEMU TCG software emulation only when you explicitly request a foreign vm_arch or run an image covered by a built-in compatibility rule (such as el8 arm64 on Apple Silicon). It never falls back to TCG after a native HVF/KVM failure.

Homebrew’s qemu formula includes both arm64 and amd64 system emulators, whereas Linux barn setup installs only the host-native emulator—install the matching qemu-system-* binary and UEFI firmware manually before running foreign-architecture guests on Linux.

Network is partial or invalid

When the Barn host network is intact but stopped, an interactive barn up includes the restart in its host-preparation plan and asks once before applying it; without a terminal, run barn setup --yes. If barn network status reports a partial or invalid state, inspect and apply Barn’s managed cleanup plan instead of deleting system network files by hand:

barn network status --json --verbose
barn network uninstall --json
barn network uninstall --yes

If the Linux bridge smoke test fails during setup, Barn rolls back the network changes automatically; only an explicit automatic rollback failed message requires manual cleanup.

On macOS, barn setup automatically repairs a missing or overly restrictive /var/log/barn-vmnet directory (root:wheel 0755), while refusing to touch a symlink, foreign owner, or group/world-writable directory—follow the exact remediation command printed by barn network status.

Linux bridge helper fails

On Debian and Ubuntu hosts, check the ownership and setuid mode on /usr/lib/qemu/qemu-bridge-helper (expected root:<caller-accessible-group> 4750):

id
stat -c '%U:%G %a %n' /usr/lib/qemu/qemu-bridge-helper
dpkg-statoverride --list /usr/lib/qemu/qemu-bridge-helper

Plan reports recreate or missing

• recreate: The node’s inventory specification changed. Inspect barn plan and back up any data on the root or non-persistent disks before running barn recreate <node> (pass --yes in non-interactive scripts).
• missing: A provisioned node was removed from the YAML inventory. Either restore its YAML entry or run barn destroy <node> to delete the VM. While a node is missing, barn recreate without node names refuses to run before any VM stops (exit 4, reason: nodes_removed).

With node selectors, barn plan node-1 and barn recreate node-1 retain unselected peers’ applied definitions, so an unrelated peer edit does not have to be rebuilt at the same time. Real conflicts in addresses, aliases, control-node roles, or deployment-wide settings still need to be resolved.

A node did not become ready

Readiness requires a working management SSH connection and a verified guest instance UUID. When a node fails to create, boot, or become reachable over management SSH, barn up reports the failing node and stage and exits with code 5. Inspect its logs:

barn logs <node>                  # guest serial console
barn logs <node> --source qemu    # QEMU stderr and diagnostics
barn logs --source events         # host setup and deployment event log
barn status

Secondary guest stages—data disks, Virtio-9p shares, hostname, /etc/hosts, control-node SSH, and the fixed-IP private interface—run independently after management SSH comes up. If one of those stages fails, barn up exits 0 and records the limitation under nodes[].warnings:

Re-running barn up retries only the unfinished stages without restarting healthy VMs. It initializes blank data disks and resets an ext4 or XFS data filesystem only when the filesystem checker reports recognized corruption (see Data disks). Pass --rollback to barn up if you want failed initial preparation artifacts removed in the same run.

For Linux shared folders, both QEMU and the guest kernel need 9p support. A valid host path cannot make an unsupported guest kernel mount 9p; use SSH/SCP/rsync or a kernel with 9p support. This applies on macOS hosts as well as Linux hosts; native macOS guests use VirtioFS separately.

SSH fails

Check barn status, barn ssh-config, and barn logs <node>.

• Deployment SSH keys: If the host’s .pub file is missing, Barn derives it from the intact private key on startup. If the private key itself is missing, restore it from backup—Barn never generates a replacement key for existing VMs. If the control node’s copy of the private key is missing, barn up reports a control-ssh warning while host-to-guest management SSH continues to work.
• Port reassignment and host keys: If another process occupies a stopped VM’s loopback SSH port, the next barn start or barn up picks a free port and updates ~/.ssh/barn_config. SSH host-key verification is scoped to each VM instance UUID, so recreating a node never triggers stale known_hosts errors.
• Dotfile-managed ~/.ssh/config: If ~/.ssh/config is a symlink or hard link, Barn writes ~/.ssh/barn_config and prints the Include line for you to add. If barn ssh meta works but ssh meta fails, verify that Include line.
• Remote command syntax: Place -- between the node name and remote command (barn exec meta -- hostname); see SSH passthrough and completion.

Catalog or image verification fails

Barn embeds active and standby Minisign public keys and rejects unknown signers, catalog revision rollbacks, file size or SHA-256 mismatches, and malformed qcow2 files. A catalog signature or signed revision that does not verify exits 7 (error: integrity, reason: catalog_signature or catalog_equivocation); a permission or I/O error while reading a cached signature remains a runtime failure (exit 1). Always pull from a validly signed repository or register local images through barn image import --sha256 ... rather than copying files directly into ~/.barn/images.

A command was killed

Pressing Ctrl-C or sending SIGTERM cancels a command with exit 130 (cancelled). Barn sends SIGTERM to the processes it started, which sudo forwards to privileged commands, and waits at most 10 seconds for them; a descendant that ignores SIGTERM keeps running until you stop it.

After an interruption, run barn status first. If another Barn process currently holds the deployment lock, status displays a note—wait for that operation to finish before intervening.

When no command holds the lock, barn status verifies each recorded QEMU process identity (matching both PID and process start time) and reconciles the state automatically:

If Barn cannot confirm whether a recorded process belongs to the node (or if a QEMU process is alive but its QMP socket is missing), it blocks further mutations so it never kills an unrelated process. Preserve the state directory and logs (barn logs <node> --source qemu --verbose) rather than deleting PID or lock files by hand.

When filing an issue on GitHub, include the exact command and exit code, barn version, host OS/architecture, QEMU version, and the JSON output of barn doctor, barn network status, and barn status.

1.9 - Build from Source

Build Barn from source when developing a change or auditing a release tag. For prebuilt CLI binaries and the native Barn.app included in the Apple Silicon release, see Install Barn.

Check out the source

Clone tag v1.2.0 to reproduce the documented release (or omit --branch v1.2.0 to work on main), and record git log -1 --oneline and git status --short alongside any build report:

git clone --branch v1.2.0 https://github.com/pgsty/barn.git
cd barn

Tag v1.2.0 reproduces the published release described in the Barn 1.2.0 release notes. Leave BARN_VERSION unset for a development build.

Build the CLI

Barn 1.2.0 pins Go 1.27.4 in go.mod and packaging/toolchain.env, and requires Git, Make, Bash, and standard C/POSIX build tools (compiling the CLI does not require QEMU or host-network setup):

BARN_VERSION=1.2.0 make build
export PATH="$PWD/bin:$PATH"
barn version

make build compiles both barn and barn-hosts-helper into bin/.barn-releases/, embeds the helper’s SHA-256 digest into the CLI, and creates entry-point symlinks under bin/. Always use make build rather than a bare go build ./cmd/barn, and keep bin/.barn-releases/ alongside the bin/ links if you move the build output.

Without BARN_VERSION, development builds report dev, and the commit field marks modified working trees as uncommitted.

To cross-compile the Go CLI and helper for all four supported targets (darwin_amd64, darwin_arm64, linux_amd64, and linux_arm64), run make cross. Keep build artifacts (bin/, dist/, .goreleaser-*/) and lab inventories out of version control; check ignore rules before generating them in the working tree.

Run the contributor checks below against the exact checkout you intend to use. Earlier dated acceptance records are kept in Validation History.

Follow packaging/toolchain.env in the checkout being built. Formal assets use the signed and notarized release procedure.

Build the Mac component

Before rebuilding a local Mac bundle, stop any running Mac VMs that use it.

On an Apple Silicon Mac running macOS 27+ with Xcode 27+ selected for xcrun (providing the macOS 27 SDK and Swift compiler), run:

BARN_VERSION=1.2.0 make mac-build
export PATH="$PWD/bin/mac:$PATH"
barn mac doctor

make mac-build produces a matched bundle under bin/mac (barn, barn-hosts-helper, standalone barn-mac-runner, and Barn.app) as well as bin/barn-mac-darwin-arm64.tar.gz. Run make mac-native-test to execute the Swift component test suite, and follow the macOS VM guide to provision a guest.

The current CLI discovers both Barn.app and legacy Barn Mac.app bundles, whereas the 0.9.0 CLI only looks for Barn Mac.app—always use the barn CLI and native app built together in bin/mac.

Code signing and notarization

When signing environment variables are unset, make mac-build applies an ad-hoc signature for local development. For signed or notarized builds:

• Set BARN_CODESIGN_IDENTITY to sign Barn.app with a Developer ID certificate.
• Set BARN_NOTARY_PROFILE and BARN_MAC_REQUIRE_NOTARIZATION=1 to submit Barn.app for Apple notarization, staple the ticket, and verify Gatekeeper acceptance.
• With BARN_CODESIGN_IDENTITY set, make mac-build also signs the Go helper before embedding its final SHA-256 in the CLI, then signs the CLI. The Mac release handbook adds joint notarization of the CLI/helper/app and verification of the exported release payload.

Run contributor checks

Running the full make check suite requires Python 3, jq, a C compiler (for -race), and the linter/scanner versions pinned in packaging/toolchain.env:

go install honnef.co/go/tools/cmd/staticcheck@v0.8.2
go install golang.org/x/tools/cmd/deadcode@v0.52.0
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0
go install golang.org/x/vuln/cmd/govulncheck@v1.9.0

Ensure GOBIN (or $(go env GOPATH)/bin) is on your PATH, then run:

make test
make check

make check verifies go.mod, shell scripts, repository maintenance rules, unit and race tests, go vet, staticcheck, deadcode, golangci-lint, govulncheck, four-target cross-builds, image-pipeline and installer tests, and dependency licenses. See Contributing and Release Engineering for packaging snapshot checks.

1.10 - Uninstall and Clean Up

Barn manages Linux labs and macOS VMs independently. barn purge removes only the Linux deployment—it does not delete Mac VMs. Keep the barn CLI installed until you have finished removing VMs, integrations, cached images, and host networking.

Choose what to remove

Check barn status (for Linux nodes) and barn mac ls (for Mac VMs), and copy any files you want to keep onto the host before destroying machines.

Full teardown steps

1. Destroy Linux and Mac virtual machines

   To discard the entire Linux lab—including retained persistent disks and deployment keys—run:

   barn purge

   This deletes immediately. Use barn purge --ask to review the VM list and deletion scope, then enter y/yes to confirm or n/no to cancel. It accepts no --yes, -y, or --force. If you also created macOS VMs, list and destroy them by name:

   barn mac ls
   barn mac destroy mac1 dev

2. Remove SSH and /etc/hosts integrations

   Whole-deployment Linux destroy / purge removes the default ~/.ssh/barn_config integration automatically. If you installed a custom named SSH fragment, /etc/hosts entries, or Mac SSH aliases, remove them:

   barn ssh-config --remove --name lab
   barn hosts uninstall --json
   barn hosts uninstall --yes
   barn mac ssh-config --remove

   These commands remove only Barn’s managed blocks, leaving your personal ~/.ssh/config and /etc/hosts entries intact.

3. Prune cached images

   Preview and delete cached Linux and macOS images:

   barn image prune --dry-run
   barn image prune --yes
   barn mac image prune --installers
   barn mac image prune --installers --yes

4. Uninstall Linux host networking

   Preview and remove the shared Linux host network (it stops while any Linux VM is running, so destroy the lab first; Mac VM networks tear down automatically when the VM stops):

   barn network uninstall --json
   barn network uninstall --yes

   When Barn uses systemd-networkd, the uninstall leaves the global networkd unit state unchanged if other host links exist or exclusive Barn use cannot be established; the plan reports preserve_networkd, and the applied report explains the decision in checks.networkd.

5. Uninstall the Barn application and remaining state

   If you installed Barn through a package manager, remove the package:

   Homebrew

   brew uninstall barn

   Debian / Ubuntu

   sudo apt remove barn

   RHEL / Fedora

   sudo dnf remove barn

   • User-scoped install.sh: Remove barn, barn-hosts-helper, .barn-current, .barn-releases/, and .barn-install.lock from ~/.local/bin (and remove the PATH entry from your shell rc file).
   • Manual archive or source build: After stopping all Mac guests, remove the extracted release directory, bin/mac, or any copied Barn.app (Barn Mac.app in 0.9.0), plus ~/Library/Preferences/com.pgsty.barn.plist (io.pgsty.barn.mac-runner.plist in 0.9.0).
   • Manually installed hosts helper: If /opt/barn/libexec/barn-hosts-helper was installed manually and no other user on the host uses Barn, remove it after running barn hosts uninstall --yes.

2 - Reference

Use these pages to look up every command, configuration field, output schema, and image catalog rule in Barn 1.2.0. The version table identifies changes since 1.1.0. For task-oriented walkthroughs, start with the Guides.

• Command Reference — Every Linux and macOS command, complete option tables, defaults, examples, and version availability
• Linux Configuration — Inventory discovery, variables, defaults, data disks, host shares, and node drift rules
• CLI Contracts — Global flags, Linux lifecycle commands, structured JSON/YAML output, and exit codes
• Mac Runtime Reference — barn mac subcommands, VM settings, JSON schemas, error reasons, and runtime files
• Linux Images — Embedded catalog 2026110502, aliases, repository verification, local imports, and cache pruning
• Image Pipeline — Contributor tools for validating and offline-normalizing Linux qcow2 candidates

Barn’s public interface is the barn CLI (barn version, barn <command> --help); Go packages under internal/ are internal implementation details. The image tables reflect the catalog embedded in Barn 1.2.0, while barn update can activate newer signed repository metadata without replacing the binary. For release verification and build gates, see Release Engineering.

2.1 - Command Reference

Find a command below for its arguments, complete local option table, examples, and effects. This reference follows the command-index and command-family organization of PIG. Barn’s CLI contracts describe structured output and exit codes; Configuration defines inventory fields.

Version baseline

This reference covers Barn 1.2.0, released on 2026-11-12 from 90f6158. Its 57 operation commands and 174 local option entries were checked against the CLI help output in both languages.

To preserve the previous defaults when upgrading, set vm_cpu: 2 and vm_mem: 4GiB explicitly and inspect barn plan. Existing applied VMs keep their resources until a resource-changing operation is requested. Use barn version and barn COMMAND --help to check an installed build. See the release notes and release validation.

Command index

Global options

barn [--json|--yaml] [-v|--verbose] COMMAND [arguments] [local options]

Global output options can appear before or after a subcommand, but must precede the remote-command -- separator used by ssh and exec. -f, -I, -A, -p, and --yes are local options: consult the selected command’s table. -f means follow for logs; -n means line count for mac logs. Long boolean options accept =true or =false.

BARN_OUTPUT and BARN_VERBOSE set presentation defaults. BARN_HOME selects private state (default ~/.barn); use an absolute path when changing directories. Linux and Mac machines share that data root but have independent lifecycles. See environment variables and exit codes.

barn and help

barn
barn --help
barn help resize
barn image pull --help
barn --json

With no arguments, text mode prints complete help and exits 0; JSON/YAML mode returns suggested actions[]. Explicit help always prints human-readable text. Groups image, repo, network, hosts, and mac image require a subcommand and exit 2 without one. The mac group is the exception: it defaults to mac ls. It is hidden from root help on Linux and Intel Macs, while explicit Mac help remains available.

Short aliases are scoped to their parent. barn im ls is barn image list; barn mac st is barn mac ls. The per-command pages list each alias. There is no rm alias for purge.

2.1.1 - Preparation and Utilities

Initialize inventories, prepare the host, validate configuration, and inspect the CLI.

This reference covers Barn 1.2.0. Option tables distinguish options also available in 1.1.0 from additions in 1.2.0; see the version baseline. All commands inherit the global options.

barn setup

barn setup [meta|dual|trio|full] [flags]

Prepare host packages, the fixed-IP network, images, and the selected inventory. It does not create the Linux VMs: run barn up afterward. With no template or -f, reuse the discovered inventory or generate meta. The templates meta, dual, trio, and full contain 1, 2, 3, and 4 nodes. -c and specification flags customize a generated template; explicit specification flags cannot be used to rewrite an existing inventory. In 1.2.0, specification environment variables are also ignored when setup reuses an inventory.

--dry-run previews the transaction. Applying it requires terminal confirmation or --yes; operating-system privilege prompts can still occur. On a fresh unedited default template, setup may choose a free private /24 and save barn.yml.before-network-change if the default subnet conflicts. Explicit inventories retain their subnet. On Linux, foreign-architecture QEMU emulators and firmware need separate installation.

Aliases: s.

barn setup --dry-run
barn setup full -I el9 --yes
barn setup -f pigsty.yml --yes
barn up

barn init

barn init [meta|dual|trio|full] [flags]

Generate a Pigsty-compatible YAML inventory. The default is the one-node meta template in ./barn.yml; dual, trio, and full add nodes at .11, .12, and .13. The control node is .10. Existing files require --force; -o - prints the inventory. This command does not download images or prepare the host.

Barn 1.2.0 defaults to 1 vCPU and 2 GiB per node, with a 64 GiB root and a separate 128 GiB /data disk. Generated templates persist all six specification fields, including vm_scale. Version 1.1.0 used 2 vCPUs and 4 GiB by default. See specification defaults.

barn init
barn init full -I el9 -A amd64 -o lab.yml
barn init dual -c 10.20.30.0/24 -o -

barn validate

barn validate [flags]

Read one inventory, validate the fields Barn consumes, and report the resolved nodes. It accepts no node selectors. Discovery checks barn.yml, barn.yaml, pigsty.yml, then pigsty.yaml in the current directory; no inventory means an error even if applied state exists. Overrides affect this validation only. Use --json to inspect the resolved specification, and plan to compare it with an existing deployment.

Aliases: v.

barn validate -f lab.yml
barn --json validate -f lab.yml -I u24 -A arm64

barn doctor

barn doctor [flags]

Probe QEMU, native acceleration, firmware, OpenSSH, a short accelerated boot test, and host networking. This is a host diagnostic and takes no inventory or node arguments. Missing compute capabilities fail the command; missing network setup is reported as informational. Inspect barn network status for the detailed network plan and barn mac doctor for native macOS VMs.

Aliases: dt.

No local options beyond --help; global presentation options still apply.

barn doctor
barn --json doctor
barn doctor --verbose

barn version

barn version [flags]

Print version, source commit, build time, host OS, and architecture. Development builds normally report dev; release identity comes from the build stamp. Use this report when matching documentation or filing an issue. The root shortcut barn --version is also available.

Aliases: ver.

No local options beyond --help; global presentation options still apply.

barn version
barn --json version

barn completion

barn completion [bash|zsh|fish|powershell] [flags]

Require one shell name: bash, zsh, fish, or powershell. Print its completion script to stdout; the command does not install the script. Completion includes scoped flags, templates, image aliases, and best-effort node names. Reload it after upgrading Barn. Use text output when sourcing shell code.

No local options beyond --help; global presentation options still apply.

source <(barn completion bash)
barn completion zsh > "${fpath[1]}/_barn"
barn completion fish > ~/.config/fish/completions/barn.fish
barn completion powershell

Implementation

command_setup.go · command_misc.go · command_root.go

The version baseline identifies the released source and the changes since 1.1.0.

2.1.2 - Linux Lifecycle

Plan, create, start, resize, inspect, and explicitly remove Linux virtual machines.

This reference covers Barn 1.2.0. Option tables distinguish options also available in 1.1.0 from additions in 1.2.0; see the version baseline. All commands inherit the global options.

Node arguments are resolved names such as meta and node-1. Omit them to select all nodes in the command’s inventory/applied scope. IP addresses, groups, and vm_alias are not selectors. plan, up, reload, resize, and recreate read -f, then the current directory’s inventory, then applied state. Other lifecycle commands use applied state directly.

Specification overrides, scaling, and their environment variables are defined in Configuration. The 1.2.0 concurrency option applies only where --parallel is listed; plan, resize, and status do not accept it. For structured results and exit codes, see CLI contracts.

barn plan

barn plan [node...] [flags]

Compare the effective desired inventory with applied state without changing VMs or downloading images. Report exact images, resources, per-disk actions, and nodes needing creation, resize, recreation, start, or explicit removal. Catalog images need only local metadata; inspecting a named local image also needs qemu-img.

Exit 0 means the plan was produced, including plans blocked by omitted nodes. Automation must inspect action, blocked, and the change arrays. Explicit selectors retain the applied definitions of unselected peers. Planning output describes the result.

Aliases: pl.

barn plan
barn plan -f pigsty.yml meta
barn --json plan -I u24 -A amd64

barn up

barn up [node...] [flags]

Create missing nodes, start stopped nodes, and retry unfinished guest setup while keeping healthy running VMs alive. It waits for management SSH unless --no-wait is set, and refreshes host SSH aliases and guest host/control-node entries. Non-fatal guest setup problems appear in warnings; ready nodes still succeed.

On an interactive first run, it can prepare missing host dependencies and generate meta when no inventory or applied deployment exists. Scripts should run setup --yes first. Existing definition changes require resize or recreate; inventory omissions require explicit destroy. --rollback only removes safe, uncommitted artifacts from preparation failures in this run.

barn up
barn up -f pigsty.yml meta
barn up --mirror --rollback
barn up meta --no-wait

barn start

barn start [node...] [flags]

Start selected stopped nodes from applied state and wait for SSH. It works from any directory using the same BARN_HOME, without reading an inventory or creating nodes. It refreshes SSH access; use up to retry unfinished guest setup on an already-running VM. An unavailable share fails its node while independent nodes continue.

barn start
barn start meta --no-wait

barn stop

barn stop [node...] [flags]

Stop selected running Linux VMs using their recorded process identities. It retains root disks, data disks, keys, and deployment state. With no names, stop the whole Linux deployment; it does not stop named macOS VMs or remove the host network.

barn stop meta
barn stop

barn restart

barn restart [node...] [flags]

Stop and start existing nodes using applied state. Inventory edits are not read. Use reload to re-read an inventory, or resize/recreate to apply changed definitions. It waits for SSH unless --no-wait is set.

barn restart
barn restart meta --no-wait

barn reload

barn reload [node...] [flags]

Validate the desired specification and startup dependencies before stopping selected nodes, then converge them through up. It can create newly added nodes. Changes requiring resize or recreation, and omitted applied nodes, fail preflight before any VM stops. Use restart when you want only the recorded configuration.

barn reload -f pigsty.yml
barn reload meta --mirror

barn resize

barn resize [node...] [flags]

Apply CPU/memory changes and grow the root disk while preserving VM identity, disks, and SSH keys. Desired resources come from the inventory, environment, or CLI overrides. Supported CPU/memory increases use hotplug; decreases or unsupported live changes use a stop/start fallback. Image, architecture, data-disk, network, share, create, and remove changes cannot be applied by resize.

Use -D 128GiB to grow the existing root to 128 GiB. Root growth stops QEMU, expands its image, boots the guest to grow and verify a last plain ext4/XFS root partition, then restores an initially stopped VM to stopped. Targets must grow and align to 512 bytes. Retry an interrupted growth with the same target; shrinking, LVM, encrypted roots, and non-last partitions are unsupported. See root growth and recovery. CLI overrides do not rewrite the inventory.

barn plan -f pigsty.yml meta
barn resize -f pigsty.yml meta
barn --json status meta

barn recreate

barn recreate [node...] [flags]

Replace the selected VMs from the desired inventory. This deletes their root disks and non-persistent data disks; compatible persistent data disks are reattached. Inspect plan first. A terminal asks you to type recreate; scripts require --yes or --force (no -y).

No selector means the whole inventory. If it omits an applied node, the operation fails before stopping VMs; explicitly destroy that node or restore it in the inventory. Selected recreation preserves unselected peers. A successful recreation also refreshes SSH access.

Aliases: rc.

barn plan meta
barn recreate meta
barn recreate -f pigsty.yml meta --yes

barn status

barn status [node...] [flags]

Inspect recorded node configuration and live QEMU process identity without requiring the inventory directory. running reports a verified VM process, not an SSH readiness probe. --verbose adds runtime details; --json exposes node records, active-operation notes, and failures. A degraded node can produce exit 5 while healthy peers are still listed. The 1.2.0 text output uses compact SPEC values such as 2c4g.

Aliases: st.

No local options beyond --help; global presentation options still apply.

barn status
barn status meta --verbose
barn --json status

barn destroy

barn destroy [node...] [flags]

Delete selected VMs, or the whole deployment without selectors. Root and non-persistent data disks are deleted; persistent data disks are retained unless a whole-deployment deletion flag is explicit. Terminal confirmation requires typing destroy; scripts need --yes or --force, with no -y.

--delete-persistent and --purge require whole-deployment scope. --purge also removes deployment keys and state. The image cache, host network, and native Mac VMs remain. Removing the control node promotes the first remaining node; update admin_ip and run up to configure its control SSH access.

Aliases: de.

barn destroy meta
barn destroy --yes
barn destroy --yes --purge

barn purge

barn purge [flags]

Immediately delete the entire Linux deployment, including root disks, persistent data disks, keys, state, and the default SSH fragment. It takes no node names and reads no inventory. It has no --yes, -y, or --force: use --ask when you want to review the scope and confirm with y/yes (Enter cancels).

Cached images, host networking, and Mac VMs remain. An absent deployment is an idempotent success; ambiguous retained artifacts still require identity checks. The 1.2.0 --parallel flag controls node work during disposal.

barn purge --ask
barn --json purge

Implementation

command_lifecycle.go · main.go

The version baseline identifies the released source and the changes since 1.1.0.

2.1.3 - Guest Access and Hosts

Connect to Linux guests, run scripts, read logs, and publish SSH or hosts entries.

This reference covers Barn 1.2.0. Option tables distinguish options also available in 1.1.0 from additions in 1.2.0; see the version baseline. All commands inherit the global options.

barn ssh

barn ssh [flags] [node] [-- command...]

Open an interactive SSH session on the selected prepared node, defaulting to the prepared control node (or first prepared node). Remote commands require --; arguments after it are joined for the remote shell like ordinary ssh. Put Barn options before the separator. Node selectors are resolved node names, not IP addresses, aliases, or groups.

A remote command returns its exit status unchanged. Structured interactive SSH sends session output to stderr and the final report to stdout. See SSH argument rules.

No local options beyond --help; global presentation options still apply.

barn ssh
barn ssh meta
barn ssh meta -- 'df -h /data; id'

barn exec

barn exec [flags] [node] -- command...

Run one remote command on the selected prepared node, with the same default-node selection as ssh. -- and a non-empty first command argument are required. Separate arguments preserve spaces, quotes, and later empty values. Use sh -c for pipelines, redirection, or variable expansion; a single command string is also accepted as compatibility shell shorthand.

Text mode forwards the child output and exit status. Structured output includes success, exit_code, stdout, and stderr. A nonzero remote exit is passed through, so inspect that result before interpreting the number as a Barn error class.

Aliases: ex.

No local options beyond --help; global presentation options still apply.

barn exec meta -- hostname
barn exec meta -- printf '<%s>\n' 'a b' ''
barn --json exec meta -- sh -c 'echo out; exit 17'

barn logs

barn logs [node] [flags]

Read the selected node’s serial console or QEMU diagnostic log, defaulting to the prepared control/first node. --source events selects the deployment-wide bounded event log and takes no node argument; it can be read before deployment state exists. Following logs emits a stream rather than one final document. -f means follow here, not inventory. QEMU argv is hidden unless verbose output is enabled.

Aliases: l.

barn logs meta
barn logs meta --source qemu
barn logs --source events --follow
barn --json logs meta --follow

barn provision

barn provision [node...] [flags]

Stream a local Bash script over the verified deployment SSH connection to selected running nodes, or all nodes if no names are supplied. The script is not left behind as a guest file; its digest is recorded for auditing. It does not create or start VMs.

--script is required. The default concurrency is 1 and the timeout is one hour for the operation. Unlike development lifecycle concurrency, --parallel 0 is invalid. --sudo uses noninteractive guest sudo -n; ensure the guest user has the required permission. Review per-node output and failures in structured mode.

barn provision --script ./check.sh meta
barn provision --script ./bootstrap.sh --sudo --parallel 2 --timeout 30m

barn ssh-config

barn ssh-config [node...] [flags]

Print the Linux deployment’s OpenSSH fragment. --install writes a fragment and one Include in ~/.ssh/config; printing and installation accept node selectors. --remove removes only the named Barn fragment, needs no deployment state, and takes no nodes. Install and remove are mutually exclusive.

The default prefix is barn and its fragment is ~/.ssh/barn_config. Normal lifecycle commands maintain the default fragment automatically. If the user’s SSH configuration cannot be safely edited, Barn reports the manual Include instruction; direct barn ssh remains usable.

Aliases: sc.

barn ssh-config
barn ssh-config --install meta
barn ssh-config --install --name lab
barn ssh-config --remove --name lab

barn hosts install

barn hosts install [flags]

Publish applied node names and aliases in the Barn-owned block of the host’s /etc/hosts, using the digest-matched privileged helper. On a terminal it shows the change and asks before applying; in noninteractive or structured mode it only previews unless --yes is passed. An unchanged block requires no privilege. This file is not automatically published by up.

Barn 1.2.0 adds -f pigsty.yml, publishing inventory nodes plus all.vars.vm_hosts before VM creation. It replaces the whole Barn block, so a later call without -f drops inventory-only service names. See local service names.

Aliases: i.

barn hosts install --json
barn hosts install --yes

barn hosts uninstall

barn hosts uninstall [flags]

Remove only the Barn-owned /etc/hosts block while retaining other entries. It needs no inventory or deployment state. Terminal mode displays a plan and asks; noninteractive/structured mode previews unless --yes is supplied. Removing the block does not delete VMs or change guest DNS configuration.

Aliases: u.

barn hosts uninstall --json
barn hosts uninstall --yes

Implementation

command_root.go · command_access.go · main.go

The version baseline identifies the released source and the changes since 1.1.0.

2.1.4 - Image Commands

Refresh signed catalogs, inspect or download images, import local files, and prune caches.

This reference covers Barn 1.2.0. Option tables distinguish options also available in 1.1.0 from additions in 1.2.0; see the version baseline. All commands inherit the global options.

Official repositories and HTTP sources require a trusted detached signature. An explicitly selected custom HTTPS repository or local directory can be unsigned, provided the source is exactly that repository’s catalog.json. Any supplied signature must verify. See catalog trust.

barn update

barn update [flags]

Fetch catalog.json and its signature when required by repository policy, verify trust and revision rules, then atomically activate the catalog. Ordinary commands use local metadata and never update it implicitly. This updates image metadata, not the Barn executable. Repository precedence is --repo > --mirror > BARN_REPO > the global official repository. See repository selection and trust.

barn update
barn update --mirror
barn --json update --repo /srv/barn

barn image list

barn image list [flags]

List every catalog architecture and registered local image. It has no image selector or architecture filter. The active local catalog is used; run barn update explicitly to refresh it. Aliases barn images and barn im select the same image command group.

Aliases: ls.

barn image list
barn --json image list
barn image list --repo /srv/barn

barn image info

barn image info [image[:channel]|image@version-prefix] [flags]

Inspect metadata and verified cache state for one image, using the catalog default if omitted. Select a family (u24), channel (u24:stable), or numeric version prefix (el9@9). Architecture defaults to native. The compatibility spelling --architecture/-a is also accepted for --arch/-A. It does not download the artifact. Supported aliases and exact embedded versions are in Linux images.

Aliases: in.

barn image info
barn image info u24 -A arm64
barn --json image info el9@9

barn image pull

barn image pull [image[:channel]|image@version-prefix] [flags]

Download the selected artifact and verify its SHA-256, byte size, qcow2 structure, and virtual capacity before activating the cache entry. Omitted image and architecture select the catalog default and native host architecture. Existing valid cached bytes are reused. The catalog’s upstream URL is provenance, not a download fallback. --architecture/-a remains a compatibility alias. A foreign artifact does not install the corresponding QEMU emulator.

Aliases: p.

barn image pull
barn image pull u24 --mirror
barn image pull d13 -A amd64 --repo /srv/barn

barn image import

barn image import <path> [flags]

Copy a local regular qcow2 image into the private cache and validate its container, optionally against an expected digest. Relative paths, ~/, and symlinks to regular files are accepted. qemu-img is required; importing does not boot the image, add cloud-init, or change credentials.

A local-* name registers an immutable inventory reference and requires boot mode plus the source login user. Named imports can record a foreign architecture with -A; qcow2 metadata does not identify CPU architecture, and unnamed imports cannot use -A. Set both vm_image and a matching vm_arch when using it. See import and cache rules.

Aliases: i.

barn image import ./base.qcow2
barn image import ./base.qcow2 --name local-dev --boot uefi --source-user ubuntu -A arm64

barn image sync

barn image sync <url|path> [flags]

Activate a catalog from one exact URL or local file, reading its adjacent .minisig signature under the trust policy above. This is the recovery/import path; use update for the configured repository’s normal endpoint. --repo chooses which repository’s active metadata to replace. An unsigned custom source must be exactly <repo>/catalog.json; an arbitrary recovery file requires a trusted signature.

Older revisions require --allow-downgrade. For custom repositories that allow unsigned catalogs, switching from a previously signed catalog to an unsigned one also requires this flag. It never permits an invalid signature or bypasses the official-repository signature requirement and revision-content checks. Future downgrade protection still remembers the highest revision.

Aliases: sy.

barn image sync /srv/barn/catalog.json
barn image sync --repo /srv/barn /srv/recovery/catalog.json
barn image sync --allow-downgrade /srv/recovery/catalog.json

barn image reset

barn image reset [flags]

Reactivate the catalog embedded in the current binary for the selected repository. It keeps the highest accepted revision used by downgrade protection. Cached images and VM disks are retained; this is not a cache deletion command.

barn image reset
barn --json image reset --repo /srv/barn

barn image prune

barn image prune [flags]

List reclaimable cache files by default. --yes deletes candidates; it is mutually exclusive with --dry-run. The selected active catalog, applied node base-image digests, and registered local aliases protect their referenced files. Stale recognized staging files can also be removed; quarantined .corrupt-* files remain.

Preview with the same repository selection you will use for deletion. Deletion is sequential; an error on a later file does not restore files already removed. See pruning rules.

Aliases: pr.

barn image prune --dry-run
barn image prune --repo /srv/barn --dry-run
barn image prune --repo /srv/barn --yes

Implementation

command_image.go · images.go

The version baseline identifies the released source and the changes since 1.1.0.

2.1.5 - Repository Commands

Scan, build, and verify static image repositories from repo.yaml and qcow2 artifacts.

This reference covers Barn 1.2.0. Option tables distinguish options also available in 1.1.0 from additions in 1.2.0; see the version baseline. All commands inherit the global options.

barn repo scan

barn repo scan <root> [flags]

Scan one repository root containing repo.yaml and a flat images/ directory. Report tracked, missing, untracked, and unsafe qcow2 files without changing them or requiring qemu-img. Successful scanning exits 0 even with findings; automation must inspect missing and unsafe rather than rely on the exit code alone.

No local options beyond --help; global presentation options still apply.

barn repo scan /srv/barn
barn --json repo scan /srv/barn

barn repo build

barn repo build <root> [flags]

Validate repo.yaml, inspect the declared qcow2 artifacts with qemu-img, calculate final digests/sizes, and atomically generate catalog.json. Missing or unsafe artifacts fail the build; untracked files are omitted. repo.yaml and image bytes are preserved.

This command does not sign or publish a catalog. Increment the revision for changed contents, keep artifact filenames immutable, and use the separate contributor signing tools before publication. See repository format.

No local options beyond --help; global presentation options still apply.

barn repo build /srv/barn
barn --json repo build /srv/barn

barn repo verify

barn repo verify <root> [flags]

Rebuild the expected catalog in memory and require byte-for-byte agreement with the existing catalog.json, using repo.yaml and actual image bytes. Requires qemu-img. It checks repository consistency; detached-signature verification belongs to catalog activation and the signing tools.

No local options beyond --help; global presentation options still apply.

barn repo verify /srv/barn
barn --json repo verify /srv/barn

Implementation

command_repo.go

The version baseline identifies the released source and the changes since 1.1.0.

2.1.6 - Host Network Commands

Inspect, install, and remove the fixed-IP network used by Linux guests.

This reference covers Barn 1.2.0. Option tables distinguish options also available in 1.1.0 from additions in 1.2.0; see the version baseline. All commands inherit the global options.

barn network status

barn network status [flags]

Inspect the one host-wide Linux-guest network: backend, installed CIDR, ownership, health, and lifecycle preflight findings. --cidr checks an expected subnet; omitting it inspects the installed one. It is read-only. This network is separate from each native Mac VM’s private network.

Aliases: st.

barn network status
barn --json network status --cidr 10.10.10.0/24

barn network install

barn network install [flags]

Inspect or install the host-wide backend: socket_vmnet on macOS or barn0 through the active Linux network manager. On a terminal it shows a privileged plan and asks; structured/noninteractive calls only preview unless --yes is supplied. On a fresh Mac, use setup to obtain the pinned socket_vmnet archive first.

--archive and --interface-id are macOS-only. host/shared are macOS vmnet modes; Linux rejects shared. An existing network must match the chosen configuration; review status before changing subnet or mode.

Aliases: i.

barn network install --json
barn network install --cidr 10.10.10.0/24 --yes

barn network uninstall

barn network uninstall [flags]

Remove only Barn-owned network configuration and restore recorded host settings. Stop running Linux guests first: the operation refuses a live deployment. Terminal mode asks after showing the plan; structured/noninteractive calls preview unless --yes is set. This does not delete VM disks or native Mac networks.

Aliases: u.

barn stop
barn network uninstall --json
barn network uninstall --yes

Implementation

command_network.go

The version baseline identifies the released source and the changes since 1.1.0.

2.1.7 - macOS Commands

Manage named native macOS VMs, desktop access, restore images, and shared bases.

This reference covers Barn 1.2.0. All options below were also available in 1.1.0.

Native macOS VMs require Apple Silicon, macOS 27+, and the matching Barn.app native app bundle, invoked as the logged-in desktop user. Their state lives under $BARN_HOME/mac and is independent of the Linux inventory.

For an optional name, Barn selects the sole existing VM or mac1; multiple VMs without mac1 require an explicit name. configure, recreate, and destroy always require names. start and stop accept multiple names or --all. At most two macOS VMs can run concurrently across apps on the host, including an active base installation. See machine rules, networking, output, and files.

Mac resource sizes use binary units even for GB, unlike Linux inventory decimal GB; a bare Mac size is bytes. These commands ignore Linux BARN_IMAGE/BARN_ARCH/BARN_CPU/BARN_MEM/BARN_SCALE/BARN_DISK overrides.

barn mac ls

barn mac ls [flags]

Show every machine: its state, address, SSH readiness, macOS version and resources. It reads local records and asks each running machine, and never creates, downloads or starts anything.

Running barn mac without a subcommand also lists machines.

Aliases: list, status, st.

No local options beyond --help; global presentation options still apply.

barn mac ls
barn --json mac ls

barn mac up

barn mac up [name] [flags]

Create the named machine (mac1 by default), start it, and wait until SSH and passwordless sudo work. Without a prepared macOS base, up first downloads the restore image from Apple after confirmation and installs it once; later machines clone that base.

Creation options apply to a new machine. For an existing machine, up starts it and rejects options that differ from its configuration; use configure for supported setting changes.

--no-wait returns once the VM is running. First-boot provisioning may still be in progress; run barn mac up NAME again to wait for SSH and finish initialization.

barn mac up
barn mac up dev --cpu 8 --memory 16G --share ~/src --open
barn mac up build --yes --no-wait

barn mac start

barn mac start [name...] [flags]

Start existing machines and wait for SSH without creating machines or downloading images. --recovery boots macOS Recovery with its desktop shown.

Select names or --all, not both. Ordinary start requires completed first-boot initialization; use up to finish an uninitialized VM.

barn mac start mac1
barn mac start --all
barn mac start mac1 --recovery

barn mac stop

barn mac stop [name...] [flags]

Shut machines down normally through macOS. A machine that has not stopped after two minutes is powered off, and the result says so. --force powers off at once, like holding a power button; unsaved work in the guest is lost.

barn mac stop dev
barn mac stop --all
barn mac stop dev --force

barn mac restart

barn mac restart [name] [flags]

Shut a machine down normally and start it again, applying configuration changes.

Accepts at most one name; there is no --all. Omitted names follow the default-machine rule above.

barn mac restart dev
barn mac restart dev --open

barn mac configure

barn mac configure <name> [flags]

Change settings of an existing machine without touching its disk or account. CPUs, memory, shared folders and the network change while the machine is stopped; the clipboard setting can change anytime. Saved configuration, including clipboard changes, applies at the next start; use the menu-bar control to toggle clipboard sharing in the current session.

An explicit name is required. Omitted flags retain their values. --share adds or replaces a named share; --unshare removes one.

barn mac stop dev
barn mac configure dev --cpu 8 --memory 16G --share ~/src
barn mac configure dev --unshare src --clipboard off
barn mac start dev

barn mac recreate

barn mac recreate <name> [flags]

Erase the machine’s disk and start a fresh macOS with the same name, account, resources, shared folders and address. --update uses the newest prepared base (see barn mac image update). Its files, apps and settings are lost.

A terminal asks you to type recreate; scripts require --yes or --force, with no -y shorthand.

barn mac recreate dev
barn mac image update --yes
barn mac recreate dev --update --yes

barn mac destroy

barn mac destroy <name...> [flags]

Power machines off and delete them: disk, keys, password and settings. The shared macOS base and other machines are kept; barn mac image prune removes unused bases.

Explicit names are required. A terminal asks you to type destroy; scripts require --yes or --force, with no -y. Shared host folders are retained.

barn mac destroy dev
barn mac destroy mac1 mac2 --yes

barn mac open

barn mac open [name] [flags]

Show the machine’s desktop window, starting the machine first when it is stopped. Closing the window keeps the machine running in the background; the clipboard is shared while the window is focused.

An uninitialized running VM can be viewed here; for a stopped uninitialized VM use mac up NAME --open.

No local options beyond --help; global presentation options still apply.

barn mac open
barn mac open dev

barn mac ssh

barn mac ssh [flags] [name] [-- command...]

Connect with the machine’s own key and pinned host key. Everything before – must be empty or one known machine name, apart from Barn flags. A remote command requires –, and its first argument must not be empty. For exec, pass the program and its arguments separately to preserve argument boundaries, including later empty values. Use sh -c explicitly for shell expressions. A single command string remains supported as shell shorthand for compatibility. exec requires a command. ssh passes the command line to the remote shell like plain ssh. Without a command, ssh opens an interactive session.

No local options beyond --help; global presentation options still apply.

barn mac ssh dev
barn mac ssh dev -- 'sw_vers; id'

barn mac exec

barn mac exec [flags] [name] -- command...

Connect with the machine’s own key and pinned host key. Everything before – must be empty or one known machine name, apart from Barn flags. A remote command requires –, and its first argument must not be empty. For exec, pass the program and its arguments separately to preserve argument boundaries, including later empty values. Use sh -c explicitly for shell expressions. A single command string remains supported as shell shorthand for compatibility. exec requires a command. ssh passes the command line to the remote shell like plain ssh. Without a command, ssh opens an interactive session.

No local options beyond --help; global presentation options still apply.

barn mac exec dev -- sw_vers
barn mac exec dev -- printf '<%s>\n' 'a b' ''
barn --json mac exec dev -- sh -c 'echo out; exit 3'

barn mac password

barn mac password [name] [flags]

Show the password of the machine’s login account, needed for the lock screen and administrator prompts in its desktop. It is stored next to the machine’s SSH key with the same protection. --copy puts it on the clipboard instead of printing it.

barn mac password dev
barn mac password dev --copy

barn mac ssh-config

barn mac ssh-config [flags]

Print the OpenSSH fragment that lets ssh, scp, rsync and editors reach each machine by name with its own key and pinned host key. The first machine to become ready installs it as one Include in ~/.ssh/config, and lifecycle commands keep it current. –remove deletes only what Barn installed and keeps it out until –install. A name that ~/.ssh/config already uses for another host is published by address only.

--install and --remove are mutually exclusive. This command takes no machine selectors.

barn mac ssh-config
barn mac ssh-config --install
barn mac ssh-config --remove

barn mac logs

barn mac logs [name] [flags]

Show the last lines of the machine’s runtime log: startup, network, shutdown and Apple Virtualization errors.

--lines/-n must be positive and defaults to 100. There is no follow flag; -n means lines, not no-wait.

barn mac logs dev
barn mac logs dev --lines 200

barn mac setup

barn mac setup [flags]

Download macOS from Apple after you confirm, or read –ipsw, and install it once into the unbooted base that every machine is cloned from. up does this automatically; setup lets you do it ahead of time.

barn mac setup --yes
barn mac setup --ipsw ~/Downloads/restore.ipsw --disk 200G

barn mac image ls

barn mac image ls [flags]

List restore images and bases with their state, disk usage and the machines that use them.

This local-state query does not invoke the native runner.

Aliases: list.

No local options beyond --help; global presentation options still apply.

barn mac image ls
barn --json mac image ls

barn mac image update

barn mac image update [flags]

Ask Apple for the newest macOS 27 restore image, download it after you confirm, and install it as the default base for new machines. Existing machines keep their base until barn mac recreate –update.

barn mac image update --yes
barn mac image ls

barn mac image prune

barn mac image prune [flags]

List unused bases except the current default base. --installers also includes downloaded restore images and partial downloads. Deletion requires --yes.

barn mac image prune
barn mac image prune --installers --yes

barn mac doctor

barn mac doctor [flags]

Check macOS and Apple Silicon support, the Mac component’s signature, free disk space, the prepared base, and every machine: its files, keys, shared folders, network and SSH. It changes nothing and starts nothing.

No local options beyond --help; global presentation options still apply.

barn mac doctor
barn --json mac doctor

Implementation

command_mac.go

The version baseline identifies the released source and the changes since 1.1.0.

2.2 - Configuration

This reference covers Barn 1.2.0. Linux defaults are 1 vCPU and 2 GiB. To preserve the 1.1.0 defaults on upgrade, explicitly set vm_cpu: 2 and vm_mem: 4GiB. See the version baseline and check the installed build with barn version and --help.

Discovery

Barn resolves the inventory path by checking an explicit -f argument first, then searching the current working directory for barn.yml, barn.yaml, pigsty.yml, and pigsty.yaml in that order. All four filenames use the same Pigsty-compatible YAML inventory format.

When no inventory file is present in the current directory, plan, up, reload, recreate, and resize fall back to the applied specification stored in BARN_HOME (default ~/.barn) if a deployment already exists. validate always requires an inventory file on disk. The file must resolve to a regular file no larger than 4 MiB; symlinks are supported. Relative shared-directory paths resolve beside the inventory’s real file. Barn stops at the first matching filename and reports any parse or validation error directly rather than falling through to the next candidate.

Barn stores applied deployment state in BARN_HOME. Renaming the inventory does not change the deployment; use an absolute BARN_HOME to address the same deployment across working directories.

A complete inventory

barn init [meta|dual|trio|full] generates a 1-, 2-, 3-, or 4-node topology template. meta uses .10, and larger templates add node-1 at .11, node-2 at .12, and node-3 at .13 (defining VM topology while leaving Pigsty service roles to your upper-layer playbook). Pass --cidr to change the /24 prefix while keeping the host octets, or run barn init full -o - to print a template to stdout without writing a file.

all:
  vars:
    admin_ip: 10.10.10.10
    vm_image: u24
    vm_cpu: 2
    vm_mem: 4GiB
    vm_disk: 64
  children:
    lab:
      hosts:
        10.10.10.10: { nodename: meta }
        10.10.10.11:
          nodename: worker
          vm_mem: 8GiB
          vm_disks:
            - { path: /data, size: 128, fs: auto, persistent: true }

This inventory defines two managed nodes with meta as the control node. Save it as barn.yml and inspect the resolved configuration before starting any VMs:

barn validate -f barn.yml
barn --json validate -f barn.yml
barn plan -f barn.yml

validate checks YAML syntax, field rules, and image catalog references (pass --repo to check against another repository’s catalog) without starting VMs or downloading images. Its JSON output includes valid, source, spec_hash, and resolved; if the local image catalog cannot be read, it emits a warning and leaves image selectors unresolved. During up, Barn verifies local-* imported image bytes, host capabilities, shared directories, networking, and guest SSH readiness.

What Barn reads

An inventory must contain a top-level all: group, from which Barn traverses hosts and nested children mappings. Barn parses static YAML directly—without evaluating Ansible inventory plugins, Jinja expressions, group_vars, or host_vars. If the same IPv4 address appears in multiple groups, Barn merges its inherited variables into a single node definition.

Barn reads node IPv4 keys, nodename, admin_ip, pg_cluster, pg_seq, node_admin_username, node_admin_uid, and the vm_* variables listed below:

• Control node: Barn reads admin_ip from all.vars. If admin_ip is omitted or does not match a managed node, Barn selects the first managed node encountered in YAML traversal order (reading each group’s hosts before its children). Set admin_ip explicitly so the control node stays fixed when you reorder groups.
• Login account: All nodes share one login username matching [a-z_][a-z0-9_-]{0,31}. For the default dba user, an explicit node_admin_uid must be 88. For a custom username, Barn verifies that node_admin_uid is an integer if present, while the guest assigns the account’s UID at creation time.
• Upper-layer Pigsty fields: Variables outside Barn’s scope—such as pg_role, pg_version, repo_*, and node_packages—are ignored by Barn and never trigger VM configuration drift.
• Inheritance and validation: Variables inherit along all.vars → nested children.<group>.vars → host variables. Host-level list variables such as vm_disks replace inherited lists wholesale. If two sibling groups at the same depth set conflicting values for the same node, override the variable on the host entry. Unknown vm_* keys, invalid types, Jinja templates, duplicate YAML keys, and multi-document YAML streams fail validation with line numbers, violated rules, and spelling suggestions for mistyped vm_* names. YAML anchors and << merge keys are supported (explicit keys win, followed by the first mapping in a merge sequence).
• Skipped nodes: Hosts with vm_skip: true may use hostnames or IPv6 keys and do not participate in the managed /24; at least one managed node must remain. Skipping an existing node marks it missing in plan without destroying it.

VM variables

An empty host mapping (10.10.10.10: {}) is enough to define a complete VM with default settings. Managed nodes require distinct usable addresses in the configured /24.

Bare integers specify MiB for vm_mem and GiB for disks. Size strings accept positive integers with case-insensitive units, including 8G, 512m, 4gib, and 64GB. K/M/G/T and KiB/MiB/GiB/TiB use binary powers; KB/MB/GB/TB use decimal powers. Fractions such as 1.5GiB and unitless strings such as "8192" are invalid. up checks that the root disk is at least as large as the base image’s virtual size.

When vm_image is omitted, Barn defaults to u24 (Ubuntu 24.04) from the binary’s embedded catalog regardless of any default declared in a custom repository. Built-in aliases such as ubuntu → u24 are normalized against the embedded catalog during inventory parsing, so custom repositories should use their canonical family names in vm_image rather than reassigning built-in aliases.

Use vm_version when you want to keep the image family and version prefix in separate fields:

vm_image: el9
vm_version: "9.8"

If an exact version match exists in the catalog, Barn selects it; otherwise it matches dot-separated numeric prefixes and picks the highest version (9.8 selects the latest 9.8.* build, 9 selects the latest 9.x release, and 9.10 sorts after 9.9). Use vm_version only with a bare family name in vm_image (without :channel or @version).

Resource scaling in 1.2.0

Resolve vm_cpu, vm_mem, and vm_scale independently: host variables override the deepest group, which overrides parent groups and all.vars. Missing values default to 1 vCPU, 2048 MiB, and a scale of 1. Multiply once after inheritance:

CPU    = resolved(vm_cpu, default=1) × resolved(vm_scale, default=1)
Memory = resolved(vm_mem, default=2048 MiB) × resolved(vm_scale, default=1)

A host’s vm_scale: 1 replaces a group’s vm_scale: 3; group and host scales do not compound. Equal-depth conflicts require a host override. Scale accepts integers from 1 to 256, subject to the effective 256-vCPU limit and memory overflow checks. Quoted numbers, fractions, booleans, null, zero, and negative values fail validation. Base memory still requires at least 512 MiB. Root disks, data disks, and shares are unaffected. Use the exact keys vm_cpu and vm_mem; vm_memory is not an alias.

Inspect barn plan -f pigsty.yml, then apply CPU/memory changes with barn resize -f pigsty.yml. Existing deployments that omit these fields will show a resource decrease when their inventory is read by the new build. Add vm_cpu: 2 and vm_mem: 4096 before upgrading to preserve the previous defaults. Commands using applied state without an inventory keep the recorded resources.

Local service names in 1.2.0

Inventory-based hosts publication is available in Barn 1.2.0.

Declare finite service mappings in all.vars.vm_hosts. Barn combines them with node names and vm_alias when publishing from an explicit inventory:

all:
  vars:
    vm_hosts:
      - {address: 10.10.10.10, names: [i.pigsty, m.pigsty]}
      - {address: 10.10.10.100, names: [pg-dns-service]}
  hosts:
    10.10.10.10: {nodename: meta}

barn hosts install -f pigsty.yml --json  # preview, including before VM creation
barn hosts install -f pigsty.yml --yes  # publish; sudo may ask for a password
barn hosts uninstall --yes

Each entry requires address and a non-empty names list. Addresses must be canonical IPv4 addresses in the inventory’s private /24, within .9–.254; .1–.8 are reserved for the host and DHCP. Identical name/address pairs deduplicate; names compare without case, and different destinations fail validation. Existing conflicting names outside the Barn-owned block also stop publication. A hosts record does not configure a VIP in a guest.

These mappings affect only the host’s /etc/hosts. Editing them does not change the VM spec hash, configure guest DNS, or trigger VM drift. Without -f, hosts install publishes only names and aliases from applied VM state, replacing the whole Barn block; repeat the explicit inventory command to retain service names. up never publishes this file automatically. An unchanged plan needs no sudo; each changed system hosts file requires privilege. Wildcards, SRV records, and live primary discovery require a DNS service.

Pigsty’s development bin/sandbox-dns extracts its portal, node, PostgreSQL, VIP, and MinIO names for this interface. See the migration audit.

Specification overrides

Barn 1.2.0 accepts unified CLI and environment inputs for six specification fields. Version 1.1.0 supports the image/architecture flags but not the four resource flags or these environment variables.

Each field follows CLI > nonempty environment > host > deepest child group > parent group > all.vars > default. CPU and memory always specify bases; multiply each once by the final scale after applying overrides. Disk capacity does not scale. -S 3 replaces the previous multiplier; add -S 1 for exact final CPU/memory. CLI and environment override host values on selected nodes. Put common defaults in all.vars when host exceptions should remain effective. Inventory syntax, field types, and inheritance conflicts must remain valid.

barn init full -C 2 -M 4GiB -S 2 -D 128GiB
barn plan -f barn.yml -S 3
BARN_SCALE=2 barn validate -f barn.yml -S 1

init and template-generating setup write all six choices, including defaults, and save CPU/memory bases and scale. The first interactive up also saves its choices if it needs to generate an inventory. Lifecycle overrides on an existing file change only the current desired specification without rewriting YAML; reading the original file later reports drift. When only applied state remains, --scale or BARN_SCALE requires -f; CPU/memory can set absolute values with an implicit scale of 1.

Environment variables affect only commands accepting the corresponding specifications. status/start/stop/restart/destroy/purge, independent image management, and barn mac ignore these six variables. So does setup when reusing an inventory. resize accepts CPU/memory/scale, root capacity, and its existing I/A consistency checks; BARN_DISK only grows the root disk. Whitespace-only environment values mean unset, and invalid values shadowed by CLI do not fail: BARN_CPU=bad barn plan -C 2 uses 2. Effective environment overrides are preserved as explicit flags in follow-up commands.

--disk sets the absolute system root capacity, which must be at least the base image’s virtual size. Planning checks catalog metadata; creation checks the actual image again. It applies to creation, explicit recreation, and in-place root growth through resize -D. Growth supports last plain ext4/XFS root partitions and never shrinks them; see root disk growth for the workflow and recovery. Recreation replaces root and nonpersistent data disks. The default 128 GiB /data disk remains separate.

Image and architecture overrides

Image and architecture follow the same specification precedence as the resource fields: CLI flags, nonempty environment variables, inventory values, then defaults.

Guests default to the host architecture: arm64 on Apple Silicon and amd64 on Intel/AMD hosts. Another architecture can be selected through the CLI, environment, or inventory. Precedence is --arch/-A → BARN_ARCH → inventory vm_arch → native (host architecture). Use -A native to override the environment and inventory and follow the host again.

vm_arch applies to the entire deployment; define it once under all.vars. Every managed node must resolve to the same architecture. Node variables and selectors cannot create a deployment with mixed architectures.

--image/-I overrides BARN_IMAGE and the selected nodes’ vm_image/vm_version without changing architecture. Without the flag, a nonempty BARN_IMAGE overrides the inventory image. The catalog must provide the requested architecture variant; a missing variant is an error and never selects another architecture automatically.

barn plan -I u24                 # Ubuntu 24.04; retain the environment, inventory, or host architecture
barn up -I u24 -A amd64          # Use amd64 Ubuntu 24.04 for this invocation
barn plan -A native              # Override the inventory architecture with the host's
barn init full -I u24 -A arm64   # Save both choices in a new inventory

Overrides on up, plan, reload, recreate, resize, and validate change only the desired configuration for that invocation. To keep a choice, set all.vars.vm_arch and the relevant node or group vm_image, removing any superseded vm_version. init and template-generating setup write the choices into the new inventory. Setup’s -I/-A flags cannot be used with an existing inventory.

When no inventory file exists, lifecycle commands use the saved deployment specification before applying explicit overrides. start and restart always use applied state. Omitting -A or editing the inventory never converts an existing VM: up reports drift, and switching architecture requires recreate with all existing nodes selected. resize applies CPU/memory changes and grows supported root disks; image and architecture changes require recreate.

Guests whose architecture differs from the host use QEMU TCG. On Linux, barn setup installs the native emulator; install the target qemu-system-* binary and UEFI firmware before starting a foreign guest. See Runtime policy for acceleration and image exceptions.

Data disks

vm_disks:
  - path: /data
    size: 128
    fs: auto
    persistent: false

Each entry in vm_disks configures an additional virtual block device:

• path: Absolute mount path, normalized automatically; spaces, Unicode, and shell punctuation are supported. Simple paths retain existing disk names; other paths get stable digest-based names. Identities must be unique within a node. System directories and overlapping mount paths remain invalid.
• size: Disk capacity, defaulting to 128 (128 GiB). Accepts a GiB integer or an explicit size string.
• fs: Filesystem type—auto (default), xfs, or ext4. On a blank auto disk, Barn formats with XFS when mkfs.xfs is available in the guest and falls back to ext4 otherwise. Explicit xfs or ext4 settings require that filesystem tool and never fall back. Healthy existing filesystems are mounted as-is.
• persistent: When true, ordinary barn destroy and barn recreate keep the disk image on the host so the recreated node reattaches it when the disk identity and definition remain compatible. Set vm_disks: [] to create a node with no extra data disks.

Shares

vm_shares:
  - host: ./src
    guest: /src
    readonly: true

vm_shares mounts host directories into Linux guests through QEMU Virtio-9p on Linux and macOS hosts, with readonly: true by default. Host QEMU and the guest kernel must support 9p; backend device limits apply. Native macOS guests use VirtioFS through barn mac --share.

Shared sources use the invoking user’s actual filesystem permissions:

• host accepts absolute paths, ~/, inventory-relative paths, and directory symlinks. guest must be absolute and is normalized automatically; spaces, Unicode, and shell punctuation are accepted, while control characters are rejected.
• Resolved host directories must exist, be accessible, and not overlap BARN_HOME; ownership by the invoking user is not required.
• Host sources may overlap and may be shared by multiple readers or writers. Users coordinate concurrent writes. Guest mount targets within one node must not overlap.
• guest paths cannot overlap data-disk mounts, system directories, or the login user’s .ssh directory. Use 9p shares for source code and build artifacts rather than PostgreSQL data directories.
• If a writable share (readonly: false) cannot be written by the guest user, Barn mounts it read-only, reports a warning, and leaves host file ownership untouched; fix host permissions and re-run barn up to upgrade the mount.
• Changing vm_shares on an existing node requires barn recreate. Missing host directories during up or start fail only the affected node, while restart, reload, and recreate verify share paths before stopping running VMs.

Names and addresses

Barn resolves each node’s name from the first available source: explicit nodename, <pg_cluster>-<pg_seq>, or node-<last-octet>. Node names must be unique across the deployment, be 1–63 characters long, contain only lowercase letters, digits, and hyphens, and neither start nor end with -. vm_alias accepts additional lowercase DNS names (dots allowed) that must be distinct from all node names and other aliases.

All managed nodes in a deployment must belong to a single RFC1918 /24 subnet: .1 is the host gateway, .2–.8 are reserved, and .9–.254 are available for nodes. Inside the guest, the fixed-IP NIC carries the configured inventory address (inspectable via ip -br addr).

Drift

Explicit node selectors apply only selected changes: plan node-1, up node-1, reload node-1, recreate node-1, and resize node-1 retain the applied definitions of unselected peers, even when edited or omitted in the inventory. The entire inventory must still parse correctly. Images for uncreated, unselected nodes are not resolved. Conflicts with applied addresses, aliases, control-node roles, or deployment-wide settings are still rejected.

Barn computes a specification hash for every resolved node:

• barn up creates newly added nodes, starts stopped nodes, and retries unfinished guest provisioning on running nodes without restarting their QEMU processes.
• Modifying a node’s CPU or memory uses barn resize <node> and preserves its identity and disks. Barn 1.2.0 also supports grow-only root capacity through resize -D. Image, data-disk, share, or other VM definition changes require barn recreate <node>. Removing a node from the inventory (or setting vm_skip: true) reports the node as missing in plan without automatically destroying it.
• Changing deployment-wide settings (vm_arch, login username, or the /24 subnet) requires recreating the entire deployment.
• Because plan and up resolve image channels and version prefixes against the active catalog, running barn update can introduce image drift even when barn.yml has not changed. Always keep an explicit nodename on each host so renaming pg_cluster does not turn an existing node into a missing old node plus a new node.

2.3 - CLI Contracts

This page describes Barn 1.2.0 global presentation, Linux lifecycle semantics, structured output, and exit codes. For syntax, options, defaults, and examples, use the Command Reference. Native Mac runtime contracts are in Mac Reference.

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

Every command documents its local flags and examples through --help:

barn --help
barn setup --help
barn image pull --help

Running barn with no arguments prints the same complete help as barn --help and exits 0; with --json or --yaml it returns an actions[] array of suggested next commands instead. Invoking a command group without a subcommand—such as barn image—exits 2 (printing help in text mode or a usage error object in JSON/YAML mode). Explicit --help always prints human-readable help and exits 0. Use barn --version or barn version to inspect the build identity.

Commands