# openai/tart architecture

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

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

## Overview

Tart is a macOS-on-Apple-Silicon virtualization toolset for creating, running, and managing macOS and Linux VMs, including use in CI. The main user workflow is to obtain or clone a VM image, store it locally, and run it through Apple’s Virtualization framework; VM configuration and platform-specific setup support that runtime. Separate command capabilities manage VM lifecycle, export/import, and OCI registry exchange. Relationships reflect README statements and source-index references or excerpts; several command and storage details are not sampled, so uncertain links are omitted.

Main entry points: [`Sources/tart/Commands/Run.swift`](https://github.com/openai/tart/blob/main/Sources/tart/Commands/Run.swift) (Run command), [`Sources/tart/VMStorageOCI.swift`](https://github.com/openai/tart/blob/main/Sources/tart/VMStorageOCI.swift) (OCI VM storage), [`Sources/tart/VMStorageLocal.swift`](https://github.com/openai/tart/blob/main/Sources/tart/VMStorageLocal.swift) (Local VM storage), [`Sources/tart/VMConfig.swift`](https://github.com/openai/tart/blob/main/Sources/tart/VMConfig.swift) (VM configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_commands["VM commands"]
  node_run["Run command<br/>[Run.swift]"]
  node_set["Set command<br/>[Set.swift]"]
  node_prune["Prune command<br/>[Prune.swift]"]
end

subgraph group_vm["VM runtime"]
  node_config["Tart config<br/>[Config.swift]"]
  node_vmconfig["VM configuration<br/>[VMConfig.swift]"]
  node_darwin["macOS platform<br/>[Darwin.swift]"]
  node_linux["Linux platform<br/>[Linux.swift]"]
  node_vmruntime["Virtual machine<br/>[VM.swift]"]
  node_network["VM networking"]
  node_softnet["Softnet backend<br/>[Softnet.swift]"]
  node_vnc["VNC display"]
end

subgraph group_storage["VM and image storage"]
  node_localstorage[("Local VM storage")]
  node_ocistorage[("OCI VM storage<br/>[VMStorageOCI.swift]")]
  node_vmhelper["Storage dispatch"]
  node_vmdir["VM directory<br/>[VMDirectory.swift]"]
  node_content[("Content store<br/>[ContentStore.swift]")]
  node_layercache[("Local layer cache")]
end

subgraph group_registry["OCI exchange"]
  node_oci["OCI registry client<br/>[Registry.swift]"]
  node_remote["Remote image names<br/>[RemoteName.swift]"]
  node_digest["Image digests<br/>[Digest.swift]"]
  node_layerizer["Disk layerizer<br/>[DiskV2.swift]"]
end

node_user(("User / CI"))
node_registry_service[("OCI-compatible registry")]

node_user -->|"manages VMs"| node_commands
node_user -->|"runs VM"| node_run
node_run -->|"configures"| node_vmconfig
node_run -->|"opens VM"| node_localstorage
node_run -->|"selects platform"| node_darwin
node_run -->|"selects platform"| node_linux
node_run -->|"configures networking"| node_network
node_run -->|"starts backend"| node_softnet
node_run -->|"configures display"| node_vnc
node_vmconfig -->|"decodes platform"| node_darwin
node_vmconfig -->|"decodes platform"| node_linux
node_set -->|"updates config"| node_vmconfig
node_set -->|"opens VM"| node_localstorage
node_localstorage -->|"opens directory"| node_vmdir
node_ocistorage -->|"materializes VM"| node_vmdir
node_ocistorage -->|"pulls and pushes"| node_oci
node_ocistorage -->|"resolves names"| node_remote
node_ocistorage -->|"uses shared content"| node_content
node_ocistorage -->|"uses layer cache"| node_layercache
node_vmhelper -->|"dispatches local"| node_localstorage
node_vmhelper -->|"dispatches remote"| node_ocistorage
node_vmdir -->|"uses content store"| node_content
node_oci -->|"uses digests"| node_digest
node_layerizer -->|"transfers layers"| node_oci
node_layerizer -->|"computes digests"| node_digest
node_layerizer -->|"uses layer cache"| node_layercache
node_oci -.->|"exchanges images"| node_registry_service
node_prune -->|"prunes local VMs"| node_localstorage
node_prune -->|"prunes remote cache"| node_ocistorage
node_config -->|"cleans temporary VMs"| node_vmdir

click node_commands "https://github.com/openai/tart/tree/main/Sources/tart/Commands"
click node_run "https://github.com/openai/tart/blob/main/Sources/tart/Commands/Run.swift"
click node_set "https://github.com/openai/tart/blob/main/Sources/tart/Commands/Set.swift"
click node_prune "https://github.com/openai/tart/blob/main/Sources/tart/Commands/Prune.swift"
click node_config "https://github.com/openai/tart/blob/main/Sources/tart/Config.swift"
click node_vmconfig "https://github.com/openai/tart/blob/main/Sources/tart/VMConfig.swift"
click node_darwin "https://github.com/openai/tart/blob/main/Sources/tart/Platform/Darwin.swift"
click node_linux "https://github.com/openai/tart/blob/main/Sources/tart/Platform/Linux.swift"
click node_vmruntime "https://github.com/openai/tart/blob/main/Sources/tart/VM.swift"
click node_network "https://github.com/openai/tart/tree/main/Sources/tart/Network"
click node_softnet "https://github.com/openai/tart/blob/main/Sources/tart/Network/Softnet.swift"
click node_vnc "https://github.com/openai/tart/tree/main/Sources/tart/VNC"
click node_localstorage "https://github.com/openai/tart/blob/main/Sources/tart/VMStorageLocal.swift"
click node_ocistorage "https://github.com/openai/tart/blob/main/Sources/tart/VMStorageOCI.swift"
click node_vmhelper "https://github.com/openai/tart/blob/main/Sources/tart/VMStorageHelper.swift"
click node_vmdir "https://github.com/openai/tart/blob/main/Sources/tart/VMDirectory.swift"
click node_content "https://github.com/openai/tart/blob/main/Sources/tart/ContentStore.swift"
click node_layercache "https://github.com/openai/tart/blob/main/Sources/tart/LocalLayerCache.swift"
click node_oci "https://github.com/openai/tart/blob/main/Sources/tart/OCI/Registry.swift"
click node_remote "https://github.com/openai/tart/blob/main/Sources/tart/OCI/RemoteName.swift"
click node_digest "https://github.com/openai/tart/blob/main/Sources/tart/OCI/Digest.swift"
click node_layerizer "https://github.com/openai/tart/blob/main/Sources/tart/OCI/Layerizer/DiskV2.swift"

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_commands,node_run,node_set,node_prune,node_user toneBlue
class node_config,node_vmconfig,node_darwin,node_linux,node_vmruntime,node_network,node_softnet,node_vnc,node_registry_service toneAmber
class node_localstorage,node_ocistorage,node_vmhelper,node_vmdir,node_content,node_layercache toneMint
class node_oci,node_remote,node_digest,node_layerizer toneRose
```

## Components

### CLI workflows

- [VM commands](https://github.com/openai/tart/tree/main/Sources/tart/Commands): `Sources/tart/Commands`
- [Run command](https://github.com/openai/tart/blob/main/Sources/tart/Commands/Run.swift): `Sources/tart/Commands/Run.swift`
- [Set command](https://github.com/openai/tart/blob/main/Sources/tart/Commands/Set.swift): `Sources/tart/Commands/Set.swift`
- [Prune command](https://github.com/openai/tart/blob/main/Sources/tart/Commands/Prune.swift): `Sources/tart/Commands/Prune.swift`

### VM runtime

- [Tart config](https://github.com/openai/tart/blob/main/Sources/tart/Config.swift): `Sources/tart/Config.swift`
- [VM configuration](https://github.com/openai/tart/blob/main/Sources/tart/VMConfig.swift): `Sources/tart/VMConfig.swift`
- [macOS platform](https://github.com/openai/tart/blob/main/Sources/tart/Platform/Darwin.swift): `Sources/tart/Platform/Darwin.swift`
- [Linux platform](https://github.com/openai/tart/blob/main/Sources/tart/Platform/Linux.swift): `Sources/tart/Platform/Linux.swift`
- [Virtual machine](https://github.com/openai/tart/blob/main/Sources/tart/VM.swift): `Sources/tart/VM.swift`
- [VM networking](https://github.com/openai/tart/tree/main/Sources/tart/Network): `Sources/tart/Network`
- [Softnet backend](https://github.com/openai/tart/blob/main/Sources/tart/Network/Softnet.swift): `Sources/tart/Network/Softnet.swift`
- [VNC display](https://github.com/openai/tart/tree/main/Sources/tart/VNC): `Sources/tart/VNC`

### VM and image storage

- [Local VM storage](https://github.com/openai/tart/blob/main/Sources/tart/VMStorageLocal.swift): `Sources/tart/VMStorageLocal.swift`
- [OCI VM storage](https://github.com/openai/tart/blob/main/Sources/tart/VMStorageOCI.swift): `Sources/tart/VMStorageOCI.swift`
- [Storage dispatch](https://github.com/openai/tart/blob/main/Sources/tart/VMStorageHelper.swift): `Sources/tart/VMStorageHelper.swift`
- [VM directory](https://github.com/openai/tart/blob/main/Sources/tart/VMDirectory.swift): `Sources/tart/VMDirectory.swift`
- [Content store](https://github.com/openai/tart/blob/main/Sources/tart/ContentStore.swift): `Sources/tart/ContentStore.swift`
- [Local layer cache](https://github.com/openai/tart/blob/main/Sources/tart/LocalLayerCache.swift): `Sources/tart/LocalLayerCache.swift`

### OCI exchange

- [OCI registry client](https://github.com/openai/tart/blob/main/Sources/tart/OCI/Registry.swift): `Sources/tart/OCI/Registry.swift`
- [Remote image names](https://github.com/openai/tart/blob/main/Sources/tart/OCI/RemoteName.swift): `Sources/tart/OCI/RemoteName.swift`
- [Image digests](https://github.com/openai/tart/blob/main/Sources/tart/OCI/Digest.swift): `Sources/tart/OCI/Digest.swift`
- [Disk layerizer](https://github.com/openai/tart/blob/main/Sources/tart/OCI/Layerizer/DiskV2.swift): `Sources/tart/OCI/Layerizer/DiskV2.swift`

### Other components

- **User / CI**
- **OCI-compatible registry**

## Connections

- User / CI → VM commands: manages VMs
- User / CI → Run command: runs VM
- Run command → VM configuration: configures (evidence: `Sources/tart/Commands/Run.swift`)
- Run command → Local VM storage: opens VM (evidence: `Sources/tart/Commands/Run.swift`)
- Run command → macOS platform: selects platform (evidence: `Sources/tart/Commands/Run.swift`)
- Run command → Linux platform: selects platform (evidence: `Sources/tart/Commands/Run.swift`)
- Run command → VM networking: configures networking (evidence: `Sources/tart/Commands/Run.swift`)
- Run command → Softnet backend: starts backend (evidence: `Sources/tart/Commands/Run.swift`)
- Run command → VNC display: configures display (evidence: `Sources/tart/Commands/Run.swift`)
- VM configuration → macOS platform: decodes platform (evidence: `Sources/tart/VMConfig.swift`)
- VM configuration → Linux platform: decodes platform (evidence: `Sources/tart/VMConfig.swift`)
- Set command → VM configuration: updates config (evidence: `Sources/tart/Commands/Set.swift`)
- Set command → Local VM storage: opens VM (evidence: `Sources/tart/Commands/Set.swift`)
- Local VM storage → VM directory: opens directory (evidence: `Sources/tart/VMStorageLocal.swift`)
- OCI VM storage → VM directory: materializes VM (evidence: `Sources/tart/VMStorageOCI.swift`)
- OCI VM storage → OCI registry client: pulls and pushes (evidence: `Sources/tart/VMStorageOCI.swift`)
- OCI VM storage → Remote image names: resolves names (evidence: `Sources/tart/VMStorageOCI.swift`)
- OCI VM storage → Content store: uses shared content (evidence: `Sources/tart/VMStorageOCI.swift`)
- OCI VM storage → Local layer cache: uses layer cache (evidence: `Sources/tart/VMStorageOCI.swift`)
- Storage dispatch → Local VM storage: dispatches local (evidence: `Sources/tart/VMStorageHelper.swift`)
- Storage dispatch → OCI VM storage: dispatches remote (evidence: `Sources/tart/VMStorageHelper.swift`)
- VM directory → Content store: uses content store (evidence: `Sources/tart/VMDirectory.swift`)
- OCI registry client → Image digests: uses digests (evidence: `Sources/tart/OCI/Registry.swift`)
- Disk layerizer → OCI registry client: transfers layers (evidence: `Sources/tart/OCI/Layerizer/DiskV2.swift`)
- Disk layerizer → Image digests: computes digests (evidence: `Sources/tart/OCI/Layerizer/DiskV2.swift`)
- Disk layerizer → Local layer cache: uses layer cache (evidence: `Sources/tart/OCI/Layerizer/DiskV2.swift`)
- OCI registry client → OCI-compatible registry: exchanges images
- Prune command → Local VM storage: prunes local VMs (evidence: `Sources/tart/Commands/Prune.swift`)
- Prune command → OCI VM storage: prunes remote cache (evidence: `Sources/tart/Commands/Prune.swift`)
- Tart config → VM directory: cleans temporary VMs (evidence: `Sources/tart/Config.swift`)
