Tart Virtualization Toolset

Tart is a virtualization toolset designed to build, run, and manage macOS and Linux virtual machines (VMs) on Apple Silicon. It is optimized for automation and CI/CD workflows.

Key features include:

• Near-native performance: Uses Apple's Virtualization.Framework.
• OCI Registry Integration: Push and pull virtual machines from any OCI-compatible container registry.
• Automated Creation: Supports the Tart Packer Plugin for automating VM creation.
• CI Integration: Designed to integrate easily with any CI system.

Orchard is an orchestrator designed to manage Tart virtual machines at scale across a cluster of Apple Silicon machines. Unlike general-purpose orchestrators like Kubernetes or Nomad, Orchard is a single Go binary designed for simplicity, security, and ease of operation for managing thousands of virtual machines.

Key features include:

• Single Binary Distribution: Can be run in controller mode on Linux/macOS or worker mode on macOS hosts with no external database dependencies (uses embedded BadgerDB).
• Secure by Default: All communication between the controller and workers is secure, and external API requests are authorized.
• First-class Access: Provides support for accessing virtual machines over SSH/VNC and script execution.
• Simplified Operations: Designed for operators who may not have experience with complex orchestration systems.

Cirrus Runners uses a fixed-price monthly subscription model rather than a per-minute execution model used by GitHub-managed runners.

• Pricing: $150 per month per Cirrus Runner.
• Availability: Each runner is available 24/7 for your organization's GitHub Actions workflows.
• Queueing: If all runners are busy, additional jobs are queued and executed as soon as a runner becomes free.
• Cost Optimization: Because you pay a flat fee, your goal is to maximize runner utilization to achieve the lowest possible price per minute. For example, at 100% utilization (43,200 minutes/month), the cost is approximately $0.0035 per minute.

An Orchard cluster consists of three primary components:

• Controller: Manages the cluster and schedules resources. Only one Controller instance is supported at a time.
• Worker: Responsible for executing Virtual Machines (VMs). You can deploy one or more Workers.
• Client: Responsible for creating, modifying, and removing resources on the Controller. Clients can be the Orchard CLI or an API consumer.

Networking Requirements:

• The Controller must be directly accessible from both Workers and Clients.
• Workers and Clients can be deployed anywhere (e.g., behind a NAT) as long as they can reach the Controller.

To run Flexible I/O tester workloads, ensure that passwordless sudo is configured on your system. Run the benchmark from the benchmark/ directory using the following command structure:

go run cmd/main.go fio --image <IMAGE_NAME> --prepare '<PREPARE_COMMAND>'

Example using a specific macOS image:

go run cmd/main.go fio --image ghcr.io/cirruslabs/macos-tahoe-base:latest --prepare 'sudo purge && sync'

Use the Orchard CLI to create, list, and delete Virtual Machines across your orchestrated hosts.

• Create a VM: Specify an image and a name for the VM.
• List VMs: View currently running VM resources.
• Delete a VM: Remove a VM and its associated resources.

# Create a VM
orchard create vm --image ghcr.io/cirruslabs/macos-tahoe-base:latest tahoe-base

# List VMs
orchard list vms

# Delete a VM
orchard delete vm tahoe-base

Once the executor is configured, you can use any remote Tart Image in your .gitlab-ci.yml file. The Tart Executor will automatically pull the image from the registry and use it to create ephemeral VMs. Ensure your job uses the appropriate tags if your runners are specifically tagged for Tart.

# You can use any remote Tart Image.
# Tart Executor will pull it from the registry and use it for creating ephemeral VMs.
image: ghcr.io/cirruslabs/macos-tahoe-base:latest

test:
  tags:
    - tart-installed # in case you tagged runners with Tart Executor installed
  script:
    - uname -a

To access a service running on your Mac from within a Tart VM:

1. Ensure the host service is bound to 0.0.0.0.
2. Identify the router's IP address from within the VM using:

netstat -nr | awk '/default/{print $2; exit}'

Warning: This only works with the default NAT network. If you are using Softnet (via tart run --net-softnet <VM NAME>), network isolation is stricter and host access is not possible.

Use the vnc command to open Screen Sharing into a remote VM. Like SSH, this uses port forwarding via the Orchard Controller.

• Basic VNC: Opens the connection to the VM.
• Custom Credentials: Use --username and --password (defaults to admin/admin).

# Open VNC for a VM
orchard vnc vm tahoe-base

Install the Orchard Controller as a systemd service using the Cirrus Labs YUM repository.

1. Create a /etc/yum.repos.d/cirruslabs.repo file with the Cirrus Labs repository configuration.
2. Install orchard-controller via yum.
3. Enable and start the orchard-controller service.

Bootstrap credentials are printed to standard output. You can view them using journalctl -u orchard-controller.

# Create /etc/yum.repos.d/cirruslabs.repo
[cirruslabs]
name=Cirrus Labs Repo
baseurl=https://yum.fury.io/cirruslabs/
enabled=1
gpgcheck=0

sudo yum -y install orchard-controller

systemctl enable orchard-controller
systemctl start orchard-controller

Starting with macOS 15 (Sequoia), Virtualization.Framework requires an unlocked login.keychain to run VMs. If you encounter errors like SecKeyCreateRandomKey_ios failed or Interaction is not allowed with the Security Server, you must ensure the keychain is available.

Option 1: Manual GUI Login Connect via Screen Sharing and log in to a Mac user account once to create the keychain. You can then enable automatic login or manually unlock the keychain via terminal.

Option 2: Automated Terminal Setup You can create and unlock a keychain with an empty password using these commands:

security create-keychain -p '' login.keychain
security unlock-keychain -p '' login.keychain
security login-keychain -s login.keychain

Note: For production or non-empty passwords, replace '' with your desired password.