---

1. What is Tart Virtualization?

Tart is a command-line virtualization toolset designed specifically for Apple Silicon Macs (e.g., M1/M2/M3 series). The key goals are:

• Build, run and manage VMs (virtual machines) of macOS and Linux on Apple Silicon hardware.
• Use Apple’s native virtualization support (via the Virtualization.Framework) so performance is near-native, minimal overhead.
• Treat VM images like container images: you can push/pull to OCI-compatible registries, version them, share them easily.
• Integrate seamlessly into CI/CD pipelines, automation workflows, developer labs, and large-scale Mac fleets.

In other words: if you have a Mac with Apple Silicon, and you want reproducible VM environments (macOS + Linux) that you can script, version, share, that spin up fast, Tart gives you a modern workflow.

---

2. Major use-cases of Tart Virtualization

Here are the scenarios where Tart really shines:

1. CI/CD runners for macOS & Linux
   • If you build macOS or iOS apps, you need macOS build agents. Tart lets you turn Apple Silicon Macs into reproducible, clean “golden images” for builds, tests, etc.
   • Also helpful for Linux runners on Apple Silicon hosts.
2. Developer sandbox / testing labs
   • Developers or Mac administrators can spin up VMs for testing new OS versions, messing with configurations, MDM enrollment, experimentation, without risking the host.
   • You can snapshot and reuse states, share images with your team.
3. Image management & sharing
   • Because Tart supports “clone/pull/push” workflows with OCI-compatible registries, you can bake an image (install all tools, MDM profiles, settings), then distribute it to other hosts/teams: reproducibility.
   • Useful for large teams, teams with many Macs, or labs where you want identical VM images.
4. Fleet / scale management
   • In large environments (Mac build farms, remote macOS desktops, device labs) Tart supports orchestration (via a companion tool called “Orchard” in its ecosystem) so you can manage many hosts, many VMs, automatically.
   • Helps when you have dozens/hundreds of Apple Silicon Macs and you want to operate them like “VM nodes”.
5. Cost/efficiency optimised
   • Because it uses native virtualization (no heavy emulation) and supports versioned images, you can cut boot/setup times, reduce drift in build agents, and manage infrastructure more efficiently.

If you summarise: Tart is ideal when you need repeatable, automated, versioned VM environments on Apple Silicon, for dev/test/CI, rather than just running a desktop VM for fun.

---

3. How Tart Virtualization works

Here is the architecture and internal workings in more detail:

Platform foundations

• On Apple Silicon Macs, Apple provides the Virtualization.Framework API: it enables user-mode code to create hypervisor-style VMs, manage virtual CPUs, memory, devices, network and storage.
• Tart sits atop that framework, exposing a CLI that handles image download, disk management, configuration, registry push/pull, and VM lifecycle (create, run, stop, delete).

Key concepts

• Images / VM definitions: You obtain or build VM images (macOS or Linux). These are stored locally under your home directory (by default) and can be cloned from remote image registries.
• OCI registry support: Tart treats VM images like container images. You can push your VM image to an OCI-compatible registry (e.g., GitHub Container Registry, ECR, Harbor) and later pull it on another host.
• Commands: Typical CLI commands are: tart install/clone/pull, tart run, tart set (to adjust CPU/memory/disk), tart delete.
• Resource configuration: When you create a VM you can define how many virtual CPUs, how much memory, how large the virtual disk, display resolution, maybe networking. After creation you can use tart set to adjust some parameters.
• Shared directories / host ↔ guest file mounting: Tart supports mapping host directories into guest VMs (via virtio-fs) so files can be shared.
• Disk & caching management: Tart caches downloaded images and IPSW files. It auto-prunes old caches to avoid disk bloat, though you can tune or disable that.
• Nested virtualization / limitations: Because Tart relies on Virtualization.Framework, it is subject to the underlying limitations: nested virtualization (a VM inside a VM) is limited or not supported depending on chip and OS version.
• macOS guest specifics: For macOS VM images, typically you create from an IPSW (Apple firmware file) or clone a prepared base image. After installation you might set up auto-login, enable SSH, disable password lock etc for automation.
• Linux guest specifics: For Linux guests (ARM64 distributions) you can use an ISO image; you may need to install SSH manually inside the guest, and for shared directories you may need to mount virtio-fs manually.

