# cirruslabs/tart architecture

> Architecture diagram of the GitHub repository cirruslabs/tart, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cirruslabs/tart
- Repository: https://github.com/cirruslabs/tart

## Overview

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: [`Sources/tart/Commands`](https://github.com/cirruslabs/tart/tree/main/Sources/tart/Commands) (Commands), [`Sources/tart/OCI/Registry.swift`](https://github.com/cirruslabs/tart/blob/main/Sources/tart/OCI/Registry.swift) (Registry), [`Sources/tart/VM.swift`](https://github.com/cirruslabs/tart/blob/main/Sources/tart/VM.swift) (VM Model), [`Tests/TartTests`](https://github.com/cirruslabs/tart/tree/main/Tests/TartTests) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_entrypoint["tart CLI<br/>entrypoint"]
  node_commands["Commands<br/>command layer"]
end

subgraph group_vm["VM Core"]
  node_vm_model["VM Model<br/>domain model<br/>[VM.swift]"]
  node_vm_directory[("VM Directory<br/>persistence boundary<br/>[VMDirectory.swift]")]
  node_vm_recovery["Recovery<br/>repair flow<br/>[VM+Recovery.swift]"]
  node_storage_helper["Storage Helper<br/>storage coordinator"]
  node_storage_local["Local Storage<br/>filesystem backend"]
  node_storage_oci["OCI Storage<br/>oci-backed storage<br/>[VMStorageOCI.swift]"]
  node_fetcher["Fetcher<br/>acquisition pipeline<br/>[Fetcher.swift]"]
  node_ipscache["IPSW Cache<br/>[IPSWCache.swift]"]
  node_layercache["Layer Cache"]
end

subgraph group_oci["OCI Registry"]
  node_oci_auth["Auth"]
  node_oci_registry["Registry<br/>[Registry.swift]"]
  node_oci_layerizer["Layerizer<br/>layer packaging"]
end

subgraph group_runtime["Runtime"]
  node_network["Network"]
  node_mac_resolver["MAC Resolver<br/>identity lookup"]
  node_control_socket["Control Socket<br/>control channel"]
  node_vnc["VNC<br/>console access"]
end

subgraph group_support["Support"]
  node_config["Config<br/>[Config.swift]"]
  node_logging["Logging<br/>observability"]
  node_platform["Platform<br/>abstraction layer"]
  node_formatter["Formatter<br/>output formatting<br/>[Format.swift]"]
end

subgraph group_verification["Verification"]
  node_tests["Tests"]
  node_integration["Integration<br/>cli harness"]
  node_benchmark["Benchmark<br/>performance harness"]
end

node_entrypoint -->|"dispatches"| node_commands
node_entrypoint -->|"reads"| node_config
node_commands -->|"orchestrates"| node_vm_model
node_commands -->|"loads/saves"| node_vm_directory
node_commands -->|"uses"| node_storage_helper
node_commands -->|"pulls/pushes"| node_oci_registry
node_commands -->|"configures"| node_network
node_commands -->|"execs"| node_control_socket
node_commands -->|"opens"| node_vnc
node_vm_model -->|"persists as"| node_vm_directory
node_vm_directory -->|"recovers"| node_vm_recovery
node_storage_helper -->|"adapts"| node_storage_local
node_storage_helper -->|"adapts"| node_storage_oci
node_storage_oci -->|"packages"| node_oci_layerizer
node_fetcher -->|"caches"| node_ipscache
node_fetcher -->|"reuses"| node_layercache
node_oci_registry -->|"authenticates"| node_oci_auth
node_oci_registry -->|"uploads/downloads"| node_oci_layerizer
node_oci_registry -->|"sources"| node_fetcher
node_network -->|"resolves"| node_mac_resolver
node_control_socket -->|"targets"| node_vm_model
node_vnc -->|"targets"| node_vm_model
node_logging -->|"reports"| node_commands
node_formatter -->|"formats"| node_commands
node_platform -->|"adapts"| node_vm_model
node_platform -->|"adapts"| node_network
node_tests -.->|"verifies"| node_vm_model
node_tests -.->|"verifies"| node_oci_registry
node_tests -.->|"verifies"| node_mac_resolver
node_integration -.->|"exercises"| node_commands
node_integration -.->|"exercises"| node_oci_registry
node_benchmark -.->|"measures"| node_commands

click node_entrypoint "https://github.com/cirruslabs/tart/tree/main/Sources/tart"
click node_commands "https://github.com/cirruslabs/tart/tree/main/Sources/tart/Commands"
click node_config "https://github.com/cirruslabs/tart/blob/main/Sources/tart/Config.swift"
click node_vm_model "https://github.com/cirruslabs/tart/blob/main/Sources/tart/VM.swift"
click node_vm_directory "https://github.com/cirruslabs/tart/blob/main/Sources/tart/VMDirectory.swift"
click node_vm_recovery "https://github.com/cirruslabs/tart/blob/main/Sources/tart/VM+Recovery.swift"
click node_storage_helper "https://github.com/cirruslabs/tart/blob/main/Sources/tart/VMStorageHelper.swift"
click node_storage_local "https://github.com/cirruslabs/tart/blob/main/Sources/tart/VMStorageLocal.swift"
click node_storage_oci "https://github.com/cirruslabs/tart/blob/main/Sources/tart/VMStorageOCI.swift"
click node_fetcher "https://github.com/cirruslabs/tart/blob/main/Sources/tart/Fetcher.swift"
click node_ipscache "https://github.com/cirruslabs/tart/blob/main/Sources/tart/IPSWCache.swift"
click node_layercache "https://github.com/cirruslabs/tart/blob/main/Sources/tart/LocalLayerCache.swift"
click node_oci_auth "https://github.com/cirruslabs/tart/blob/main/Sources/tart/OCI/Authentication.swift"
click node_oci_registry "https://github.com/cirruslabs/tart/blob/main/Sources/tart/OCI/Registry.swift"
click node_oci_layerizer "https://github.com/cirruslabs/tart/tree/main/Sources/tart/OCI/Layerizer"
click node_network "https://github.com/cirruslabs/tart/tree/main/Sources/tart/Network"
click node_mac_resolver "https://github.com/cirruslabs/tart/tree/main/Sources/tart/MACAddressResolver"
click node_control_socket "https://github.com/cirruslabs/tart/blob/main/Sources/tart/ControlSocket.swift"
click node_vnc "https://github.com/cirruslabs/tart/tree/main/Sources/tart/VNC"
click node_logging "https://github.com/cirruslabs/tart/tree/main/Sources/tart/Logging"
click node_platform "https://github.com/cirruslabs/tart/tree/main/Sources/tart/Platform"
click node_formatter "https://github.com/cirruslabs/tart/blob/main/Sources/tart/Formatter/Format.swift"
click node_tests "https://github.com/cirruslabs/tart/tree/main/Tests/TartTests"
click node_integration "https://github.com/cirruslabs/tart/tree/main/integration-tests"
click node_benchmark "https://github.com/cirruslabs/tart/tree/main/benchmark"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entrypoint,node_commands toneBlue
class node_vm_model,node_vm_directory,node_vm_recovery,node_storage_helper,node_storage_local,node_storage_oci,node_fetcher,node_ipscache,node_layercache toneAmber
class node_oci_auth,node_oci_registry,node_oci_layerizer toneMint
class node_network,node_mac_resolver,node_control_socket,node_vnc toneRose
class node_config,node_logging,node_platform,node_formatter toneIndigo
class node_tests,node_integration,node_benchmark toneTeal
```

## Components

### CLI

User-facing command shell and command orchestration

- [tart CLI](https://github.com/cirruslabs/tart/tree/main/Sources/tart): entrypoint · Top-level command application and shell wiring · `Sources/tart`
- [Commands](https://github.com/cirruslabs/tart/tree/main/Sources/tart/Commands): command layer · Subcommands for create, run, exec, registry, and lifecycle operations · `Sources/tart/Commands`

### VM Core

VM model, directory layout, storage, and recovery

- [VM Model](https://github.com/cirruslabs/tart/blob/main/Sources/tart/VM.swift): domain model · Core VM and VM configuration definitions · `Sources/tart/VM.swift`
- [VM Directory](https://github.com/cirruslabs/tart/blob/main/Sources/tart/VMDirectory.swift): persistence boundary · On-disk VM representation and archive/OCI helpers · `Sources/tart/VMDirectory.swift`
- [Recovery](https://github.com/cirruslabs/tart/blob/main/Sources/tart/VM+Recovery.swift): repair flow · Recovery and interrupted-operation handling for VM state · `Sources/tart/VM+Recovery.swift`
- [Storage Helper](https://github.com/cirruslabs/tart/blob/main/Sources/tart/VMStorageHelper.swift): storage coordinator · Shared logic for VM storage backends · `Sources/tart/VMStorageHelper.swift`
- [Local Storage](https://github.com/cirruslabs/tart/blob/main/Sources/tart/VMStorageLocal.swift): filesystem backend · Local filesystem-backed VM storage · `Sources/tart/VMStorageLocal.swift`
- [OCI Storage](https://github.com/cirruslabs/tart/blob/main/Sources/tart/VMStorageOCI.swift): oci-backed storage · OCI-backed VM storage and registry materialization · `Sources/tart/VMStorageOCI.swift`
- [Fetcher](https://github.com/cirruslabs/tart/blob/main/Sources/tart/Fetcher.swift): acquisition pipeline · Acquires base images and remote artifacts · `Sources/tart/Fetcher.swift`
- [IPSW Cache](https://github.com/cirruslabs/tart/blob/main/Sources/tart/IPSWCache.swift): cache · Cached Apple firmware and installer images · `Sources/tart/IPSWCache.swift`
- [Layer Cache](https://github.com/cirruslabs/tart/blob/main/Sources/tart/LocalLayerCache.swift): cache · Local cache for OCI layers and reused artifacts · `Sources/tart/LocalLayerCache.swift`

### OCI Registry

Registry auth, manifests, references, and layerization

- [Auth](https://github.com/cirruslabs/tart/blob/main/Sources/tart/OCI/Authentication.swift): registry auth · Credential provider selection and authentication state · `Sources/tart/OCI/Authentication.swift`
- [Registry](https://github.com/cirruslabs/tart/blob/main/Sources/tart/OCI/Registry.swift): registry client · Registry operations, tokens, manifests, and remote names · `Sources/tart/OCI/Registry.swift`
- [Layerizer](https://github.com/cirruslabs/tart/tree/main/Sources/tart/OCI/Layerizer): layer packaging · Converts VM disk artifacts into OCI layers · `Sources/tart/OCI/Layerizer`

### Runtime

Networking, console access, and guest interaction

- [Network](https://github.com/cirruslabs/tart/tree/main/Sources/tart/Network): guest networking · Guest network setup and bridging abstractions · `Sources/tart/Network`
- [MAC Resolver](https://github.com/cirruslabs/tart/tree/main/Sources/tart/MACAddressResolver): identity lookup · Resolves guest identity via ARP, leases, and agents · `Sources/tart/MACAddressResolver`
- [Control Socket](https://github.com/cirruslabs/tart/blob/main/Sources/tart/ControlSocket.swift): control channel · Out-of-band guest control and exec coordination · `Sources/tart/ControlSocket.swift`
- [VNC](https://github.com/cirruslabs/tart/tree/main/Sources/tart/VNC): console access · Guest display and screen-sharing access paths · `Sources/tart/VNC`

### Support

Logging, platform abstraction, formatting, and environment helpers

- [Config](https://github.com/cirruslabs/tart/blob/main/Sources/tart/Config.swift): runtime config · Global configuration and shared options · `Sources/tart/Config.swift`
- [Logging](https://github.com/cirruslabs/tart/tree/main/Sources/tart/Logging): observability · CLI logging, progress reporting, and HTTP session logs · `Sources/tart/Logging`
- [Platform](https://github.com/cirruslabs/tart/tree/main/Sources/tart/Platform): abstraction layer · Darwin/Linux and architecture/environment abstraction · `Sources/tart/Platform`
- [Formatter](https://github.com/cirruslabs/tart/blob/main/Sources/tart/Formatter/Format.swift): output formatting · Human-facing output formatting helpers · `Sources/tart/Formatter/Format.swift`

### Verification

Unit tests, integration tests, and benchmarks

- [Tests](https://github.com/cirruslabs/tart/tree/main/Tests/TartTests): unit tests · Primary Swift test suite for core logic · `Tests/TartTests`
- [Integration](https://github.com/cirruslabs/tart/tree/main/integration-tests): cli harness · End-to-end tests for real CLI and registry flows · `integration-tests`
- [Benchmark](https://github.com/cirruslabs/tart/tree/main/benchmark): performance harness · Standalone benchmark tooling for VM throughput · `benchmark`

## Connections

- 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
