byre/docs/clean-install-vm.md

Testing a clean install in a macOS VM

A tart VM on the Mac byre runs on gives a fresh Mac in seconds, to install byre on as a new user would. tart list shows the VMs there.

The base VM

byre-base is a stopped VM left as just set up, kept in ~/.tart/vms/ (outside any checkout), and never run or installed into. Tests run on clones of it. It has:

• the macOS that tart create --from-ipsw latest installed (the newest the host supports; tart get byre-base and sw_vers inside show it), 4 CPUs, 8 GB of memory and an 80 GB disk;
• one account, admin with password admin, signed in automatically at boot, with passwordless sudo, the host user's ~/.ssh/id_ed25519.pub in authorized_keys, Remote Login on, and sleep and screen lock off;
• no Apple Account, FileVault, Siri, Location Services or analytics, and macOS updates that download without installing;
• nothing else: no Homebrew, Command Line Tools, Tailscale or byre.

Testing

tart clone byre-base byre-test
tart run byre-test

Run tart run in the task's terminal: it keeps running while the VM is up, and the VM's screen opens as a tart window. tart ip byre-test prints the VM's address once it has booted; ssh admin@<ip> gets in. tart delete byre-test throws the clone away. A clone is a copy-on-write copy, so it takes seconds and little disk. Apple's license allows two macOS VMs running at once per Mac, and other tasks may be running one.

To install a build, copy ~/byre-deploy/byre.dmg (or a mac/bundle.sh build) in and put Byre.app in /Applications there. Copy an app bundle as a zip (ditto -c -k --keepParent on the host, ditto -x -k in the VM), since scp -r fails on the symlinks in its frameworks. Open apps in the VM's GUI session from SSH with sudo launchctl asuser 501 sudo -u admin open /Applications/Byre.app.

The app's Tailscale sign-in opens Safari in the VM. To have the human approve it from their own Mac, read the address over SSH (sudo launchctl asuser 501 sudo -u admin osascript -e 'tell application "Safari" to get URL of front document', which asks once in the VM for Automation of Safari) and open the https://login.tailscale.com/a/<code> it names with show_page on the human's Mac.

Driving the VM's screen

• Start each act with a click on an empty part of the VM's screen, not its title bar: the VM takes clicks and keys only after a click inside it.
• tart run in a terminal runs until the VM stops, and Ctrl-C in that terminal shuts the VM down.
• screencapture over SSH fails for lack of Screen Recording in the VM; capture the tart window from the host with hands.
• Check screen_list before acting: another task's tart window can sit exactly on top of yours.

Rebuilding the base

Only when it needs a newer macOS. tart create --from-ipsw latest --disk-size 80 byre-base downloads the restore image (about 15 GB, cached in ~/.tart/cache/IPSWs/) and installs it; tart set byre-base --cpu 4 --memory 8192. Run it and click through Setup Assistant: "Set up as new", account admin/admin, skip the Apple Account ("Sign in Later in Settings"), and decline everything else. Then turn on Remote Login from the VM's Terminal:

sudo launchctl enable system/com.openssh.sshd; sudo launchctl bootstrap system /System/Library/LaunchDaemons/ssh.plist

and over SSH from the host (ssh-copy-id admin@<ip>, then):

echo 'admin ALL=(ALL) NOPASSWD: ALL' | sudo tee /etc/sudoers.d/admin
sudo chmod 440 /etc/sudoers.d/admin
sudo launchctl asuser 501 sudo sysadminctl -autologin set -userName admin -password admin
sudo pmset -a sleep 0 displaysleep 0
sudo shutdown -h now

sysadminctl -autologin fails with error 22 when run over SSH outside the GUI session, hence launchctl asuser.

tart itself is installed from its GitHub release (gh release download --repo cirruslabs/tart, unpacked to ~/Applications/tart.app, with ~/bin/tart linked to tart.app/Contents/MacOS/tart), since the Homebrew formula in cirruslabs/cli fails on current Homebrew.