Bootstrap And Run Nodes
Native virtual machines for macOS and Linux.

Website · Quick Start · Documentation · Blog · Changelog · Contributing · Security · 中文

What is Barn?

Barn creates local virtual machines for development and testing:

• Linux labs on macOS and Linux. Describe up to 20 nodes in one Ansible-compatible YAML inventory. Barn starts QEMU VMs with fixed IPs, SSH access, and test data disks. Use the same inventory with Pigsty to deploy PostgreSQL and other services.
• macOS machines on Apple Silicon. barn mac creates named macOS 27 VMs with a native desktop, SSH, shared folders, and text clipboard sharing. Each machine has its own disk, credentials, and private subnet.

Linux uses QEMU with HVF on macOS or KVM on Linux. Mac guests use Apple's Virtualization framework. Barn runs on your hardware and works independently of Pigsty.

Install 0.9.0

macOS — Homebrew

brew install pgsty/infra/barn
barn version

Linux — download installer

The installer selects the native arm64 or amd64 archive, verifies it, and installs into ~/.local/bin without sudo:

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

Add the PATH line to your shell configuration when using the download installer. DEB/RPM packages and manual archives are also available; see installation for requirements and upgrades.

Start a Linux lab

barn up
barn ssh

On a first interactive run, with no inventory or existing deployment, up creates a one-node barn.yml, prepares host dependencies and networking, downloads the verified Ubuntu 24.04 image, and waits for SSH. It shows host changes and asks for administrator access when needed. Run exit to return from the guest to your host.

The default VM has 2 vCPUs, 4 GiB of memory, a 64 GiB root disk, and a 128 GiB test disk at /data. Disk files grow as data is written.

To choose the configuration before booting, use barn init and edit the file. barn init full generates four nodes. An existing Pigsty inventory works too:

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

Barn prepares the machines; installing Pigsty services is a separate step. Follow the Linux quick start.

Run a macOS VM

macOS guests require Apple Silicon, macOS 27 or later, and Barn Mac.app. The 0.9.0 release archives contain the CLI. Build the native component with Xcode 27 using the Mac guide, then run:

barn mac doctor
barn mac up
barn mac open
barn mac ssh

The first up asks before downloading Apple's restore image, verifies it, and installs a reusable base. Later machines clone that base with independent writable disks. Closing the desktop window keeps the VM running.

Name another machine with barn mac up dev --cpu 8 --memory 16G. Apple allows two macOS VMs running at a time per Mac, including other tools. Mac commands keep their state under ~/.barn/mac and do not read barn.yml. Linux destroy and purge leave Mac machines intact.

See the Mac guide for native-component installation, shared folders, desktop controls, and cleanup.

Everyday Linux commands

Task	Command
Inspect machines	barn status
Review inventory changes	barn plan
Create nodes or finish interrupted setup	barn up
Run a guest command	barn exec meta -- hostname
Stop / resume the lab	barn stop / barn start
Apply a changed VM definition	barn recreate meta
Delete a VM	barn destroy meta
Inspect available images	barn image list
Diagnose the host	barn doctor

Barn keeps one Linux deployment per user under ~/.barn. Changing directories does not create another lab. Removing a host from YAML does not delete its VM; destruction is explicit. Repeating up keeps healthy VMs running and retries unfinished setup. --json and --yaml provide structured output for scripts.

Use disposable test data. Recreate replaces root and non-persistent disks. During guest recovery, Barn may also reset an unrecognized or confirmed damaged data filesystem, including one marked persistent. Persistence controls retention across destroy/recreate, not backup or recovery of corrupt contents. See storage and access.

Documentation and help

• Guides — installation, daily operations, images, automation, and troubleshooting.
• Reference — configuration, Linux and Mac commands, output, and exit codes.
• Platforms and limits — host requirements and guest restrictions.
• Release notes — what's new in 0.9.0.
• Issues — bug reports and feature requests; use the security policy for vulnerabilities.

Use barn --help or barn <command> --help for the options in your installed version.

Contribute

make build     # build the CLI and matching hosts helper into ./bin
make test      # unit tests
make check     # complete source checks

make mac-build builds the native Mac bundle with Xcode 27 on Apple Silicon. See CONTRIBUTING.md for the development workflow, design rules, and release tooling. Documentation lives in barn.pgsty.com.

License

Barn is licensed under Apache-2.0. Archives and packages include the license texts for their Go dependencies.