Barn — Linux and macOS virtual machines on Barn

Install Barn

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

Barn 0.9.0 provides archives for macOS and Linux on arm64 and amd64, plus DEB and RPM packages for Linux. Install it as your normal user, then follow the Linux quick start or macOS VM guide.

Install the release

Choose your host operating system: use Homebrew on macOS or the download installer on Linux.

macOS

Install Barn and its QEMU dependency with Homebrew:

brew install pgsty/infra/barn
barn version

Run brew as your normal user, without sudo. macOS guests also require Apple Silicon, macOS 27+, and Barn Mac.app. Run barn mac doctor to check the native component; see the Mac installation instructions.

Why Barn Has No Projects

Thu, 27 Aug 2026 19:00:00 +0800

This article describes Barn 0.9.0. The VM lifecycle and network design here apply to Linux guests; Mac machines are managed independently.

Barn began with a familiar VM-manager abstraction: a working directory was a project, a hidden marker gave it identity, a registry found projects again, and a host-global lease kept their private networks from colliding. That model can support many independent VM sets. It was also the wrong model for the product Barn was actually becoming.

Configuration

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

This reference covers Barn 0.9.0. Check barn version when using another version.

Discovery

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

For plan, up, reload, and recreate, absence of a file falls back to the applied spec when a deployment exists. validate has no fallback. A configuration must be a regular non-symlink file no larger than 4 MiB. The first existing discovery candidate wins; if it is invalid, Barn reports the error instead of trying the next filename. Renaming a file or moving directories does not create another deployment; applied state lives in BARN_HOME.

Linux Quick Start

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

Create an Ubuntu 24.04 VM on your Mac or Linux host, then expand it into a lab. For macOS guests, use the separate Mac guide.

Before you start

Install Barn 0.9.0 and reserve at least 4 GiB of guest memory plus room for the host. Run these commands as your normal user in a terminal. Barn can prepare QEMU and the private network; host changes may require sudo.

Platforms and Limits

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

Barn is built for local development and testing. This page helps you choose a host and understand what each guest type supports.

Version

These docs cover Barn 0.9.0. Install the release, check barn version, and read the release notes for changes. The Linux image catalog updates independently with barn update.

Linux guests

Host	Architecture	Native acceleration	Minimum QEMU
macOS	arm64 (Apple Silicon), amd64 (Intel)	HVF	8.2.1
Linux	amd64, arm64	KVM	6.2

Barn builds for all four targets. The principal native test paths are macOS arm64 and Linux amd64; Intel macOS and Linux arm64 have narrower validation coverage. Linux also requires usable /dev/kvm and NetworkManager or systemd-networkd. barn doctor checks the host; barn setup --dry-run shows the dependency and network changes for your machine.

Why Every Barn Node Has Two NICs

Thu, 27 Aug 2026 20:00:00 +0800

This article describes Barn 0.9.0. The VM lifecycle and network design here apply to Linux guests; Mac machines are managed independently.

A Pigsty inventory names machines by stable addresses. PostgreSQL replication, etcd membership, HAProxy backends, VIPs, monitoring targets, and Ansible all assume that 10.10.10.11 continues to mean the same node. A loopback port forward can expose SSH or PostgreSQL to the host, but it cannot provide that network identity to peers.

CLI

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

This reference covers common options and Linux lab commands in Barn 0.9.0. For macOS guests, see Mac commands. Check barn version when using another version.

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

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

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

Bare barn prints a short welcome with next commands, exits 0, and exposes actions[] in JSON/YAML. A bare namespace such as barn image still exits 2 (human help in text mode, a structured usage error in JSON/YAML). Explicit --help always renders human help and exits 0. Use barn --version or barn version to inspect the build identity.

Design

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

Barn provides two workflows that share a CLI but keep their configuration and lifecycle separate.

	Linux labs	macOS guests
