Mac Commands

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

Flags by command

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.

Flag values

up refuses creation options that differ from an existing machine instead of ignoring them, and its next: line names the fix. CPUs, memory, shares, the subnet and the clipboard change with configure. The account and disk capacity are fixed for a machine’s lifetime, and recreate keeps them: other values need another machine. A different macOS comes from image update, then recreate --update.

Machines

• Names: 1–32 lowercase letters, digits and inner hyphens, starting with a letter: mac1, dev, build-2.
• Running limit: two macOS virtual machines per Mac, counting other tools and macOS installation. Barn never stops a machine to make room.
• Account: an administrator with passwordless sudo, SSH key login, desktop automatic login and Remote Login. SSH password login is disabled. The login password is random and stored in the machine’s password file.
• Guest names: the computer name is the machine name; the local host name is barn-<name>, so the guest answers as barn-<name>.local.
• Shares: one VirtioFS device mounted by macOS under /Volumes/My Shared Files/<name>. Shares must be existing directories, not symlinks, and change only while the machine is stopped.
• Clipboard: plain text, synchronized over the machine’s SSH connection when its window gains or loses focus; at most 1 MiB; items marked concealed are never sent.
• Stop: normal shutdown through macOS in the guest; if the machine is still running after two minutes it is powered off and the result carries "forced": true. --force powers off at once.

Networks

Each machine’s network is created by its own runner process when the machine starts and disappears when it stops. No daemon and no root is involved.

start refuses a subnet that a host route now overlaps, such as a VPN, with reason mac_subnet_in_use. SSH host keys are pinned to the machine instance, not its address, so configure --subnet keeps trust.

macOS Local Network privacy stops third-party programs from connecting to these networks unless their app is allowed under Privacy & Security → Local Network; the error is “No route to host”. Barn itself connects through Apple’s /usr/bin/nc and /usr/bin/ssh, which are exempt.

JSON output

Every command honors --json and --yaml. Progress goes to stderr.

ls

{
  "schema_version": 2,
  "root": "/Users/alice/.barn/mac",
  "prepared": true,
  "base": {"version": "27.0", "build": "26A428", "base_id": "26A428-e16af589f4b705ca397f5b21"},
  "machines": [
    {
      "name": "mac1",
      "kind": "macos",
      "state": "running",
      "ready": true,
      "ssh": "ready",
      "address": "10.10.20.10",
      "address_stable": true,
      "ssh_host": "10.10.20.10",
      "ssh_port": 22,
      "user": "alice",
      "image": {"version": "27.0", "build": "26A428", "base_id": "26A428-e16af589f4b705ca397f5b21"},
      "cpus": 4,
      "memory_bytes": 8589934592,
      "disk": {"capacity_bytes": 107374182400, "allocated_bytes": 1202647040},
      "network": {"subnet": "10.10.20.0/24", "gateway": "10.10.20.1", "address": "10.10.20.10"},
      "shares": [{"name": "src", "host": "/Users/alice/src", "guest": "/Volumes/My Shared Files/src", "readonly": false}],
      "clipboard": true,
      "pid": 2545,
      "instance_id": "b1482ffc-2da7-45d9-ace5-c5f3193a9172",
      "warnings": []
    }
  ],
  "running": 1,
  "limit": 2
}

Lifecycle results

up, restart, open, recreate and configure return one result; start, stop and destroy return {"machines": [...]}, one result per machine, even for a single name.

{"name": "mac1", "action": "created", "state": "running", "ready": true,
 "address": "10.10.20.10", "user": "alice", "version": "27.0", "build": "26A428"}

exec --json returns the same object as Linux barn exec --json: node is the machine name, and exit_code, stdout and stderr come from the guest. An interactive ssh has no JSON form.

Failures

Exit codes are the Barn CLI’s. A remote command’s own exit status passes through ssh and exec unchanged. JSON failures carry a stable reason and a next command:

Files

$BARN_HOME/mac/
  config.json                        installation identity and default base
  images/ipsw/<build>.ipsw(.json)    Apple restore images; .partial while downloading
  images/base/<id>/                  read-only, unbooted macOS bases
  slots/<name>/state.json            the machine record (schema 2)
  slots/<name>/disk.asif             copy-on-write disk layer over the base
  slots/<name>/machine-id.bin        Apple machine identifier
  slots/<name>/auxiliary-storage.bin boot storage
  slots/<name>/id_ed25519(.pub)      the machine's SSH key pair
  slots/<name>/known_hosts           the pinned host key, under barn-mac-<instance>
  slots/<name>/password              login password, mode 0600
  slots/<name>/runner.log            runtime log (barn mac logs)

Runtime sockets live in /tmp/barn-mac-<uid>-<hash>/. ssh-config writes ~/.ssh/barn-mac_config and one # barn-mac:include block in ~/.ssh/config, independent of the Linux # barn:include block. The desktop window positions are saved in ~/Library/Preferences/io.pgsty.barn.mac-runner.plist.

Inside the guest, Barn writes ~/.ssh/authorized_keys, /private/etc/sudoers.d/80-barn, /etc/ssh/sshd_config.d/000-barn.conf, the computer and local host names, and disables sleep with pmset.