Tart runs macOS and Linux VMs on Apple Silicon from the command line, and a macOS 27 guest answers commands about 30 seconds after tart run. It is the tool to pick when the VM has to be scripted: CI runners, agent sandboxes, a headless Mac mini.
You’ll install Tart from the openai/tools tap, boot macOS and Ubuntu guests, share a folder, grow a disk, hit the two-VM limit on purpose and boot a guest into Recovery. Everything below ran on an AWS EC2 mac-m4.metal host (Apple M4, 24 GB, macOS 27.0) in October 2026 with Tart 2.41.1 and softnet 0.25.0.
Pick Tart or UTM for the job
Tart is a CLI over Apple’s Virtualization.framework that stores VMs as OCI images you push and pull like containers. UTM is a GUI app that wraps the same framework plus QEMU, which is why it can emulate an x86 guest and Tart cannot. The split matters most on a headless Mac: in this guide’s earlier lab run, utmctl over SSH exited with code 133 and printed nothing, because UTM expects its app running in a logged-in desktop session. So the deciding question is who drives the VM.
- Pick Tart when scripts, CI jobs or agents start and throw away VMs over SSH.
- Pick UTM when you sit at the Mac, want a windowed desktop, or need an x86 guest.
- Pick Multipass when you only want an Ubuntu shell and do not care how it is built.
For the last case, the Multipass guide for Ubuntu VMs on macOS is the shorter path. Check Tart’s licence before you build a product on it. It ships under FSL-1.1-ALv2, which allows internal use such as your own CI or your own agents, but not a “Competing Use” that resells the same functionality. Each release turns into Apache 2.0 on its second anniversary, so a hosting business built on Tart today needs a lawyer, not a blog post.
Check your Mac against each feature
Any Apple Silicon Mac runs the Tart binary, but the Homebrew route and several features need a newer macOS than the binary does. Intel Macs can’t run Tart at all. Match your host against this table before you pick an install method:
| Feature | Host needs | Source |
|---|---|---|
| Tart binary (release tarball) | Apple Silicon, macOS 13 Ventura or later | openai/tools tart formula |
brew install openai/tools/tart | macOS 26 Tahoe or later (softnet dependency), plus brew trust on Homebrew 6 | softnet formula, lab run |
Shared folders (--dir) | macOS 13 host; macOS guests 13 or later | tart run --help |
VNC in Recovery (--vnc-experimental) | Any supported host | tart run --help, lab run |
| Headless macOS guests | A login.keychain on the host user | Tart FAQ, lab run |
| macOS guests at once | Two per Mac; Linux guests don’t count | Apple’s macOS licence, lab run |
The keychain and two-guest rows bite people most, and both have their own section below with the exact error. If you’re on macOS 13 to 15, skip Homebrew and use the tart.tar.gz asset from the openai/tart releases page instead. It unpacks to tart.app, and the binary to put on your PATH is tart.app/Contents/MacOS/tart, the same path the Homebrew formula wraps.
Install Tart from the openai/tools tap
The project moved to the openai organisation, and its formula lives in openai/homebrew-tools. The old cirruslabs/cli tap still exists but its tart formula stopped at 2.32.1, and the repo hasn’t been pushed since June 2026, so tutorials that print brew install cirruslabs/cli/tart leave you nine minor releases behind. Start with the install line the README gives:
brew install openai/tools/tart
On Homebrew 6 that first attempt fails. Homebrew trusts the formula you named but not the softnet dependency from the same third-party tap, so it refuses to load it and installs nothing:
==> Tapping openai/tools
Cloning into '/opt/homebrew/Library/Taps/openai/homebrew-tools'...
Tapped 1 cask and 5 formulae (29 files, 271.8KB).
==> Trusted formula openai/tools/tart
Error: Refusing to load formula openai/tools/softnet from untrusted tap openai/tools.
Run `brew trust --formula openai/tools/softnet` or `brew trust openai/tools` to trust it.
Trust the whole tap once, then run the install again. Trusting the tap rather than one formula saves you the same error on the next dependency it adds:
brew trust openai/tools
brew install openai/tools/tart
tart --version
The second run installs softnet first, then Tart, in about three seconds, and the version check should print the release you just pulled. The capture below is the full sequence on the M4 host, failure included:

If brew itself is not found over SSH, your non-login shell skipped /opt/homebrew/bin, so run eval "$(/opt/homebrew/bin/brew shellenv)" first. The DHCP caveat Tart prints after the install only matters when you create a couple of hundred VMs a day, because the 192.168.64.0/24 pool hands out 24-hour leases and runs dry before the old ones expire. A build farm should shorten the lease as the caveat says. A laptop running two guests can ignore it. If every brew install stalls on an update first, the guide to disable Homebrew auto update fixes that.
Pull a macOS 27 VM image
Cirrus Labs publishes ready-made images on GHCR, and the macOS 27 one is macos-golden-gate-base. It’s 32.8 GB compressed and expands to a 50 GB disk, so check that you have room before you pull. tart clone downloads the image into the OCI cache and makes a local VM from it in one step:
tart clone ghcr.io/cirruslabs/macos-golden-gate-base:latest tart-install-macos
On the EC2 host in eu-west-1 the pull took 4 minutes 52 seconds, and you should expect several times that on home broadband, so start it well before you need the VM. Every later clone of the same image comes from the cache as an APFS copy. That is why a later clone of the same image finished in 0.01 seconds with nothing to download. Read the VM’s settings before you boot it.
tart get tart-install-macos
The image defaults to 4 vCPUs and 8 GB of memory, and the disk uses Apple’s new asif sparse format, which is why it reports 39 GB on disk for a 50 GB drive:
OS CPU Memory Disk DiskFormat Size Display MACAddress State
darwin 4 8192 50 GB asif 39 GB 1024x768 a2:f4:9b:xx:xx:xx stopped
Change CPU or memory now with tart set if 8 GB is too much for your Mac. Two of these guests already take about 16.5 GB on a 24 GB host.
Run the macOS VM
On a Mac you’re sitting at, tart run tart-install-macos opens the guest in a window. Over SSH there’s no window to open, so start it with Virtualization.framework’s own VNC server and push it to the background, because tart run holds the terminal until the VM stops:
tart run tart-install-macos --vnc-experimental &
Tart prints a vnc:// URL with a one-time password and a local port. Open it in Screen Sharing on the Mac, or tunnel the port over SSH from another machine. If the VM must outlive your SSH session, start it from a detached subshell instead, (tart run tart-install-macos --vnc-experimental > ~/tart-run.log 2>&1 < /dev/null &), which is how the guests here stayed up over SSH (a plain nohup did not). The guest logs in as admin automatically and lands on the desktop, where Terminal confirms the build:

The guest reports macOS 27.2 build 26B123, newer than the 27.0 host, because the image ships its own OS and does not track the host. Look at the df line too. Only 5.8 GB of the 41 GB root volume is free on the stock image, so an Xcode install or a large toolchain fails with a full disk unless you grow it first. The disk step further down handles that in one command and a reboot.
Error: “Failed to create new HostKey” on a headless Mac
The first tart run on the EC2 host died at once with VZErrorDomain Code=-9 "The virtual machine encountered a security error", and the real cause sat three errors deep: “Failed to create new HostKey”. Virtualization.framework stores a host key in the user’s login keychain, and a Mac nobody has logged in to through the GUI has no login keychain at all. Reinstalling Tart changes nothing. The fix takes four security calls:
- Create a keychain named
login.keychain. - Unlock it for this session.
- Make it the default keychain.
- Put it on the user’s search list.
Run them as the user that runs tart:
security create-keychain -p "" login.keychain
security unlock-keychain -p "" login.keychain
security default-keychain -s login.keychain
security list-keychains -d user -s login.keychain
An empty password is fine on a single-user build host, because the keychain only exists to hold the VM host key. Use a real one with -p if other people can log in as that account, since they could otherwise read anything else that lands in it later. Afterwards, security default-keychain should point at login.keychain-db in your home folder.

