# utmapp/utm architecture

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

- Interactive diagram: https://gitdiagram.com/utmapp/utm
- Repository: https://github.com/utmapp/utm

## Overview

UTM is a system-emulation and virtual-machine host for Apple platforms, built around QEMU and Apple’s virtualization APIs. Users create or import a VM, configure its hardware, launch and interact with it, then manage its files, snapshots, and devices. The graph includes the shared VM catalog, both execution backends, platform display, and documented remote and automation capabilities. Edges reflect README statements or source-index references; unsampled subsystem wiring is not inferred.

Main entry points: [`Services/UTMQemuVirtualMachine.swift`](https://github.com/utmapp/utm/blob/main/Services/UTMQemuVirtualMachine.swift) (QEMU VM), [`Services/UTMAppleVirtualMachine.swift`](https://github.com/utmapp/utm/blob/main/Services/UTMAppleVirtualMachine.swift) (Apple VM), [`Platform/VMData.swift`](https://github.com/utmapp/utm/blob/main/Platform/VMData.swift) (VM Records), [`Services/UTMVirtualMachine.swift`](https://github.com/utmapp/utm/blob/main/Services/UTMVirtualMachine.swift) (VM Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and VM Catalog"]
  node_catalog["VM Catalog<br/>[UTMData.swift]"]
  node_vmdata["VM Records<br/>[VMData.swift]"]
  node_registry[("VM Registry<br/>[UTMRegistry.swift]")]
  node_registryentry["Registry Entry"]
end

subgraph group_config["VM Configuration"]
  node_configbase["Shared Configuration"]
  node_qemuconfig["QEMU Configuration"]
  node_appleconfig["Apple Configuration"]
end

subgraph group_runtime["VM Runtime"]
  node_vmprotocol["VM Lifecycle"]
  node_qemuvm["QEMU VM"]
  node_applevm["Apple VM"]
  node_spicevm["SPICE VM"]
  node_snapshots["Snapshot Service"]
  node_qemu{{"QEMU Engine<br/>[main.c]"}}
  node_appleframework{{"Apple Virtualization"}}
end

subgraph group_interaction["Guest Interaction"]
  node_display["VM Display"]
  node_qemudisplay["QEMU Display"]
  node_appledisplay["Apple Display"]
  node_usbmanager["Apple USB Manager"]
end

subgraph group_extensions["Remote and Automation"]
  node_remote["Remote Client"]
  node_scripting["Scripting API"]
end

node_user(("User"))

node_user -->|"creates and manages"| node_catalog
node_catalog -->|"wraps VMs"| node_vmdata
node_vmdata -->|"uses registry"| node_registry
node_vmdata -->|"uses backend"| node_qemuvm
node_vmdata -->|"uses backend"| node_applevm
node_registryentry -->|"tracks lifecycle"| node_vmprotocol
node_vmprotocol -->|"updates state"| node_registryentry
node_qemuconfig -->|"implements"| node_configbase
node_appleconfig -->|"implements"| node_configbase
node_qemuvm -->|"reads configuration"| node_qemuconfig
node_applevm -->|"reads configuration"| node_appleconfig
node_qemuvm -->|"uses SPICE"| node_spicevm
node_applevm -->|"uses snapshots"| node_snapshots
node_qemuvm -->|"uses snapshot manifest"| node_snapshots
node_user -->|"interacts with guest"| node_display
node_display -->|"controls VM"| node_vmprotocol
node_qemudisplay -->|"renders and inputs"| node_qemuvm
node_appledisplay -->|"controls display"| node_applevm
node_appledisplay -->|"queries devices"| node_usbmanager
node_applevm -->|"claims devices"| node_usbmanager
node_user -.->|"connects remotely"| node_remote
node_remote -.->|"uses remote VM"| node_spicevm
node_user -.->|"automates VM"| node_scripting
node_scripting -->|"accesses VM data"| node_vmdata
node_qemuvm -.->|"launches engine"| node_qemu
node_applevm -.->|"runs guest"| node_appleframework

click node_catalog "https://github.com/utmapp/utm/blob/main/Platform/UTMData.swift"
click node_vmdata "https://github.com/utmapp/utm/blob/main/Platform/VMData.swift"
click node_registry "https://github.com/utmapp/utm/blob/main/Services/UTMRegistry.swift"
click node_registryentry "https://github.com/utmapp/utm/blob/main/Services/UTMRegistryEntry.swift"
click node_configbase "https://github.com/utmapp/utm/blob/main/Configuration/UTMConfiguration.swift"
click node_qemuconfig "https://github.com/utmapp/utm/blob/main/Configuration/UTMQemuConfiguration.swift"
click node_appleconfig "https://github.com/utmapp/utm/blob/main/Configuration/UTMAppleConfiguration.swift"
click node_vmprotocol "https://github.com/utmapp/utm/blob/main/Services/UTMVirtualMachine.swift"
click node_qemuvm "https://github.com/utmapp/utm/blob/main/Services/UTMQemuVirtualMachine.swift"
click node_applevm "https://github.com/utmapp/utm/blob/main/Services/UTMAppleVirtualMachine.swift"
click node_spicevm "https://github.com/utmapp/utm/blob/main/Services/UTMSpiceVirtualMachine.swift"
click node_snapshots "https://github.com/utmapp/utm/blob/main/Services/UTMSnapshotService.swift"
click node_display "https://github.com/utmapp/utm/blob/main/Platform/macOS/Display/VMDisplayWindow.swift"
click node_qemudisplay "https://github.com/utmapp/utm/blob/main/Platform/macOS/Display/VMDisplayQemuDisplayController.swift"
click node_appledisplay "https://github.com/utmapp/utm/blob/main/Platform/macOS/Display/VMDisplayAppleWindowController.swift"
click node_usbmanager "https://github.com/utmapp/utm/blob/main/Services/UTMAppleUSBManager.swift"
click node_remote "https://github.com/utmapp/utm/blob/main/Remote/UTMRemoteClient.swift"
click node_scripting "https://github.com/utmapp/utm/blob/main/Scripting/UTMScriptingVirtualMachineImpl.swift"
click node_qemu "https://github.com/utmapp/utm/blob/main/QEMULauncher/main.c"

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_catalog,node_vmdata,node_registry,node_registryentry,node_user toneBlue
class node_configbase,node_qemuconfig,node_appleconfig toneAmber
class node_vmprotocol,node_qemuvm,node_applevm,node_spicevm,node_snapshots,node_qemu,node_appleframework toneMint
class node_display,node_qemudisplay,node_appledisplay,node_usbmanager toneRose
class node_remote,node_scripting toneIndigo
```

## Components

### App and VM Catalog

- [VM Catalog](https://github.com/utmapp/utm/blob/main/Platform/UTMData.swift): `Platform/UTMData.swift`
- [VM Records](https://github.com/utmapp/utm/blob/main/Platform/VMData.swift): `Platform/VMData.swift`
- [VM Registry](https://github.com/utmapp/utm/blob/main/Services/UTMRegistry.swift): `Services/UTMRegistry.swift`
- [Registry Entry](https://github.com/utmapp/utm/blob/main/Services/UTMRegistryEntry.swift): `Services/UTMRegistryEntry.swift`

### VM Configuration

- [Shared Configuration](https://github.com/utmapp/utm/blob/main/Configuration/UTMConfiguration.swift): `Configuration/UTMConfiguration.swift`
- [QEMU Configuration](https://github.com/utmapp/utm/blob/main/Configuration/UTMQemuConfiguration.swift): `Configuration/UTMQemuConfiguration.swift`
- [Apple Configuration](https://github.com/utmapp/utm/blob/main/Configuration/UTMAppleConfiguration.swift): `Configuration/UTMAppleConfiguration.swift`

### VM Runtime

- [VM Lifecycle](https://github.com/utmapp/utm/blob/main/Services/UTMVirtualMachine.swift): `Services/UTMVirtualMachine.swift`
- [QEMU VM](https://github.com/utmapp/utm/blob/main/Services/UTMQemuVirtualMachine.swift): `Services/UTMQemuVirtualMachine.swift`
- [Apple VM](https://github.com/utmapp/utm/blob/main/Services/UTMAppleVirtualMachine.swift): `Services/UTMAppleVirtualMachine.swift`
- [SPICE VM](https://github.com/utmapp/utm/blob/main/Services/UTMSpiceVirtualMachine.swift): `Services/UTMSpiceVirtualMachine.swift`
- [Snapshot Service](https://github.com/utmapp/utm/blob/main/Services/UTMSnapshotService.swift): `Services/UTMSnapshotService.swift`
- [QEMU Engine](https://github.com/utmapp/utm/blob/main/QEMULauncher/main.c): `QEMULauncher/main.c`
- **Apple Virtualization**

### Guest Interaction

- [VM Display](https://github.com/utmapp/utm/blob/main/Platform/macOS/Display/VMDisplayWindow.swift): `Platform/macOS/Display/VMDisplayWindow.swift`
- [QEMU Display](https://github.com/utmapp/utm/blob/main/Platform/macOS/Display/VMDisplayQemuDisplayController.swift): `Platform/macOS/Display/VMDisplayQemuDisplayController.swift`
- [Apple Display](https://github.com/utmapp/utm/blob/main/Platform/macOS/Display/VMDisplayAppleWindowController.swift): `Platform/macOS/Display/VMDisplayAppleWindowController.swift`
- [Apple USB Manager](https://github.com/utmapp/utm/blob/main/Services/UTMAppleUSBManager.swift): `Services/UTMAppleUSBManager.swift`

### Remote and Automation

- [Remote Client](https://github.com/utmapp/utm/blob/main/Remote/UTMRemoteClient.swift): `Remote/UTMRemoteClient.swift`
- [Scripting API](https://github.com/utmapp/utm/blob/main/Scripting/UTMScriptingVirtualMachineImpl.swift): `Scripting/UTMScriptingVirtualMachineImpl.swift`

### Other components

- **User**

## Connections

- User → VM Catalog: creates and manages
- VM Catalog → VM Records: wraps VMs (evidence: `Platform/UTMData.swift`)
- VM Records → VM Registry: uses registry (evidence: `Platform/VMData.swift`)
- VM Records → QEMU VM: uses backend (evidence: `Platform/VMData.swift`)
- VM Records → Apple VM: uses backend (evidence: `Platform/VMData.swift`)
- Registry Entry → VM Lifecycle: tracks lifecycle (evidence: `Services/UTMRegistryEntry.swift`)
- VM Lifecycle → Registry Entry: updates state (evidence: `Services/UTMVirtualMachine.swift`)
- QEMU Configuration → Shared Configuration: implements (evidence: `Configuration/UTMQemuConfiguration.swift`)
- Apple Configuration → Shared Configuration: implements (evidence: `Configuration/UTMAppleConfiguration.swift`)
- QEMU VM → QEMU Configuration: reads configuration (evidence: `Services/UTMQemuVirtualMachine.swift`)
- Apple VM → Apple Configuration: reads configuration (evidence: `Services/UTMAppleVirtualMachine.swift`)
- QEMU VM → SPICE VM: uses SPICE (evidence: `Services/UTMQemuVirtualMachine.swift`)
- Apple VM → Snapshot Service: uses snapshots (evidence: `Services/UTMAppleVirtualMachine.swift`)
- QEMU VM → Snapshot Service: uses snapshot manifest (evidence: `Services/UTMQemuVirtualMachine.swift`)
- User → VM Display: interacts with guest
- VM Display → VM Lifecycle: controls VM (evidence: `Platform/macOS/Display/VMDisplayWindowController.swift`)
- QEMU Display → QEMU VM: renders and inputs (evidence: `Platform/macOS/Display/VMDisplayQemuDisplayController.swift`)
- Apple Display → Apple VM: controls display (evidence: `Platform/macOS/Display/VMDisplayAppleWindowController.swift`)
- Apple Display → Apple USB Manager: queries devices (evidence: `Platform/macOS/Display/VMDisplayAppleWindowController.swift`)
- Apple VM → Apple USB Manager: claims devices (evidence: `Services/UTMAppleVirtualMachine.swift`)
- User → Remote Client: connects remotely
- Remote Client → SPICE VM: uses remote VM (evidence: `Platform/UTMData.swift`)
- User → Scripting API: automates VM
- Scripting API → VM Records: accesses VM data (evidence: `Scripting/UTMScriptingVirtualMachineImpl.swift`)
- QEMU VM → QEMU Engine: launches engine
- Apple VM → Apple Virtualization: runs guest