Virtualization	QEMU with HVF or KVM; TCG for selected compatibility cases	Apple Virtualization.framework
Desired state	A Pigsty-compatible YAML inventory	Named machines configured with `barn mac`
State directory	`~/.barn`	`~/.barn/mac`
Networking	Management NIC plus a fixed-IP lab subnet	One NAT subnet and DHCP reservation per machine
Typical work	Database clusters, Linux development and automation	macOS builds, desktop tools and isolated development

The sections below explain the Linux lab model. For the native macOS workflow, see macOS guests and the Mac reference.

macOS Virtual Machines

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

barn mac creates and runs macOS virtual machines on an Apple Silicon Mac. Each machine is a clean, disposable macOS with an administrator account, passwordless sudo, pinned SSH keys and a fixed address — for testing, building and reproducing macOS-specific behavior. It uses Apple’s Virtualization framework directly and needs no administrator access.

Mac machines are separate from the Linux lab. They never read barn.yml, never join a Pigsty inventory, and keep their files under $BARN_HOME/mac (default ~/.barn/mac). Linux destroy and purge leave them alone.

Mac Commands

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

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

barn mac requires Apple Silicon and macOS 27 or later, and runs as the logged-in user; it refuses to run as root. On other hosts the command is hidden, and commands that need the Mac component fail with mac_host_unsupported. Bare barn mac is barn mac ls.

Commands

Command	Purpose
`ls`	every machine with state, address, SSH, macOS, resources and shares; aliases `list`, `status`, `st`
`up [name]`	create the machine if needed, start it, wait for SSH and sudo
`start [name...]`	start existing machines
`stop [name...]`	shut down normally; power off after two minutes
`restart [name]`	stop, then start, applying configuration changes
`open [name]`	show the desktop, starting the machine first if needed
`ssh [name]`	interactive shell, or, after `--`, a command line for the guest shell
`exec [name] -- cmd`	run a command, keeping argument boundaries
`configure name`	change a machine’s settings
`recreate name`	replace the machine with a fresh macOS, keeping its settings
`destroy name...`	delete machines
`password [name]`	show or copy the login password
`ssh-config`	print, install or remove the OpenSSH entries
`logs [name]`	recent runtime log
`setup`	prepare the macOS base without creating a machine
`image ls`	restore images and bases with the machines using them; alias `list`
`image update`	prepare Apple’s newest macOS 27 as the default base
`image prune`	list, and with `--yes` delete, unused images
`doctor`	check the host, the component, the base and every machine

Flags by command

Command	Flags
`up`	`--cpu` `--memory` `--disk` `--user` `--share` `--clipboard` `--subnet` `--ipsw` `-y`/`--yes` `-n`/`--no-wait` `--open`
`start`	`--all` `-n`/`--no-wait` `--open` `--recovery`
`stop`	`--all` `--force`
`restart`	`-n`/`--no-wait` `--open`
`configure`	`--cpu` `--memory` `--share` `--unshare` `--clipboard` `--subnet`
`recreate`	`--update` `--force` `-n`/`--no-wait`
`destroy`	`--force`
`password`	`-c`/`--copy`
`ssh-config`	`-i`/`--install` `--remove`
`logs`	`-n`/`--lines` (default 100, at most 10000)
`setup`	`--ipsw` `--disk` `-y`/`--yes`
`image update`	`--ipsw` `-y`/`--yes`
`image prune`	`--installers` `-y`/`--yes`

A command without a machine name acts on the only machine, or on mac1; with several machines and none named mac1, it asks for a name. start and stop accept several names, or --all. destroy and recreate describe what they delete and ask for the command name to be typed; --force confirms without a terminal.

Declarative Does Not Mean Destructive

Thu, 27 Aug 2026 21:00:00 +0800

This article describes Barn 0.9.0. The VM lifecycle and network design here apply to Linux guests; Mac machines are managed independently.

“Declarative” is often shortened to “make reality equal the file.” That is a useful slogan until the file is incomplete, the wrong branch is checked out, or one YAML group is temporarily removed. If absence is treated as deletion, an ordinary editing mistake becomes a destructive operation.

