DOCSEARCHbyAlgolia
Submit Docs

CirrusLabs macOS Image Templates

repository·main·Indexed 43 days ago

https://github.com/cirruslabs/macos-image-templates

A collection of macOS Packer templates for building virtual machine images for Tart. Optimized for GitHub Actions runners, Cirrus Runners, and automation via cirrus-cli. Includes image variants for vanilla macOS, base installations with Homebrew, Xcode-preinstalled images, and runner-specific images for versions including Sonoma, Sequoia, and Tahoe. Features an experimental Tart Metal capability shim for virtual-GPU support.

Tokens
1.6K
Snippets
6
Records
10
Agent score
57%

What's inside macos-image-templates

  1. Available macOS image variants

    main

    This repository provides Packer templates to build macOS virtual machines for use with Tart, self-hosted GitHub Actions runners, Cirrus Runners, or other automation via the cirrus-cli.

    Available image variants include:

    • macos-{golden-gate,tahoe,sequoia,sonoma}-vanilla: A vanilla macOS installation with helpful tweaks (like auto-login) but no additional software.
    • macos-{golden-gate,tahoe,sequoia,sonoma}-base: Based on the vanilla image, includes brew and other useful software, but no Xcode.
    • macos-{tahoe,sequoia,sonoma}-xcode:N: Based on the base image, includes Xcode N and Flutter-preinstalled.
    • macos-runner:{tahoe,sequoia,sonoma}: A variant of the xcode:N image with multiple versions of Xcode pre-installed and the xcodes tool for switching between them.

    A full list of available VMs can be found in the CirrusLabs GitHub Packages.

  2. Understand image release and update cadences

    main

    Xcode Image Releases

    When a new version of Xcode is released, a GitHub release is automatically initiated to build and push a new version of macos-{tahoe,sequoia}-xcode:N. This typically occurs the weekend following the Xcode release.

    Regular Image Rebuilds

    Certain images are rebuilt monthly to update pre-installed packages. Rebuilds occur on the first Saturday of every month, as defined by the repository's monthly workflow.

  3. Enable Metal capabilities for macOS VMs

    main

    Base images include an experimental Tart Metal shim located at /usr/local/lib/TartMetalCapabilities.dylib. This shim is not enabled by default for the guest agent or tart exec.

    1. Enable unrestricted virtual-GPU features on the host

    Before starting the VM, you must enable unrestricted virtual-GPU features on the host machine as the user running Tart:

    defaults write com.apple.gpusw.ParavirtualizedGraphics ForceUnrestrictedDeviceFeatureLevel -bool true

    Note: You must restart any already-running VMs after changing this preference.

    2. Run a workload with the Metal shim

    To enable the shim for a specific command (e.g., for Apple family 9 and 64 KiB of threadgroup memory), use tart exec with the following environment variables:

    tart exec my-vm /usr/bin/env \
  DYLD_INSERT_LIBRARIES=/usr/local/lib/TartMetalCapabilities.dylib \
  TART_METAL_APPLE_FAMILY_MAX=1009 \
  /path/to/workload

    Important Notes:

    • To run normally without the shim, omit these environment variables.
    • TART_METAL_APPLE_FAMILY_MAX=0 disables the capability override.
    • Each opted-in process receives its own settings.
    • Protected executables may reject injection.
    • GPU support depends on the host, guest, and specific workload.
    defaults write com.apple.gpusw.ParavirtualizedGraphics ForceUnrestrictedDeviceFeatureLevel -bool true

tart exec my-vm /usr/bin/env \
  DYLD_INSERT_LIBRARIES=/usr/local/lib/TartMetalCapabilities.dylib \
  TART_METAL_APPLE_FAMILY_MAX=1009 \
  /path/to/workload

  6. Build an Xcode macOS Image

    main

    To build an image containing Xcode, use the templates/xcode.pkr.hcl template. This requires two specific variables:

    • macos_version: The version of macOS to install (e.g., sonoma).
    • xcode_version: The version of Xcode to install, provided as a string (e.g., "[15.4]").
    packer build -var macos_version=sonoma -var xcode_version="[15.4]" templates/xcode.pkr.hcl

  7. Build a Vanilla macOS Image

    main

    To build the macos-sonoma-vanilla image, use the packer build command pointing to the vanilla Sonoma template.

    If you need to build an image with System Integrity Protection (SIP) disabled, use the templates/disable-sip.pkr.hcl template and provide a vm_name variable.

    # Standard vanilla build
packer build templates/vanilla-sonoma.pkr.hcl

# Build with SIP disabled
packer build -var vm_name=sonoma-vanilla templates/disable-sip.pkr.hcl

  8. Configure Tart Metal capabilities via environment variables

    main

    The Tart Metal capability shim uses environment variables to define reported Metal capabilities to guest processes. These variables are read once when the library is loaded. Note that the shim uses private, version-sensitive behavior; reported capabilities do not guarantee that every corresponding GPU operation is supported.

    To enable the shim, you must provide a valid TART_METAL_APPLE_FAMILY_MAX. If this variable is missing, zero, or invalid, the shim is disabled.

  10. Reference Tart Metal configuration variables

    main

    The following environment variables control the behavior of the Tart Metal capability shim:

    | Variable | Behavior |
| --- | --- |
| `TART_METAL_APPLE_FAMILY_MAX` | Required Apple-family ceiling, from 1001 through 1999. Missing, zero, or invalid values disable the shim. |
| `TART_METAL_MAX_THREADGROUP_MEMORY` | Memory floor in bytes; defaults to 65536. |
| `TART_METAL_RECOMMENDED_WORKING_SET_SIZE` | Optional working-set floor in bytes; unchanged when unset. |