How cirruslabs/tart works
1. What this repo is
- Tart is a Swift-based command-line VM manager for Apple Silicon.
- The core runtime is macOS-focused and built around Apple’s Virtualization.Framework; the repo also includes a Linux-leaning platform abstraction layer, but the primary product is VM lifecycle management on macOS.
2. Top-level architecture
- The entrypoint is the CLI application in Sources/tart.
- User-facing behavior is organized as discrete commands under Sources/tart/Commands and wired into shared domain/services in the rest of Sources/tart.
- This is not a monolith with one big VM class; it is a command shell over a set of VM, storage, registry, networking, and logging subsystems.
3. Command layer
- Commands cover the full VM lifecycle and registry workflow: create, clone, run, exec, stop, suspend, delete, rename, list, get, set, ip, import, export, pull, push, login, logout, prune, and fqn.
- Each command acts as an orchestration boundary: it parses CLI input, invokes core services, and formats output rather than owning low-level VM logic.
4. VM core and persistence boundary
- VM.swift, VMConfig.swift, VMDirectory.swift, and VMDirectory+* define the core VM model and how a VM is represented on disk.
- VMDirectory appears to be the main persistence unit: it combines config, metadata, and backing storage for a VM instance.
- VM+Recovery.swift suggests recovery/snapshot-style logic for restoring a VM directory or handling interrupted operations.
5. Storage backends
- Tart supports at least two storage modes: local filesystem-backed VMs (VMStorageLocal.swift) and OCI-backed VMs (VMStorageOCI.swift).
- VMStorageHelper.swift likely coordinates common storage behaviors across those backends.
- The storage layer is a key architectural boundary: commands operate on VMs, while the storage implementation decides whether the VM is local or represented as OCI content.
6. OCI and registry integration
- The Sources/tart/OCI subtree handles registry-facing functionality: authentication, digests, manifests, remote name parsing, and WWW-Authenticate handling.
- Layerizer converts disk artifacts into OCI layers, which is the main mechanism behind Tart’s “push/pull VMs from registries” workflow.
- Auth is pluggable via credentials providers: environment, Docker config, keychain, and stdin-based credentials.
- This subsystem is the main bridge between VM disk content and external container registries.
7. Image, cache, and fetch pipeline
- Fetcher.swift, IPSWCache.swift, and LocalLayerCache.swift suggest a pipeline for acquiring base OS images and reusing downloaded or layerized artifacts.
- The repo is optimized for repeated VM creation and cloning by caching large inputs such as IPSW images and OCI layers.
- DiskImageFormat.swift and Diskutil.swift indicate platform-specific handling of disk images and conversion/inspection utilities.
8. Networking, identity, and guest reachability
- Network/, MACAddressResolver/, and IP-related commands support VM connectivity and address discovery.
- MAC address resolution is backed by ARP/lease parsing and agent-assisted lookup, which implies Tart tracks guest identity through network metadata, not just VM names.
- This subsystem is important for ip, exec, and possibly remote orchestration features where the guest must be reached reliably after boot.
9. Console and interaction paths
- VNC/ provides guest display access, with variants for full VNC and screen-sharing-based access.
- ControlSocket.swift and Exec.swift indicate an out-of-band control channel for interacting with a running guest, likely used for command execution and coordination.
- So Tart has two distinct interaction planes: graphical console access and programmatic control/exec access.
10. Logging, formatting, and terminal UX
- Logging/, Formatter/, Term.swift, and ShellCompletions/ support CLI ergonomics rather than VM mechanics.
- ProgressObserver and URLSessionLogger suggest download/upload progress and network-operation visibility are first-class UX concerns.
- This makes sense for a tool that moves large VM images and registry layers over the network.
11. Platform and environment abstraction
- Platform/, DeviceInfo/, Root.swift, CI/CI.swift, and utility files abstract differences in OS/architecture and execution environment.
- The presence of Darwin/Linux platform modules indicates the code is structured to compile across environments even though the VM runtime is Apple-centric.
- CI helpers likely alter behavior when running in automation or test environments.
12. Release, packaging, and operations
- The repo includes Swift Package Manager metadata, CI configs, goreleaser.yml, and scripts for versioning, packaging, signing, and docs publishing.
- Resources/ contains entitlements, provision profiles, and app assets, showing the CLI also has macOS-specific signing/distribution concerns.
- Operationally, Tart is designed to be installed via package managers and run in CI or developer environments, not just as a local utility.
13. Verification and ecosystem
- Tests/TartTests is the main unit test suite for digesting, registry auth, VM config, locking, layerization, and networking helpers.
- integration-tests/ is a separate Python/Go test harness that exercises real CLI flows, registry interactions, and OpenTelemetry behavior.
- benchmark/ is a standalone Go benchmark tool for performance evaluation, indicating the project treats VM throughput as a core product metric.
14. High-level data flow
- Typical flow: CLI command → core VM/OCI service → storage/cache/network helpers → external system (filesystem, registry, Apple virtualization APIs, VNC, keychain, or network stack).
- Create/clone flows start from an image source, materialize a VM directory, and persist it locally or as OCI content.
- Run/exec flows load VM config, start the guest, establish networking and console/control channels, and then interact with the running VM.
Main entry points: Commands Commands · Registry.swift Registry · VM.swift VM Model · TartTests Tests
Components 25
CLI
User-facing command shell and command orchestration
VM Core
VM model, directory layout, storage, and recovery
- VM Model · Core VM and VM configuration definitions
Sources/tart/VM.swift - VM Directory · On-disk VM representation and archive/OCI helpers
Sources/tart/VMDirectory.swift - Recovery · Recovery and interrupted-operation handling for VM state
Sources/tart/VM+Recovery.swift - Storage Helper · Shared logic for VM storage backends
Sources/tart/VMStorageHelper.swift - Local Storage · Local filesystem-backed VM storage
Sources/tart/VMStorageLocal.swift - OCI Storage · OCI-backed VM storage and registry materialization
Sources/tart/VMStorageOCI.swift - Fetcher · Acquires base images and remote artifacts
Sources/tart/Fetcher.swift - IPSW Cache · Cached Apple firmware and installer images
Sources/tart/IPSWCache.swift - Layer Cache · Local cache for OCI layers and reused artifacts
Sources/tart/LocalLayerCache.swift
OCI Registry
Registry auth, manifests, references, and layerization
Runtime
Networking, console access, and guest interaction
- Network · Guest network setup and bridging abstractions
Sources/tart/Network - MAC Resolver · Resolves guest identity via ARP, leases, and agents
Sources/tart/MACAddressResolver - Control Socket · Out-of-band guest control and exec coordination
Sources/tart/ControlSocket.swift - VNC · Guest display and screen-sharing access paths
Sources/tart/VNC
Support
Logging, platform abstraction, formatting, and environment helpers
- Config · Global configuration and shared options
Sources/tart/Config.swift - Logging · CLI logging, progress reporting, and HTTP session logs
Sources/tart/Logging - Platform · Darwin/Linux and architecture/environment abstraction
Sources/tart/Platform - Formatter · Human-facing output formatting helpers
Sources/tart/Formatter/Format.swift
Verification
Unit tests, integration tests, and benchmarks
- Tests · Primary Swift test suite for core logic
Tests/TartTests - Integration · End-to-end tests for real CLI and registry flows
integration-tests - Benchmark · Standalone benchmark tooling for VM throughput
benchmark
Connections 32
- tart CLI → Commands: dispatches · CLI entrypoint routes user input into subcommands
- tart CLI → Config: reads · Entrypoint and commands consume shared configuration
- Commands → VM Model: orchestrates · Commands act on VM lifecycle and metadata
- Commands → VM Directory: loads/saves · Commands manipulate on-disk VM directories
- Commands → Storage Helper: uses · Commands delegate storage decisions to shared helpers
- Commands → Registry: pulls/pushes · Registry-oriented commands talk to OCI services
- Commands → Network: configures · Run and IP flows depend on guest networking
- Commands → Control Socket: execs · Exec flows use the control channel
- Commands → VNC: opens · Run and console flows expose guest display access
- VM Model → VM Directory: persists as · VM state is represented through the VM directory boundary
- VM Directory → Recovery: recovers · Directory layer handles interrupted or partial state
- Storage Helper → Local Storage: adapts · Shared logic feeds the local storage backend
- Storage Helper → OCI Storage: adapts · Shared logic feeds the OCI-backed storage backend
- OCI Storage → Layerizer: packages · OCI storage relies on disk-to-layer conversion
- Fetcher → IPSW Cache: caches · Fetcher reuses downloaded installer images
- Fetcher → Layer Cache: reuses · Fetcher avoids repeated layer downloads and layerization
- Registry → Auth: authenticates · Registry client delegates credential handling
- Registry → Layerizer: uploads/downloads · Registry client moves layerized VM content
- Registry → Fetcher: sources · Registry workflows can start from remote artifact fetching
- Network → MAC Resolver: resolves · Networking uses MAC-to-guest identity discovery
- Control Socket → VM Model: targets · Control channel coordinates with running VM instances
- VNC → VM Model: targets · Console access attaches to running VMs
- Logging → Commands: reports · Command execution is surfaced through logs and progress
- Formatter → Commands: formats · Commands produce human-readable output through formatting helpers
- Platform → VM Model: adapts · Platform abstraction influences runtime behavior and compatibility
- Platform → Network: adapts · Networking differs across host platforms and builds
- Tests → VM Model: verifies · Unit tests cover VM config and state logic
- Tests → Registry: verifies · Unit tests cover registry and digest handling
- Tests → MAC Resolver: verifies · Unit tests cover lease and MAC resolution behavior
- Integration → Commands: exercises · End-to-end tests run real CLI flows
- Integration → Registry: exercises · Integration tests cover registry interactions
- Benchmark → Commands: measures · Benchmark harness measures command and runtime throughput