Barn uses a narrower rule:

Contributing

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

Barn is an Apache-2.0 project. Contributions to the CLI, native macOS component, documentation, and image tooling are welcome.

Choose a repository

What you want to change	Where to work
CLI behavior, VM lifecycle, native macOS component, installer, packages	pgsty/barn
This website, tutorials, command reference, translations	pgsty/barn.pgsty.com
An image definition or normalization step	`packaging/image-repository/` and `packaging/image-pipeline/` in the Barn source repository

For a bug report, include barn version, the host OS and architecture, the command you ran, and the relevant error. Remove private keys, passwords, and other secrets from logs and inventories. Report security issues using the security policy.

Daily Operations

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

This guide covers Linux labs in Barn 0.9.0. For Mac machines, use the macOS guide.

Inspect and access

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

Applied state is under ~/.barn by default (BARN_HOME overrides it); these commands work from any directory. Changing the working directory does not create a separate deployment. Status shows images and resources; --verbose adds architecture, accelerator, SSH ports, and PID. TCG is marked in ordinary output, and a degraded node does not hide its peers. barn up rebuilds the default SSH aliases from the complete applied deployment after the selected VMs are started, so a scoped up never drops unselected peers and plain ssh meta just works; barn ssh-config --install rewrites it by hand if you ever need to. plan, up, reload, and recreate prefer -f, then a discovered inventory, then the applied spec when no file exists. validate always needs a file.

Images

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

Barn uses a materialized static-file catalog plus immutable qcow2 artifacts. Official and HTTP Catalogs are signed; explicitly selected local and HTTPS repositories may be unsigned. A catalog update does not require a new Barn binary, but the binary decides which signing keys and image safety rules are trusted.

Warning

EL7, EL9 9.3/9.6, and EL10 10.0 are deprecated compatibility images. All other built-in versions are supported.

Aliases and pull order

Barn 0.9.0 embeds catalog 2026093001: 9 families and 41 artifacts. el7 is amd64-only; every other family has amd64 and arm64 artifacts. EL9 includes 9.3, 9.6, 9.7, and 9.8; EL10 includes 10.0, 10.1, and 10.2. u24:stable (Ubuntu 24.04) on the native architecture is the default request.

A PID Is Not a Virtual Machine

Fri, 28 Aug 2026 10:00:00 +0800

This article describes Barn 0.9.0. The VM lifecycle and network design here apply to Linux guests; Mac machines are managed independently.

A pidfile answers one question: which integer did a process have when the file was written? It does not prove that the process is still alive, that the PID was not reused, that the executable is QEMU, or that this particular QEMU owns the node an operator wants to stop.

Image Pipeline

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

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

Run these commands from the Barn source checkout. Python 3 and qemu-img are required; offline additionally needs working virt-customize and virt-cat tools from libguestfs. These are build-host dependencies, separate from the dependencies that barn setup installs for running VMs.

Modes

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

Official candidate matrix

build-official.py wraps the same offline boundary for a fixed eight-target matrix: Debian 12/13 and Rocky Linux 8/9, each on amd64 and arm64. Every upstream qcow2, RPM/DEB input, release name, digest, and source epoch is pinned in official-v1.json.

Storage, Files, and Service Access

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

This guide uses the Barn 0.9.0 interface. Start with the Quick Start before running the guest-side checks. The examples use node meta and the default subnet; retain your actual names and addresses when adapting an existing inventory.

Choose disks before creating the VM

Every node has a 64 GiB root disk and, by default, one 128 GiB non-persistent data disk at /data. vm_disk sets the root disk size in GiB. vm_disks replaces the entire data-disk list; vm_disks: [] disables extra data disks.

repo.yaml Is Intent; catalog.json Is Evidence

Sat, 29 Aug 2026 19:00:00 +0800

This article describes Barn 0.9.0. The VM lifecycle and network design here apply to Linux guests; Mac machines are managed independently.

