Start on Barn

Quick Start

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

Install

This tutorial targets the Barn 0.9.0 release candidate. For now, build from source. The package and Homebrew commands below apply after 0.9.0 is published and the formula is updated; these links do not establish publication. See Status.

Barn has no compatibility layer for earlier development builds. It uses barn.yml, BARN_*, and fresh ~/.barn state, with no old command aliases or state migration. Stop internal old environments, preserve needed data, and create a fresh Barn installation. Renaming an old state directory is unsupported.

Daily Operations

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

This guide describes the Barn 0.9.0 release candidate. See Status for the publication and validation boundary.

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.

Troubleshooting

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

This page describes the Barn 0.9.0 release candidate. Check barn version before applying version-specific guidance.

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.

Automation and Guest Scripts

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

These examples target the Barn 0.9.0 release candidate. 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@20260911.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.

Storage, Files, and Service Access

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

This guide uses the Barn 0.9.0 release candidate 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.

macOS Virtual Machines

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

Important

Barn 0.9.0 release candidate; unreleased. This page describes the renamed barn mac, which uses fresh Barn state and provides no development-state migration. Earlier native records are retained in Status and do not establish the same acceptance for the renamed build. Check the barn mac --help of the binary you run.

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.

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:

Build from Source

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

Barn 0.9.0 is an unreleased candidate. Use this page to build and check a checkout containing the rename. Installation commands for the eventual release are in the Quick Start.

Choose the source

Use a checkout containing the Barn changes. Once that source is pushed to the public repository, it can also be cloned with:

git clone https://github.com/pgsty/barn.git
cd barn

Do not assume a v0.9.0 tag exists before publication. Check the source identity and working-tree changes first; go.mod must name github.com/pgsty/barn and the command source must live in cmd/barn:

Uninstall and Clean Up

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

This page deletes VMs and local data. Inspect the current state and stop if any Barn VM must remain:

barn st

1. Remove the deployment

Delete nodes, persistent disks, keys, and deployment state:

barn purge

This whole-deployment command asks for no confirmation. The image cache and host network remain. Use the granular, confirmed barn destroy command instead when preserving persistent disks or removing selected nodes.