Workflow summary

1. Pull or create a VM image.
2. Adjust configuration (CPU/memory/disk).
3. Launch the VM using tart run.
4. Optionally connect via GUI or SSH.
5. Use the VM (install software, test).
6. If desired, push the VM image to registry.
7. On other hosts you can clone/pull and run the image.
8. Clean up unused VMs/caches.

Why performance is good

Because the host (Apple Silicon Mac) and the guest (macOS or ARM64 Linux) share the same architecture, and because Virtualization.Framework provides hardware acceleration (no need to emulate x86), the overhead is very low. The result: very fast boot, near-native performance in many cases.

---

4. How to install Tart on a Mac

Here’s a step-by-step installation guide, updated for late 2025.

Prerequisites

• A Mac with Apple Silicon (M1, M2, M3, etc).
• Running macOS 13 (Ventura) or later (newer OS versions are fully supported).
• Homebrew (or another package manager) is strongly recommended for simplicity.

Installation steps

1. Open Terminal.app on your Mac.
2. Ensure Homebrew is installed: brew update If Homebrew is not installed, install it via the official method.
3. Install the Tart CLI: brew install cirruslabs/cli/tart
4. Verify the installation: tart --version You should see the version number, indicating the CLI tool is installed correctly.
5. (Optional) Configure any environment variables or preferences you want; e.g., set TART_HOME if you want to store VM images in a custom location instead of the default ~/.tart.
6. After installation you may want to run a simple test: pull a known VM image and run it (see next section).

Note on licensing & usage

• On personal computers (workstations), usage is generally free, under the terms specified by the tool’s maintainers.
• In organizational / server-tier usage (clusters, many hosts), you may need to comply with licensing (e.g., number of hosts, cores).
• Always check the latest licensing terms before deployment in a large-scale environment.

---

5. Basic Tutorials: complete lifecycle of VMs using Tart

In this section I will walk you through the full lifecycle of a VM using Tart: from pulling/creating image, to configuring, running, sharing, and cleaning up.

A. Pulling / cloning a pre-built image

This is the fastest route.

# Example: clone a macOS base image (prepared by community/maintainer)
tart clone <image-registry>/macos-base:latest my-mac-vm

# Example: clone a Linux base image
tart clone <image-registry>/ubuntu:latest my-ubuntu-vm
Code language: PHP (php)

• You provide the remote image identifier and a local VM name (my-mac-vm, my-ubuntu-vm).
• The command downloads the manifest and disk image; the size may be large (dozens of GB).
• After download, the VM definition is available locally (usually under ~/.tart/vms/).

B. Creating a VM from scratch

If you don’t want to use a pre-built image:

For macOS guest:

tart create --from-ipsw=latest macos-vanilla
tart run macos-vanilla
Code language: JavaScript (javascript)

• This downloads an IPSW file (a macOS firmware image) and begins the VM creation process.
• You will boot into the macOS installer inside the VM; complete installation, create an admin user.
• Recommended post-install steps: enable auto-login for the admin user, enable SSH (Remote Login), disable screen-lock or password prompt for convenience in automation.

For Linux guest:

tart create --linux ubuntu-arm64
tart run --disk ~/Downloads/ubuntu-arm64-desktop.iso ubuntu-arm64
Code language: JavaScript (javascript)

• After installation you SSH in; ensure openssh-server is installed and enabled, allow SSH in firewall.

C. Configuring resources

Once the VM is created (or after pulling), you may want to adjust its configuration:

tart set my-mac-vm --cpu 4 --memory 8192  # 4 vCPU, 8 GB RAM
tart set my-ubuntu-vm --disk-size 50      # 50 GB disk
Code language: JavaScript (javascript)

• CPU, memory, disk size and display resolution are common parameters.
• On macOS guests you might also adjust display size or graphics resolution.
• For Linux you may need to expand the filesystem inside the guest after increasing disk size.

