# kholia/osx-kvm architecture

> Architecture diagram of the GitHub repository kholia/osx-kvm, 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/kholia/osx-kvm
- Repository: https://github.com/kholia/osx-kvm

## Overview

OSX-KVM provides a QEMU/KVM-based macOS installation and virtual-machine setup. The documented main workflow fetches a macOS recovery image, converts it, creates a virtual disk, and starts the installer through the OpenCore boot script; users then install macOS in the VM. The repository also includes boot variants, an OpenCore EFI bundle, and binary-patching utilities. Edges reflect README-documented actions; the sampled sources do not show how the boot scripts configure QEMU or how EFI components are dispatched.

Main entry points: [`OpenCore/EFI/OC/OpenCore.efi`](https://github.com/kholia/osx-kvm/blob/master/OpenCore/EFI/OC/OpenCore.efi) (OpenCore core), [`OpenCore-Boot.sh`](https://github.com/kholia/osx-kvm/blob/master/OpenCore-Boot.sh) (OpenCore boot), [`fetch-macOS-v2.py`](https://github.com/kholia/osx-kvm/blob/master/fetch-macOS-v2.py) (Recovery fetcher), [`OpenCore/EFI/BOOT/BOOTx64.efi`](https://github.com/kholia/osx-kvm/blob/master/OpenCore/EFI/BOOT/BOOTx64.efi) (EFI bootloader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Image preparation"]
  node_fetch["Recovery fetcher<br/>[fetch-macOS-v2.py]"]
  node_recovery["Recovery image"]
  node_converter["DMG converter"]
  node_disk["Virtual disk"]
end

subgraph group_boot["Boot and firmware"]
  node_bootcli["OpenCore boot<br/>[OpenCore-Boot.sh]"]
  node_bootmac["macOS boot variant"]
  node_bootcd["Boot CD variant"]
  node_efi["EFI bootloader<br/>[BOOTx64.efi]"]
  node_opencore["OpenCore core<br/>[OpenCore.efi]"]
  node_acpi["ACPI tables"]
  node_drivers["UEFI drivers"]
  node_kexts["macOS extensions"]
  node_resources["Boot UI resources"]
end

subgraph group_vm["Virtual machine"]
  node_qemu["QEMU / KVM"]
  node_macos["macOS installer / VM"]
end

subgraph group_patch["Binary patching"]
  node_kernelpatch["Kernel autopatcher"]
  node_idadif["IDA diff patcher<br/>[idadif.py]"]
end

node_user(("VM operator"))

node_user -->|"selects version"| node_fetch
node_fetch -->|"downloads"| node_recovery
node_user -->|"converts image"| node_converter
node_recovery -->|"input image"| node_converter
node_converter -->|"prepares installer"| node_disk
node_user -->|"creates disk"| node_disk
node_user -->|"starts install"| node_bootcli
node_bootcli -->|"launches VM"| node_qemu
node_qemu -->|"runs installer"| node_macos
node_user -.->|"starts boot"| node_bootmac
node_user -.->|"starts boot"| node_bootcd
node_bootcli -.->|"loads EFI"| node_efi
node_efi -.->|"dispatches to"| node_opencore
node_opencore -.->|"uses tables"| node_acpi
node_opencore -.->|"loads drivers"| node_drivers
node_opencore -.->|"loads extensions"| node_kexts
node_opencore -.->|"uses resources"| node_resources
node_user -->|"patches kernel"| node_kernelpatch
node_user -->|"patches binary"| node_idadif

click node_fetch "https://github.com/kholia/osx-kvm/blob/master/fetch-macOS-v2.py"
click node_bootcli "https://github.com/kholia/osx-kvm/blob/master/OpenCore-Boot.sh"
click node_bootmac "https://github.com/kholia/osx-kvm/blob/master/OpenCore-Boot-macOS.sh"
click node_bootcd "https://github.com/kholia/osx-kvm/blob/master/OpenCore-Boot-CD.sh"
click node_efi "https://github.com/kholia/osx-kvm/blob/master/OpenCore/EFI/BOOT/BOOTx64.efi"
click node_opencore "https://github.com/kholia/osx-kvm/blob/master/OpenCore/EFI/OC/OpenCore.efi"
click node_acpi "https://github.com/kholia/osx-kvm/tree/master/OpenCore/EFI/OC/ACPI"
click node_drivers "https://github.com/kholia/osx-kvm/tree/master/OpenCore/EFI/OC/Drivers"
click node_kexts "https://github.com/kholia/osx-kvm/tree/master/OpenCore/EFI/OC/Kexts"
click node_resources "https://github.com/kholia/osx-kvm/tree/master/OpenCore/EFI/OC/Resources"
click node_kernelpatch "https://github.com/kholia/osx-kvm/blob/master/resources/kernel_autopatcher.py"
click node_idadif "https://github.com/kholia/osx-kvm/blob/master/resources/idadif.py"

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_fetch,node_recovery,node_converter,node_disk toneBlue
class node_bootcli,node_bootmac,node_bootcd,node_efi,node_opencore,node_acpi,node_drivers,node_kexts,node_resources toneAmber
class node_qemu,node_macos toneMint
class node_kernelpatch,node_idadif toneRose
class node_user toneIndigo
```

## Components

### Image preparation

- [Recovery fetcher](https://github.com/kholia/osx-kvm/blob/master/fetch-macOS-v2.py): `fetch-macOS-v2.py`
- **Recovery image**
- **DMG converter**
- **Virtual disk**

### Boot and firmware

- [OpenCore boot](https://github.com/kholia/osx-kvm/blob/master/OpenCore-Boot.sh): `OpenCore-Boot.sh`
- [macOS boot variant](https://github.com/kholia/osx-kvm/blob/master/OpenCore-Boot-macOS.sh): `OpenCore-Boot-macOS.sh`
- [Boot CD variant](https://github.com/kholia/osx-kvm/blob/master/OpenCore-Boot-CD.sh): `OpenCore-Boot-CD.sh`
- [EFI bootloader](https://github.com/kholia/osx-kvm/blob/master/OpenCore/EFI/BOOT/BOOTx64.efi): `OpenCore/EFI/BOOT/BOOTx64.efi`
- [OpenCore core](https://github.com/kholia/osx-kvm/blob/master/OpenCore/EFI/OC/OpenCore.efi): `OpenCore/EFI/OC/OpenCore.efi`
- [ACPI tables](https://github.com/kholia/osx-kvm/tree/master/OpenCore/EFI/OC/ACPI): `OpenCore/EFI/OC/ACPI`
- [UEFI drivers](https://github.com/kholia/osx-kvm/tree/master/OpenCore/EFI/OC/Drivers): `OpenCore/EFI/OC/Drivers`
- [macOS extensions](https://github.com/kholia/osx-kvm/tree/master/OpenCore/EFI/OC/Kexts): `OpenCore/EFI/OC/Kexts`
- [Boot UI resources](https://github.com/kholia/osx-kvm/tree/master/OpenCore/EFI/OC/Resources): `OpenCore/EFI/OC/Resources`

### Virtual machine

- **QEMU / KVM**
- **macOS installer / VM**

### Binary patching

- [Kernel autopatcher](https://github.com/kholia/osx-kvm/blob/master/resources/kernel_autopatcher.py): `resources/kernel_autopatcher.py`
- [IDA diff patcher](https://github.com/kholia/osx-kvm/blob/master/resources/idadif.py): `resources/idadif.py`

### Other components

- **VM operator**

## Connections

- VM operator → Recovery fetcher: selects version (evidence: `README.md`)
- Recovery fetcher → Recovery image: downloads (evidence: `README.md`)
- VM operator → DMG converter: converts image (evidence: `README.md`)
- Recovery image → DMG converter: input image (evidence: `README.md`)
- DMG converter → Virtual disk: prepares installer (evidence: `README.md`)
- VM operator → Virtual disk: creates disk (evidence: `README.md`)
- VM operator → OpenCore boot: starts install (evidence: `README.md`)
- OpenCore boot → QEMU / KVM: launches VM (evidence: `README.md`)
- QEMU / KVM → macOS installer / VM: runs installer (evidence: `README.md`)
- VM operator → macOS boot variant: starts boot
- VM operator → Boot CD variant: starts boot
- OpenCore boot → EFI bootloader: loads EFI
- EFI bootloader → OpenCore core: dispatches to
- OpenCore core → ACPI tables: uses tables
- OpenCore core → UEFI drivers: loads drivers
- OpenCore core → macOS extensions: loads extensions
- OpenCore core → Boot UI resources: uses resources
- VM operator → Kernel autopatcher: patches kernel (evidence: `resources/kernel_autopatcher.py`)
- VM operator → IDA diff patcher: patches binary (evidence: `resources/idadif.py`)