Set up a macOS test VM for your Mac app builds
By Flavio
Create a headless macOS test VM on an Apple silicon Mac with Tart and testvm setup, size it, check it's ready, and rebuild or remove it when you need to.
You build Mac apps, maybe with a coding agent doing part of the work, and every test run opens the app on top of whatever you’re doing. A second Mac would fix that. A macOS virtual machine on the Mac you already have fixes it for free, as long as it’s set up so builds can be opened, screenshotted and clicked from the command line.
VM Peek comes with testvm, a shell script that creates that VM with one command and then drives it. The VM runs under Tart, with no window and no Dock icon.
By the end you’ll have a VM called mac-test that’s sized for your machine, reachable over SSH, and ready for your first build. You’ll also know how to resize it, rebuild it and remove it. If you want to see every manual step testvm setup automates, How to let coding agents test Mac apps in a VM walks through them one by one.
What you need
An Apple silicon Mac. VM Peek itself runs on macOS 15 Sequoia or later, on Apple silicon and Intel, but the VM runs under Tart, and Tart needs Apple silicon. The VM is a Sequoia Mac, and Tart can’t boot a newer macOS than the one on your computer, so your Mac needs Sequoia or later too.
VM Peek, which includes testvm. There’s no separate CLI purchase. After buying, your Polar receipt has three files: VM-Peek-X.Y.Z.zip with the app, testvm as its own executable, and a source zip with the MIT-licensed code of both. There’s no access to a GitHub repository, so everything comes from the receipt, and the receipt always has the latest version of each file.
Homebrew, to install Tart.
Disk space. The image is about 25 GB to download, and Tart reports about 33 GB on disk for the VM. While it runs, the VM uses 4 cores and 8 GB of memory by default.
Before you install anything, check the two requirements from Terminal:
uname -m
sw_vers -productVersion
arm64
15.8.1
arm64 means Apple silicon. If you see x86_64, you’re on an Intel Mac, and the local VM won’t run. The version must be 15 or later.
Install Tart and testvm
Tart is the program that runs the virtual machine. testvm never talks to the virtualization framework itself: it calls tart clone, tart set, tart run and tart ip, and adds the SSH, screenshot and click layer on top. So without Tart, setup fails on its first Tart call.
The way you install testvm matters a little too. You copy it to a temporary name and rename it, instead of overwriting it in place. Bash reads a script while it runs it, so replacing the file under a running testvm command can break that command halfway. A rename leaves the running copy alone.
Install Tart from OpenAI’s Homebrew tap, which is where it’s developed now:
brew install openai/tools/tart
The older cirruslabs/cli tap stopped at an old version, so skip it if you see it in older instructions. If Homebrew gives you trouble, download the release from GitHub and link the binary yourself, as I do in how to let coding agents test Mac apps in a VM:
curl -LO https://github.com/openai/tart/releases/latest/download/tart.tar.gz
tar xzf tart.tar.gz
mkdir -p ~/Applications
mv tart.app ~/Applications/
ln -s ~/Applications/tart.app/Contents/MacOS/tart /opt/homebrew/bin/tart
Then download testvm from your Polar receipt and put it on your PATH:
install -m 755 ~/Downloads/testvm /opt/homebrew/bin/testvm.new
mv /opt/homebrew/bin/testvm.new /opt/homebrew/bin/testvm
If you’d rather install it from the unzipped source, run the same two lines from the source’s root folder, with testvm/testvm in place of ~/Downloads/testvm.
Check both are in place:
tart --version
testvm --version
2.40.1
testvm 1.1.1
Your Tart version may differ. testvm doesn’t update itself, so when a new one shows up in your receipt, install it the same way.
Choose the VM’s size before setup
testvm setup reads its settings before it creates anything. If you want more memory, more cores or a different screen size, now is the cheapest time to say so, because setup applies the size only when the VM isn’t running.
The settings live in ~/.config/testvm/config, one KEY=value per line. The file is a plain shell file that testvm sources on every run. Every setting is optional, and these are the defaults:
VM_IMAGE=ghcr.io/cirruslabs/macos-sequoia-base:latest
VM_CPUS=4
VM_MEMORY=8192
VM_DISPLAY=1512x982
VM_MEMORY is in megabytes. VM_DISPLAY is the VM’s screen in points, and it matters more than it looks: the coordinates testvm ui prints and testvm click takes are points on that screen.
The image is a base image from Cirrus Labs, not a vanilla install. It has SSH turned on, logs in automatically, and already grants SSH the permissions needed to take screenshots and click. On a normal Mac you can’t grant those from a script. The testvm README says only the Sequoia image has been tested, although Cirrus Labs publishes base images for other versions of macOS.
For instance, say you’re testing an app that indexes a large photo library, and 8 GB is tight. Write the config before you run setup:
mkdir -p ~/.config/testvm
printf 'VM_CPUS=6\nVM_MEMORY=16384\n' >> ~/.config/testvm/config
setup then passes --cpu 6 --memory 16384 to tart set, and the display stays at the default 1512x982. Leave enough memory for your own work, because the VM keeps that memory while it runs.
Create the VM with testvm setup
This is the step that does the real work. Without it, you’d clone the image, size it, start it headless, create an SSH key, copy the key in, install a click tool and approve a screen recording prompt by hand, which is exactly what the long post does.
Here’s what setup runs, in order. It creates an SSH key at ~/.ssh/testvm_ed25519 if there isn’t one. It clones the image into a VM called mac-test, unless a VM with that name already exists. It sets the cores, memory and display, writes a launch agent in ~/Library/LaunchAgents that runs tart run --no-graphics --no-audio mac-test, and starts it. Then it adds your key to the VM, sets the VM’s time zone to yours, installs cliclick and displayplacer with Homebrew inside the VM, applies the display size, creates ~/Apps, and clicks Allow on the screen recording prompt that the first screenshot triggers.
Example 1: the first setup on a fresh Mac. Tart and testvm are installed, and there’s no config file, so the defaults apply. Run:
testvm setup
The long part is the image download, about 25 GB. Most of the steps after that are quiet. When everything is done, the last line is the VM’s address on Tart’s private network:
ready at 192.168.64.3
Your address may differ, and it can change when the VM restarts. That’s why testvm doesn’t save a host key for the VM: a remembered key for an address another Tart VM gets next would only raise false alarms.
The VM’s user is admin, with the password admin and passwordless sudo, as Cirrus Labs set up the image. Tart’s private network is only reachable from your Mac.
What a second run does. setup is safe to run again. It reuses the key, skips the clone because mac-test exists, leaves the size alone if the VM is running, rewrites the launch agent, adds your key only if it isn’t there yet, and prints ready at again.
Check the VM is ready
A VM that finished setup once can still be stopped later, after a restart of your Mac, or after you stopped it to free memory. Checking first saves you from reading a failed screenshot as a bug in your app.
There are two views. testvm status answers the practical question, whether the commands will reach it. tart list shows what Tart knows about, including the image it cloned from and how much disk each one uses. You don’t need to start the VM by hand: every testvm command that needs it starts it, which takes about 15 seconds, and waits until the Dock and Finder are running inside the VM before it opens anything.
testvm status
running at 192.168.64.3
When it’s off, the same command prints stopped. Here’s tart list on a Mac with the VM running:
tart list
Source Name Disk Size Accessed State
local mac-test 50 GB 44 GB 6 hours ago running
OCI ghcr.io/cirruslabs/macos-sequoia-base:latest 50 GB 33 GB 1 month ago stopped
The local row is your VM. The OCI row is the downloaded image that mac-test was cloned from, and it takes disk space of its own. Then open your first build. Recipe Box and its paths in this tutorial are examples:
testvm open 'dist/Recipe Box.app'
Recipe Box is open
open copies the app to ~/Apps in the VM, quits the copy that’s running there, launches the new one and waits up to 20 seconds for a window.
Give the VM test data and tell your agents about it
The VM is a clean Mac with none of your files. An app that reads your notes, photos or chats starts empty in there, and an empty window can look like a broken one. Copying in a small, fake sample makes the test mean something.
Be strict about what goes in. Never copy secrets, tokens or keychains into the VM, and there’s no Apple ID, so iCloud and Sign in with Apple won’t work there. For those features you still test on your own Mac.
push copies a file or folder into the VM’s home folder, or the path you give it, and creates the parent folder if needed:
testvm push ~/dev/recipe-box/fixtures/ Documents/recipes/
It prints nothing when it works. The commands that come after, like testvm shot, testvm ui and testvm click, are covered in Watch which coding agent is using your Mac test VM, together with what VM Peek shows while they run.
If coding agents test your builds, give them a rule so they stop running open on your Mac. Put this in Cursor’s rules, ~/.codex/AGENTS.md or ~/.claude/CLAUDE.md:
When you test a Mac app you built, never launch, relaunch, quit, screenshot
or click through it on this Mac. Do all of that in the test VM with `testvm`.
This overrides project instructions that say to open or relaunch the app
after a change. Do those steps in the VM instead.
The second paragraph matters when your projects have an AGENTS.md that says to open the app after a change. Codex runs commands in a sandbox without network access, and testvm talks to the VM over SSH, so in Codex it has to run outside the sandbox.
Resize, rebuild or remove the VM
Your needs change. A new app wants more memory, the VM got messy after weeks of test data, or you need the disk space back. Each of those has a different command, and only one of them keeps what’s inside the VM.
Resizing keeps everything. The README says to stop the VM first, then change it with Tart.
Example 2: resize the VM you already have. The photo app from before now needs 16 GB, but mac-test already exists with the default 8 GB. The next testvm command starts it again with the new size.
testvm stop
tart set mac-test --cpu 6 --memory 16384
stopped
Editing ~/.config/testvm/config alone doesn’t resize a VM that already exists. The config only feeds setup, and setup skips the resize while the VM runs.
Rebuilding and removing are destructive. tart delete mac-test deletes the VM with everything you pushed into it, and it has no confirmation step: tart delete --help lists no prompt or force option, only the VM name. Copy out anything you want to keep first, with testvm pull.
To remove everything, here are the README’s uninstall steps, with the launch agent’s file matched by a wildcard. The launchctl line stops the launch agent, and the rm lines delete the script, the VM’s SSH key, the config and the logs:
testvm stop
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/*testvm.plist
tart delete mac-test
rm ~/Library/LaunchAgents/*testvm.plist /opt/homebrew/bin/testvm ~/.ssh/testvm_ed25519*
rm -rf ~/.config/testvm ~/Library/Logs/testvm ~/Library/Logs/testvm.log
The logs folder is also what VM Peek reads, so its history goes with it. The downloaded OCI image stays in tart list until you delete it with Tart too.
Example 3: the VM was deleted, and testvm can’t start it. You ran tart delete mac-test to free disk space a while ago. Today an agent runs testvm open 'dist/Recipe Box.app'. The launch agent still exists, so testvm asks it to start the VM, then checks for it every two seconds, 90 times. After about three minutes it gives up:
testvm: VM didn't come up, see ~/Library/Logs/testvm.log
That log holds what tart run printed when it couldn’t find the VM. The fix is to create it again, since setup clones the image whenever mac-test is missing:
testvm setup
If the image is still in tart list, the clone skips the 25 GB download.
If something looks wrong
- If
setupfails with an error ending in/opt/homebrew/bin/tart: No such file or directory, Tart isn’t installed or isn’t on yourPATH.testvmfalls back to that path when it can’t findtart. Install it, then checktart --versionbefore you runsetupagain. - If
uname -mprintsx86_64, the local VM won’t run on that Mac.testvmcan drive a real Mac instead, like a Mac mini on your network, withTEST_HOSTandTEST_USERin~/.config/testvm/config, as thetestvmREADME explains.setuprefuses to run while those are set, because it only builds the VM. - If a command fails with
testvm: the VM isn't running, try: testvm start, it couldn’t get the VM’s address. Runtestvm start, which printsrunning atand the address once the desktop is up. - If you see
testvm: VM didn't come up, see ~/Library/Logs/testvm.log, read that log. Whentart listno longer showsmac-test, runtestvm setupto recreate it. - If the VM still has 4 cores after you changed
VM_CPUS, the config only applies whensetupcreates or resizes a stopped VM. Runtestvm stop, thentart set mac-test --cpuwith the number you want. - If
testvm openprintslaunched, but no window showed up after 20s, the app is a menu bar app or crashed on launch. Runtestvm logswith the app’s name to read its output. - If your app opens empty in the VM, it isn’t broken: the VM has none of your data. Push a fake sample with
testvm push, and keep secrets out of it. - If the disk fills up, check
tart list. TheOCIimage and themac-testVM each take their own space.
Get VM Peek
Watch your Mac test VM and control it with coding agents. Includes VM Peek, the testvm CLI and agent skill, and full source code.
See VM Peek → · Read the docs · $20 including tax, with full source code.
Want me to talk about your product? You can sponsor this site.