With the keychain in place, the same tart run came up and tart exec answered 29 seconds later. Linux guests never hit this error, since only macOS guests need the host key.
Run an Ubuntu ARM guest
Linux guests are smaller and faster to fetch. The Cirrus Labs Ubuntu image is 3.1 GB compressed and pulled in 32 seconds. Its root partition grows to fill the disk at boot, so set the size before you start it and there’s nothing to do inside the guest:
- Clone the image into a local VM with
tart clone. - Set CPU, memory and disk with
tart setwhile it’s stopped. - Confirm the new values with
tart get.
tart clone ghcr.io/cirruslabs/ubuntu:latest tart-install-ubuntu
tart set tart-install-ubuntu --cpu 2 --memory 2048 --disk-size 40
tart get tart-install-ubuntu
The tart list in the capture shows two kinds of entry. local rows are your VMs, while OCI rows are the cached image you can clone again without downloading. Clear old cache entries with tart prune --entries=caches --older-than=7 when disk runs short. A bare tart prune fails with “at least one pruning criteria must be specified”.

The disk went from 20 GB to 40 GB with no output, which is normal for tart set. Disks only grow, though. Tart refuses a smaller --disk-size so it never truncates a filesystem, which means an oversized disk on a small SSD stays oversized until you delete the VM and clone it again. Size it for the job in front of you, not for a job you might run someday.
Connect over SSH and share a folder
Start the Ubuntu guest with a host folder attached. The share: prefix names the folder inside the guest, which keeps the path readable when you attach more than one:
mkdir -p ~/vm-share
tart run tart-install-ubuntu --no-graphics --dir=share:$HOME/vm-share &
Guests sit on a 192.168.64.0/24 NAT network behind the Mac. tart ip asks the DHCP server for the address, and --wait keeps it polling while the guest boots instead of failing on the first try. The Cirrus Labs images use admin with password admin, so change it before the VM holds anything you care about:
ssh admin@$(tart ip tart-install-ubuntu --wait 60)
Linux doesn’t mount the share for you. Inside the guest, mount the virtiofs tag Tart uses by default, and every --dir appears as a subfolder under the mount point:
sudo mkdir -p /mnt/shared
sudo mount -t virtiofs com.apple.virtio-fs.automount /mnt/shared
ls -l /mnt/shared/share
You don’t even need SSH for one-off commands. tart exec runs them through the guest agent the images ship with, and that’s how the mount and the checks below were done from the host:

The share is read-write both ways, so a file the guest wrote showed up in the host folder owned by the Mac user. That suits build artefacts, but it is risky for a sandboxed agent, because anything running in the guest can then change files on your Mac. Append :ro to the --dir value when the guest should only read. The guest’s own console tells the same story, seen here over --vnc-experimental.

The root filesystem reads 36G, so the 40 GB from tart set landed on first boot without a manual growpart. To mount the share on every boot, add the same virtiofs line to /etc/fstab.
Grow a macOS VM disk
The 5.8 GB free on the stock macOS image fills fast. The Golden Gate base image extends its APFS container on startup, so the whole job happens from the host:
- Stop the VM, since
tart setonly changes a stopped guest. - Raise the disk with
--disk-size. - Boot it again and let macOS grow the container.
There’s no diskutil step inside the guest for this image.
tart stop tart-install-macos
tart set tart-install-macos --disk-size 80
tart run tart-install-macos --no-graphics &
Check the result from the host with tart exec. The root volume should report far more free space, and the APFS container should sit just under the new disk size:

Free space went from 5.8 GiB to 34 GiB, and the container grew to 74.1 GB with the 5.4 GB Recovery container still after it. A macOS image you build yourself may not resize on its own; the Tart FAQ covers the manual diskutil route for those.
Hit the two-VM limit on purpose
Apple’s macOS licence allows two macOS guests per Mac, and Virtualization.framework enforces it. Plan CI capacity around that number, because a third macOS job fails instead of queuing. To see the error yourself, keep tart-install-macos and the Ubuntu guest running, start a second macOS guest from the cache, then try a third:
tart clone ghcr.io/cirruslabs/macos-golden-gate-base:latest tart-install-macos2
tart run tart-install-macos2 --no-graphics &
tart clone ghcr.io/cirruslabs/macos-golden-gate-base:latest tart-install-macos3
tart run tart-install-macos3 --no-graphics
The third macOS guest exits with status 1 straight away. The message lists every running VM, the Linux one included, even though it doesn’t count against the limit:
The number of VMs exceeds the system limit (other running VMs: tart-install-macos, tart-install-ubuntu, tart-install-macos2)
Memory sets a second ceiling. top on the host shows each 8 GB macOS guest holding about 8.2 GB, while the 2 GB Ubuntu guest used 729 MB:

So a 24 GB Mac fits two default macOS guests plus a small Linux one, and the limit you hit first depends on the memory you gave each guest. If you need more macOS parallelism, it takes more Macs, not more RAM. Machines sized for this kind of work are compared in the Mac mini guide for AI agents.
Boot a Tart VM into Recovery
Recovery is where you change SIP, reinstall macOS or run Disk Utility on the guest’s own disk. Stop the VM first, then pair --recovery with --vnc-experimental, because plain --vnc uses the guest’s Screen Sharing and that service doesn’t exist in Recovery:
tart stop tart-install-macos
tart run tart-install-macos --recovery --vnc-experimental &
The guest stops at the startup options screen rather than going straight into Recovery. Get past it in two clicks:
- Click Options, the gear, not Macintosh HD.
- Click Continue, which only appears once Options is selected.

recoveryOS was already up in the first capture, taken 20 seconds after Continue, and didn’t ask for a password at this stage. It offers the usual four tools, with the reinstall entry naming the guest’s own macOS 27 release:

Terminal hides under the Utilities menu in the menu bar, not in that list. Open it and check SIP before changing anything:
csrutil status
That check saved a reboot here. The Cirrus Labs base image already ships with SIP off, and tart exec tart-install-macos csrutil status on the running guest said the same. csrutil disable still asks for the admin password and confirms. Keep that step for a VM you built from an IPSW, because a fresh install starts with SIP on.

Run tart stop on the host, then start the guest normally. If your CI depends on SIP being on, run csrutil enable in the same Terminal instead, since the base image won’t have it.
Clean up VMs and the image cache
Each macOS VM keeps around 39 GB on disk and the OCI cache holds another copy of the image, so a few test runs fill a 256 GB SSD faster than you would expect. Stop and delete what you are done with, then prune the cache. tart prune only removes cached images by default, so it never touches a VM unless you pass --entries=vms.
tart stop tart-install-macos
tart stop tart-install-macos2
tart stop tart-install-ubuntu
tart delete tart-install-macos
tart delete tart-install-macos2
tart delete tart-install-macos3
tart delete tart-install-ubuntu
tart prune --entries=caches --older-than=7
Run tart list afterwards. Your VMs drop off the list, while the OCI rows stay until a week passes without a clone from them, which saves a 33 GB pull if you rebuild the same VM tomorrow. If you also run macOS guests under KVM on Linux, the macOS on KVM guide and macOS on Proxmox VE walkthrough cover the non-Apple-hardware side, with the licence caveats that come with it.
Tart command reference
These are the commands this guide ran, grouped by what you’ll reach for:
| Task | Command |
|---|---|
| Install | brew trust openai/tools && brew install openai/tools/tart |
| Pull and create a VM | tart clone ghcr.io/cirruslabs/ubuntu:latest NAME |
| Resize | tart set NAME --cpu 2 --memory 2048 --disk-size 40 |
| Run headless | tart run NAME --no-graphics & |
| Run with VNC | tart run NAME --vnc-experimental & |
| Share a folder | tart run NAME --dir=share:$HOME/vm-share |
| Get the IP | tart ip NAME --wait 60 |
| Run a command, no SSH | tart exec NAME uname -a |
| Boot Recovery | tart run NAME --recovery --vnc-experimental |
| Stop, delete, prune | tart stop NAME, tart delete NAME, tart prune --entries=caches --older-than=7 |
Swap NAME for your VM and the table covers a day of Tart work. The --dir share only mounts by itself in macOS guests, so on Linux keep the virtiofs mount line from the shared folder step next to it.