D. Running the VM

Once configured:

tart run my-mac-vm

or

tart run my-ubuntu-vm

• The VM window opens (for macOS typically a window with the VM’s display).
• Inside the VM you log in with the default credentials (for many base images username admin, password admin).
• For automation you may prefer to enable SSH and connect from the host: ssh admin@$(tart ip my-vm-name)

E. Mounting host directories into the VM

Very useful for sharing code/projects between host and VM:

tart run --dir=project:~/Code/Project1 my-mac-vm
Code language: JavaScript (javascript)

• Here project is the mount-name visible inside the VM, ~/Code/Project1 is the host path.
• Inside a macOS guest the mount point is by default: /Volumes/My Shared Files/project.
• Inside Linux guests you may need to manually mount: sudo mount -t virtiofs com.apple.virtio-fs.automount /mnt/shared And then access /mnt/shared/project.

F. Using the VM: install software / test / build

• Use the VM as you would any machine: install tools, build code, run tests, configure environments.
• For macOS guests you might install Xcode, configure MDM profiles, test configurations.
• For Linux guests you might install Docker, development tools, test scripts.

G. Capturing & pushing a VM image for reuse

Once your VM is prepared (all software installed, configuration baked):

tart push my-mac-vm myregistry.io/org/macos-golden:2025-10

• You tag the image and push it to an OCI registry.
• On another host you can do:

tart clone myregistry.io/org/macos-golden:2025-10 team-vm
tart run team-vm
Code language: PHP (php)

• This enables teams to share standardized images, or CI pipelines to use identical build agents.

H. Stopping, listing, deleting, pruning

• To list all VMs: tart list
• To stop a VM: shut it down from inside the VM (recommended) or close the window.
• To delete a VM: tart delete my-mac-vm
• To prune caches (free disk space): Tart auto-prunes caches when pulling/cloning and low disk space. You can also disable auto-prune or adjust limit via environment variable.
• Note: deleting a VM removes the definition and disk image; pushing an image does not push the suspend snapshot or host-specific data.

I. Putting it all together: Example workflow

1. Install Tart on your Mac.
2. Clone a base image: tart clone registry/org/macos-vanilla:latest mac-vanilla tart set mac-vanilla --cpu 4 --memory 16384 --disk-size 80 tart run mac-vanilla
3. Inside VM: create admin user, enable SSH, install Xcode or your tooling.
4. Exit VM and push image: tart push mac-vanilla registry/org/macos-golden:v1
5. On another machine (or CI worker): clone and run: tart clone registry/org/macos-golden:v1 build-vm tart run build-vm
6. After use: delete VM, prune if needed.

---

6. Key limitations & best practices

Limitations

• Requires Apple Silicon host (Intel Macs are not supported).
• Nested virtualization (VM inside VM) is either unsupported or limited depending on chip/OS.
• Some guest OS features (e.g., Secure Enclave emulation, certain Apple-ID/activation flows) may be constrained by Virtualization.Framework.
• When using macOS guests you must comply with Apple’s licensing (e.g., running macOS VMs on Apple hardware).
• Disk resizing for macOS guests can be more complicated (you might need to handle the APFS container and recovery partition manually).
• Shared directory mounting for Linux guests sometimes requires manual mount commands.

Best practices

• Use versioned image tags when pushing images (:v1.0, :2025-10-22, etc) so you can roll back or reproduce builds.
• Bake your “golden” images with all required software and settings once, then reuse them rather than always rebuilding from scratch.
• Keep your TART_HOME location on a sufficiently large and fast disk (preferably SSD) because VM images are large (tens of GB).
• Monitor disk usage – cached images and IPSW files can accumulate; configure auto-prune limits to avoid host disk fill-up.
• For automation/CI: use SSH or headless mode, script tart ip, ssh admin@$(...), etc, so you can drive the VM from your pipeline.
• Use shared directories to mount code into the VM rather than copying files every time; it speeds up workflows.
• Clean up old images/unused VMs regularly to keep disk space tidy.

---