macOS and Linux VMs on Apple Silicon with tart and SaltStack
How to automate tart VM lifecycle on Apple Silicon Mac Minis using SaltStack — install, clone OCI images, set resources, and keep VMs alive with launchd. Covers both macOS Sonoma and Ubuntu VMs for testing the kri fleet platform without touching production nodes.
🖥️
**hellodk**
hellodk.io · Deepak Gupta
27 May 2026
·
9 min read
tart
SaltStack
Apple Silicon
On This Page
**The Problem**Why VMs, not physical Macs
**Why tart**OCI images, Apple Virtualization
**Architecture**Host → VM → Salt → kri
**Salt State Walkthrough**init.sls explained
**The Plist**launchd daemon template
**The Pillar**VM configuration
**How to Apply**Exact commands
**Tearing Down**remove.sls
**What's Next**kri nodes, E2E tests
Stack
VM Images
OCI
ghcr.io/cirruslabs
Host Requirement
M1+
macOS 13 minimum
Salt States
2
init.sls + remove.sls
VM Types
2
macOS Sonoma + Ubuntu
-
Infrastructure · macOS · SaltStack
macOS and Linux VMs on Apple Silicon
with tart and SaltStack
I manage a small fleet of Apple Silicon Mac Minis that run iOS CI/CD pipelines. To test the fleet management platform — kri — without touching production nodes, I built Salt states that provision and maintain tart VMs: install tart via Homebrew, clone OCI images, set CPU/memory/disk, and wire up launchd daemons so VMs survive reboots automatically. Here's the exact implementation.
27 May 2026
9 min read
hellodk
macOS image size
~20 GB
Sonoma base, first pull
Linux image size
~2 GB
cirruslabs/ubuntu:latest
Salt states
4
tap, install, clone, service
Clone timeout
3600s
macOS images on slow links
TL;DR — Four sentences
**tart** uses Apple's native `Virtualization.framework` to run both macOS and Linux VMs as OCI images on Apple Silicon — CLI-first, no GUI overhead.
- The Salt state **installs tart via Homebrew, clones each VM from ghcr.io/cirruslabs, sets per-VM CPU/memory/disk, and drops a launchd plist** into `/Library/LaunchDaemons/` so VMs start at boot and restart on crash.
- VM configuration lives in pillar — flip **`enabled: false`** to keep a VM defined but dormant; flip to `true` and re-apply to spin it up on demand.
- Tear everything down with **`salt 'mm1' state.apply tart.remove`** — unloads launchd, stops VMs, deletes disk images, removes plists — no residue on the host.
① The Problem — Physical Macs Are Not Disposable
The Mac Minis in the fleet are busy. They run Xcode, Fastlane, the kri Salt minion, and a rotating set of iOS jobs. Testing a new kri feature directly on them means interrupting real CI runs, potentially corrupting minion state, and — if something goes wrong — leaving a Mac in a broken configuration that takes time to diagnose and clean up.
I needed isolated, disposable test nodes that look like Mac Minis to kri's Salt master but don't share any state with the production machines. VMs are the right answer: spin one up, run your tests, tear it down. If the minion config is wrong, delete the VM and clone a fresh one.
The two constraints that shaped the choice:
- **Must run on Apple Silicon.** The fleet is M1/M2 Mac Minis. x86 hypervisors don't exist here. Any VM solution has to use Apple's own virtualisation stack.
- **Must be automatable via Salt.** The whole point of kri is Salt-driven fleet management — the VMs themselves need to be provisioned the same way.
② Why tart
**tart** is a virtualisation tool from Cirrus Labs that sits on top of Apple's `Virtualization.framework` — the same framework that powers the macOS Ventura+ Virtualisation UI. It has three properties that make it exactly right for this use case.
Reason 1
Native framework
Virtualization.framework is Apple's own supported API. No kernel extensions, no third-party hypervisor, no compatibility layer. Performance is close to bare metal for CPU-bound workloads.
Reason 2
OCI images
VM images are pushed to and pulled from OCI registries — the same infrastructure as Docker images. Cirrus Labs publishes ready-made macOS and Linux images on ghcr.io. No manual ISO setup.
Reason 3
CLI-first
Every tart operation — clone, run, stop, delete, set — is a single shell command. That makes it trivially automatable from Salt's `cmd.run` states with standard idempotency guards.
Reason 4
Both OS types
The same toolchain handles macOS Sonoma and Ubuntu side by side. One Salt state covers both. kri tests run against whichever OS mix the pillar defines.
**Prerequisite:** tart requires Apple Silicon (M1 or later) and macOS 13 Ventura or newer. It will not run on Intel Macs or older macOS versions. The Virtualization.framework APIs it depends on were introduced in macOS 12 but the nested virtualisation required for macOS guests landed in macOS 13.
③ Architecture
The setup has three layers: the physical Mac Mini host, the tart VMs running on it, and the Salt master that pushes states to everything. launchd acts as the process supervisor that keeps VMs alive between Salt runs.
-
Architecture — Salt master pushes states to Mac Mini host; tart VMs register as kri nodes
Salt Master
kri stack
state.apply tart
tart.sls pillar
pushes to minions
ZeroMQ
Mac Mini Host (mm1) — Apple Silicon M2
/opt/homebrew/bin/tart · launchd · Salt Minion
launchd — /Library/LaunchDaemons/
macOS Sonoma VM
kri-test-macos-1
4 vCPU · 8192 MB · 60 GB
com.tart.kri-test-macos-1
Salt Minion inside
registers as kri node
Ubuntu VM
kri-test-linux-1
2 vCPU · 4096 MB · 20 GB
com.tart.kri-test-linux-1
Salt Minion inside
registers as kri node
ghcr.io/cirruslabs
macos-sonoma-base
ubuntu:latest
tart clone
kri Platform
Fleet Management
VM nodes = kri nodes
E2E tests → VMs
physical Macs untouched
register
KeepAlive: true — launchd restarts VMs on unexpected exit
Salt state push (ZeroMQ)
OCI image pull (tart clone)
macOS Sonoma VM
Ubuntu VM
launchd supervision
The Mac Mini runs a Salt minion as usual. When `state.apply tart` runs, it installs tart, clones the VM images from ghcr.io, configures resources, and drops launchd plists into `/Library/LaunchDaemons/`. From that point on, launchd owns the VM processes — they start at boot and restart automatically if they crash. Salt is only needed again when the pillar changes.
Each VM gets a Salt minion installed inside it (via a separate state, not shown here). That minion registers with the same Salt master, making the VM appear as a normal kri node. kri sees the VM exactly like it sees a physical Mac Mini — same grains, same beacons, same API surface.
④ The Salt State Walkthrough
The state lives at `salt/states/tart/init.sls`. It has two logical blocks: install tart, then loop over the VM map from pillar and provision each one.
Variables
Three Jinja variables are extracted at the top and used throughout:
salt/states/tart/init.sls — preamble
{% set tart_bin = '/opt/homebrew/bin/tart' %}{% set brew_bin = ‘/opt/homebrew/bin/brew’ %} {% set run_user = pillar[‘tart’][‘run_user’] %} {% set vms = pillar.get(‘tart’, {}).get(‘vms’, {}) %}
`run_user` is the macOS user who owns `~/.tart/` — tart stores all VM disk images under the user's home directory, so every `cmd.run` that invokes tart must use `runas: {{ run_user }}`.
Install tart
salt/states/tart/init.sls — install block
# 1. Tap the Cirrus Labs Homebrew tap (idempotent)tart_tap: cmd.run: - name: {{ brew_bin }} tap cirruslabs/cli - unless: {{ brew_bin }} tap | grep -q ‘cirruslabs/cli’ - runas: {{ run_user }}
2. Install tart (skip if binary already exists)
tart_install: cmd.run: - name: {{ brew_bin }} install cirruslabs/cli/tart - unless: test -x {{ tart_bin }} - runas: {{ run_user }} - require: - cmd: tart_tap
The `unless` guards make both states idempotent: the tap is skipped if already present, and tart is skipped if the binary exists. On subsequent `state.apply` runs these execute in milliseconds with no network traffic.
Per-VM provisioning loop
The Jinja `{% for vm_name, vm in vms.items() %}` loop generates one set of states per VM. The `{% if vm.get('enabled', True) %}` check skips VMs whose pillar has `enabled: false` — they stay defined but dormant until you flip the flag and re-apply.
salt/states/tart/init.sls — per-VM states
{% for vm_name, vm in vms.items() %}{% if vm.get(‘enabled’, True) %}
{% set cpu = vm.get(‘cpu’, 2) %} {% set memory = vm.get(‘memory’, 4096) %} {% set disk = vm.get(‘disk’, 20) %} {% set image = vm[‘image’] %} {% set label = ‘com.tart.’ ~ vm_name %} {% set plist = ‘/Library/LaunchDaemons/’ ~ label ~ ‘.plist’ %}
Clone from OCI registry — pulls image automatically if not cached
tart_clone_{{ vm_name }}: cmd.run: - name: {{ tart_bin }} clone {{ image }} {{ vm_name }} - unless: {{ tart_bin }} list 2>/dev/null | awk ‘NR>1 {print $1}’ | grep -qx ’{{ vm_name }}’ - runas: {{ run_user }} - timeout: 3600 - require: - cmd: tart_install
Set CPU / memory / disk — only runs on first clone (onchanges)
tart_set_{{ vm_name }}: cmd.run: - name: >- {{ tart_bin }} set {{ vm_name }} —cpu {{ cpu }} —memory {{ memory }} —disk {{ disk }} - onchanges: - cmd: tart_clone_{{ vm_name }} - runas: {{ run_user }}
Drop the launchd plist — rendered from Jinja template
tart_plist_{{ vm_name }}: file.managed: - name: {{ plist }} - source: salt://tart/files/com.tart.vm.plist.jinja - template: jinja - context: vm_name: {{ vm_name }} tart_bin: {{ tart_bin }} run_user: {{ run_user }} label: {{ label }} - user: root - group: wheel - mode: ‘0644’
Load the daemon — skip if already registered with launchctl
tart_service_{{ vm_name }}: cmd.run: - name: launchctl load -w {{ plist }} - unless: launchctl list 2>/dev/null | grep -q ’{{ label }}’ - require: - file: tart_plist_{{ vm_name }} - cmd: tart_set_{{ vm_name }}
{% endif %} {% endfor %}
A few things worth noting in the clone step: `tart clone` both resolves the OCI image and copies the disk image to `~/.tart/VMs/<vm_name>/`. The `unless` guard uses `tart list` and `awk 'NR>1'` to skip the header row before grepping — without that, the header line would produce a false positive.
**First clone of a macOS image takes up to 20 minutes.** The Sonoma base image from ghcr.io/cirruslabs is roughly 20 GB. Salt's default command timeout is 5 minutes — which is why the clone state explicitly sets `timeout: 3600`. Without it, Salt kills the download mid-stream and leaves a partial VM that confuses subsequent runs.
The `tart_set` state uses `onchanges` rather than `require`. This means it only runs when the clone step actually changed something — i.e., on first creation. On re-apply to an already-running VM the set command is skipped entirely, which prevents tart from trying to resize a running VM's disk (that would fail).
⑤ The launchd Plist Template
The plist template at `salt/states/tart/files/com.tart.vm.plist.jinja` is rendered once per VM and written to `/Library/LaunchDaemons/com.tart.<vm_name>.plist` as a root-owned file. launchd reads it from there and manages the VM process for the lifetime of the host.
salt/states/tart/files/com.tart.vm.plist.jinja
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC ”-//Apple//DTD PLIST 1.0//EN” “http://www.apple.com/DTDs/PropertyList-1.0.dtd”> <plist version=“1.0”> <dict> <key>Label</key> <string>{{ label }}</string>
<key>ProgramArguments</key>
<array>
<string>{{ tart_bin }}</string>
<string>run</string>
<string>{{ vm_name }}</string>
<string>--no-graphics</string>
</array>
<!-- Run as the user who owns ~/.tart/ -->
<key>UserName</key>
<string>{{ run_user }}</string>
<key>RunAtLoad</key>
<true/>
<!-- Restart automatically if the VM exits unexpectedly -->
<key>KeepAlive</key>
<true/>
<key>ThrottleInterval</key>
<integer>10</integer>
<key>StandardOutPath</key>
<string>/var/log/tart-{{ vm_name }}.log</string>
<key>StandardErrorPath</key>
<string>/var/log/tart-{{ vm_name }}.err</string></dict> </plist>
Three keys are worth explaining in detail:
UserName
LaunchDaemons run as root by default. tart stores all VM disk images under `~/.tart/VMs/` — the home directory of whichever user owns the tart installation. Without `UserName`, the daemon would launch as root and try to find VMs at `/var/root/.tart/`, which doesn't exist. Setting `UserName` to the correct user causes launchd to switch to that user before executing the tart process.
KeepAlive
`KeepAlive: true` tells launchd to restart the process whenever it exits, for any reason. If the VM crashes, if tart is force-killed, or if the host comes back from sleep and the VM process is gone — launchd respawns it. This is what turns tart into a self-healing VM service rather than a one-shot command. Combined with `RunAtLoad: true`, the VMs are always running as long as the host is up.
ThrottleInterval
Set to 10 seconds. This prevents launchd from rapid-fire-respawning a VM that's crashing immediately on start (a crash loop). If tart exits within 10 seconds of starting, launchd waits before trying again. Without this, a misconfigured VM could hammer the host with restart attempts. Check `/var/log/tart-<vm_name>.err` if a VM keeps restarting.
The `--no-graphics` flag tells tart to start the VM headless — no window, no VNC. That's correct for unattended CI nodes. SSH in via the VM's IP if you need a shell; use `tart ip <vm_name>` to get it.
⑥ The Pillar
VM configuration is entirely in pillar. No VM names or sizes are hardcoded in the state. Copy the example to your minion's active pillar path and you're done.
salt/pillar/tart.sls.example
tart:macOS user who owns ~/.tart/ (tart VMs are stored per-user)
run_user: dk
vms: # macOS Sonoma — mirrors a real Mac Mini node for kri testing kri-test-macos-1: image: ghcr.io/cirruslabs/macos-sonoma-base:latest cpu: 4 # virtual CPUs memory: 8192 # MB disk: 60 # GB enabled: true
# Second macOS VM — for multi-node kri scenarios
kri-test-macos-2:
image: ghcr.io/cirruslabs/macos-sonoma-base:latest
cpu: 4
memory: 8192
disk: 60
enabled: false # flip to true when needed
# Lightweight Linux VM — for non-macOS-specific kri API / worker tests
kri-test-linux-1:
image: ghcr.io/cirruslabs/ubuntu:latest
cpu: 2
memory: 4096 # MB
disk: 20 # GB
enabled: true
The `enabled: false` pattern for `kri-test-macos-2` is the right way to manage on-demand VMs. The VM is defined in pillar — grains, CPU/memory, image source all documented — but it doesn't consume host resources until you need it. Flip it to `true`, run `state.apply tart`, and the VM is up within however long the image takes to clone (seconds for Linux, up to 20 minutes for macOS).
**Top.sls entry:** to activate this pillar for minion `mm1`, add the following to `salt/pillar/top.sls`:
base:‘mm1’: - tart
Available images from ghcr.io/cirruslabs:
`ghcr.io/cirruslabs/macos-sonoma-base:latest` — macOS 14 Sonoma, ~20 GB
- `ghcr.io/cirruslabs/macos-ventura-base:latest` — macOS 13 Ventura, ~20 GB
- `ghcr.io/cirruslabs/ubuntu:latest` — Ubuntu LTS, ~2 GB
- `ghcr.io/cirruslabs/debian:latest` — Debian, ~2 GB
⑦ How to Apply
With the pillar in place, applying the state to a Mac Mini minion is one command:
# Apply to a single minionsalt ‘mm1’ state.apply tart
Apply to all Mac Mini minions at once
salt ‘mm*’ state.apply tart
Salt executes the states in dependency order. On a host with no previous tart installation the sequence is: tap → install → clone macOS VM → set resources → drop plist → load daemon → clone Linux VM → set resources → drop plist → load daemon.
**First run is slow.** The macOS Sonoma base image is ~20 GB. On a typical home broadband connection or a Mac Mini on a shared office network, the clone step can take 15–20 minutes. The `timeout: 3600` in the state covers this. Salt will appear to hang on `tart_clone_kri-test-macos-1` — that's expected. Monitor progress on the minion with: `tail -f /var/log/salt/minion`
Once the state completes, get the VM IPs:
# Run on the Mac Mini directly, or via salt cmd.runtart ip kri-test-linux-1
→ 192.168.64.12 (example; DHCP assigns the actual IP)
tart ip kri-test-macos-1
→ 192.168.64.13
Or via Salt
salt ‘mm1’ cmd.run ‘tart ip kri-test-linux-1’ runas=dk
SSH in to verify:
ssh admin@192.168.64.12 # Linux VM — default user is 'admin'ssh admin@192.168.64.13 # macOS VM — same
Check launchd service status on the host:
# List all tart serviceslaunchctl list | grep com.tart
Check a specific VM’s status (0 = running)
launchctl list com.tart.kri-test-linux-1
Tail VM logs
tail -f /var/log/tart-kri-test-linux-1.log tail -f /var/log/tart-kri-test-linux-1.err
⑧ Tearing Down
The remove state at `salt/states/tart/remove.sls` is intentionally destructive. It unloads the launchd daemon, stops the VM with a 30-second graceful timeout, deletes the disk image, and removes the plist. Nothing is left on the host.
salt/states/tart/remove.sls
# Unload daemon first — prevents launchd from restarting the VMtart_unload_{{ vm_name }}: cmd.run: - name: launchctl unload -w {{ plist }} - onlyif: launchctl list 2>/dev/null | grep -q ’{{ label }}‘
Stop the VM gracefully (30s timeout)
tart_stop_{{ vm_name }}: cmd.run: - name: {{ tart_bin }} stop {{ vm_name }} —timeout 30 - onlyif: {{ tart_bin }} list 2>/dev/null | awk ‘NR>1 {print $1}’ | grep -qx ’{{ vm_name }}’ - runas: {{ run_user }} - require: - cmd: tart_unload_{{ vm_name }}
Delete disk image — permanent, no recovery
tart_delete_{{ vm_name }}: cmd.run: - name: {{ tart_bin }} delete {{ vm_name }} - onlyif: {{ tart_bin }} list 2>/dev/null | awk ‘NR>1 {print $1}’ | grep -qx ’{{ vm_name }}’ - runas: {{ run_user }} - require: - cmd: tart_stop_{{ vm_name }}
Remove plist
tart_plist_absent_{{ vm_name }}: file.absent: - name: {{ plist }} - require: - cmd: tart_unload_{{ vm_name }}
Run it:
salt 'mm1' state.apply tart.remove
**This reads from the same pillar.** `remove.sls` iterates over all VMs in the pillar — `enabled` flag is ignored, every defined VM is torn down. If you only want to remove a single VM, either comment it out of the pillar before running, or stop and delete it manually with `tart stop <name>` and `tart delete <name>` on the host.
The `onlyif` guards in the remove state mean it's safe to run against a host that was never provisioned or is already clean — every step is a no-op if the VM or plist doesn't exist.
⑨ What’s Next
The VMs are up. launchd keeps them running. Now the rest of the kri testing infrastructure can land on top of them.
Step 1
Register as kri nodes
Install the kri Salt minion inside each VM. The minion connects to the same Salt master and appears in kri's node inventory alongside physical Mac Minis — same grains, same beacon events.
Step 2
Run E2E tests against VMs
kri's Playwright test suite can target VM IPs directly. Any test that exercises Salt state pushes, job dispatch, or minion health checks can run against a VM node without affecting production.
Step 3
Test destructive operations
Playbooks that reboot a node, reinstall Xcode, or wipe a build cache are too risky to run on physical machines during active sprints. On a VM, if it goes wrong, delete it and clone fresh from the OCI image.
Step 4
Keep physical Macs pristine
Production Mac Minis run iOS builds. They stay clean. All kri development and feature testing happens inside VMs. When a feature is proven on VMs, it ships to the fleet.
**The core insight:** tart VMs on the Mac Mini host look identical to physical Mac Minis from kri's perspective. Salt grains, network connectivity, launchd, Homebrew, Xcode — all of it works the same way inside a VM. The isolation is real, the fidelity is high, and the cost to clone a fresh one is a `state.apply` plus a 20-minute wait for the macOS image pull.
The Salt states for tart are three files, about 150 lines total including comments. They have been running cleanly on a single Mac Mini during kri development — provisioning a macOS VM for API/minion integration tests and a Linux VM for the kri backend worker tests. The physical Mac Minis stay untouched during development sprints.
Written by **hellodk (Deepak Gupta)** · hellodk.io · 27 May 2026
Salt states: `salt/states/tart/init.sls`, `salt/states/tart/remove.sls`, `salt/states/tart/files/com.tart.vm.plist.jinja`, `salt/pillar/tart.sls.example` — all in the kri repository.
tart: tart.run · Images: github.com/cirruslabs/macos-image-templatesEnjoyed this post?
Get the next one in your inbox — only when I ship something worth reading.
Newsletter form not configured.
Or follow on Substack for the newsletter.
Comments via GitHub Discussions
Comments not configured. Set GISCUS env vars to enable.
Related Posts
vagrant Vagrant with QEMU/KVM on Linux
How to use Vagrant with the QEMU/KVM provider instead of VirtualBox for faster local VMs on Linux.