A static image repository sounds like a directory of qcow2 files plus a JSON index. The difficult part is deciding which facts a maintainer may write by hand and which facts must be derived from the bytes being published.

If checksums and sizes live in the hand-authored source, they are easy to copy incorrectly. If policy exists only in generated JSON, reviewing a channel change or deprecation requires reading machine output. Barn keeps the two jobs separate.

Image Repositories

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

Normal use needs no image command first: barn up resolves u24:stable for the native host architecture and pulls the resulting immutable version. Barn uses the catalog embedded in the installed build until you run barn update, which fetches, verifies, and activates the repository’s current catalog. Nothing refreshes it automatically; image sync explicitly activates an exact URL or file for recovery.

Choose an image

Inspect the available aliases:

Automation and Guest Scripts

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

These examples target the Barn 0.9.0. Run host commands as the Unix user who owns the deployment. Use the same inventory and BARN_HOME on every invocation; a new working directory does not create an independent lab.

Prepare a predictable lab

For a first lab, create and review the inventory before starting automation:

mkdir -p ~/barn-lab
cd ~/barn-lab
barn init dual
# Edit barn.yml before proceeding.
barn version
barn validate -f barn.yml
barn plan -f barn.yml
barn setup -f barn.yml --dry-run

Keep the selected inventory in version control. Set vm_image explicitly; use a version such as vm_image: u24@20260926.0.0 when new nodes must use the same base after a catalog update. Explicit -f also prevents first-run setup from automatically moving an untouched default template to another subnet.

Troubleshooting

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

This page covers Barn 0.9.0. Check barn version before applying version-specific guidance.

For macOS guests, use barn mac doctor and the Mac troubleshooting guide. The diagnostics below apply to Linux labs.

Start with diagnostics (status may reconcile interrupted runtime state):

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

Download and PATH problems

The installer uses GitHub Release assets; --mirror selects the Barn image repository and does not redirect installer downloads. If your network needs a proxy, set HTTPS_PROXY or ALL_PROXY in the terminal to your existing proxy’s address. A macOS system proxy setting alone does not configure these environment variables for command-line tools.

Build from Source

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

Use a source build to develop Barn, inspect a change, or build the native Mac component. For a packaged CLI, use installation.

Select the version

Clone the documented release:

git clone --branch v0.9.0 https://github.com/pgsty/barn.git
cd barn

For the development branch, omit --branch v0.9.0. Check git log -1 --oneline and git status --short to identify your source before comparing behavior.

Build the CLI

Barn 0.9.0 pins Go 1.27.1 in go.mod and packaging/toolchain.env. You also need Git, Make, Bash, and standard build tools. Compiling the CLI does not require QEMU or host-network setup.

Uninstall and Clean Up

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

Barn manages Linux and macOS machines separately. barn purge deletes only the Linux deployment; it does not remove Mac machines. Keep Barn installed until you have finished VM and host cleanup.

Choose what to remove

Goal	Operation
Free running resources, keep disks	`barn stop`; `barn mac stop --all` for Mac machines
Delete a Linux node	`barn destroy <node>`
Delete the Linux lab, keep persistent disks	`barn destroy`
Delete the Linux lab, including persistent disks and keys	`barn purge` — no confirmation
Delete named Mac machines	`barn mac destroy <name...>` — asks for confirmation

Use actual names from barn status and, if you use Mac guests, barn mac ls. Back up files you need before deleting machines.

Barn 0.9.0

Wed, 30 Sep 2026 00:00:00 +0800

Barn 0.9.0 brings Linux labs and native macOS machines into one command-line tool, with clearer diagnostics and recovery for interrupted operations.

Install 0.9.0 · Download assets · Full changelog

macOS machines on Apple Silicon

barn mac creates named macOS 27 machines with a desktop, SSH, shared folders, and text clipboard sharing. The first machine installs a base from Apple’s verified restore image; subsequent machines clone it with separate writable disks, credentials, and private subnets.