# luchina-gabriel/osx-proxmox architecture

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

- Interactive diagram: https://gitdiagram.com/luchina-gabriel/osx-proxmox
- Repository: https://github.com/luchina-gabriel/osx-proxmox

## Overview

OSX-PROXMOX is a Proxmox setup for running macOS VMs on Intel or AMD hardware. The documented user journey starts in the Proxmox shell, runs the installer, and proceeds to install macOS; the repository also supplies OpenCore EFI profiles, patches, host reports, and a macOS recovery-download utility. The README establishes the product capabilities, but installer and setup source was not excerpted, so their internal handoffs are shown only as unverified dashed links. The sampled recovery code supports the utility’s request, download, and verification relationships.

Main entry points: [`setup`](https://github.com/luchina-gabriel/osx-proxmox/blob/main/setup) (VM Setup), [`tools/macrecovery/macrecovery.py`](https://github.com/luchina-gabriel/osx-proxmox/blob/main/tools/macrecovery/macrecovery.py) (Recovery CLI), [`install.sh`](https://github.com/luchina-gabriel/osx-proxmox/blob/main/install.sh) (Installer), [`EFI/Source/EFI-Nvidia-HS/EFI/OC/config.plist`](https://github.com/luchina-gabriel/osx-proxmox/blob/main/EFI/Source/EFI-Nvidia-HS/EFI/OC/config.plist) (NVIDIA Profile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Proxmox Setup"]
  node_installer["Installer<br/>[install.sh]"]
  node_setup_flow["VM Setup"]
end

subgraph group_boot["EFI Boot Profiles"]
  node_nvidia_profile["NVIDIA Profile<br/>[config.plist]"]
  node_vm_profile["VM Profile"]
  node_pikera_on["Pikera Enabled"]
  node_pikera_off["Pikera Disabled"]
  node_opencore["OpenCore Bootloader<br/>[OpenCore.efi]"]
end

subgraph group_recovery["Recovery Utility"]
  node_recovery_cli["Recovery CLI<br/>[macrecovery.py]"]
  node_apple_recovery["Apple Recovery Service"]
  node_recovery_download["Image Download<br/>[macrecovery.py]"]
  node_chunk_verify["Chunk Verification<br/>[macrecovery.py]"]
  node_recovery_files[("Recovery Images")]
end

subgraph group_support["Patches and Reports"]
  node_host_reports["Proxmox Reports"]
  node_vm_patches["VM Patches"]
end

node_operator(("Proxmox Operator"))
node_proxmox["Proxmox VE"]

node_operator -.->|"runs"| node_installer
node_installer -.->|"hands off"| node_setup_flow
node_setup_flow -.->|"configures"| node_proxmox
node_setup_flow -.->|"selects"| node_nvidia_profile
node_setup_flow -.->|"selects"| node_vm_profile
node_setup_flow -.->|"selects"| node_pikera_on
node_setup_flow -.->|"selects"| node_pikera_off
node_nvidia_profile -.->|"configures"| node_opencore
node_operator -.->|"invokes"| node_recovery_cli
node_recovery_cli -->|"requests metadata"| node_apple_recovery
node_recovery_cli -->|"starts download"| node_recovery_download
node_recovery_download -->|"fetches image"| node_apple_recovery
node_recovery_download -->|"writes image"| node_recovery_files
node_recovery_cli -->|"verifies image"| node_chunk_verify
node_chunk_verify -->|"reads image"| node_recovery_files
node_operator -.->|"consults"| node_host_reports
node_operator -.->|"applies"| node_vm_patches

click node_installer "https://github.com/luchina-gabriel/osx-proxmox/blob/main/install.sh"
click node_setup_flow "https://github.com/luchina-gabriel/osx-proxmox/blob/main/setup"
click node_nvidia_profile "https://github.com/luchina-gabriel/osx-proxmox/blob/main/EFI/Source/EFI-Nvidia-HS/EFI/OC/config.plist"
click node_vm_profile "https://github.com/luchina-gabriel/osx-proxmox/tree/main/EFI/Source/EFI-VirtualMachine-Only"
click node_pikera_on "https://github.com/luchina-gabriel/osx-proxmox/tree/main/EFI/Source/EFI-pikera-ON"
click node_pikera_off "https://github.com/luchina-gabriel/osx-proxmox/tree/main/EFI/Source/EFI-pikera-OFF"
click node_opencore "https://github.com/luchina-gabriel/osx-proxmox/blob/main/EFI/Source/EFI-Nvidia-HS/EFI/OC/OpenCore.efi"
click node_recovery_cli "https://github.com/luchina-gabriel/osx-proxmox/blob/main/tools/macrecovery/macrecovery.py"
click node_recovery_download "https://github.com/luchina-gabriel/osx-proxmox/blob/main/tools/macrecovery/macrecovery.py"
click node_chunk_verify "https://github.com/luchina-gabriel/osx-proxmox/blob/main/tools/macrecovery/macrecovery.py"
click node_host_reports "https://github.com/luchina-gabriel/osx-proxmox/tree/main/Artefacts"
click node_vm_patches "https://github.com/luchina-gabriel/osx-proxmox/tree/main/Patches"

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_installer,node_setup_flow toneBlue
class node_nvidia_profile,node_vm_profile,node_pikera_on,node_pikera_off,node_opencore toneAmber
class node_recovery_cli,node_apple_recovery,node_recovery_download,node_chunk_verify,node_recovery_files toneMint
class node_host_reports,node_vm_patches toneRose
class node_operator,node_proxmox toneIndigo
```

## Components

### Proxmox Setup

- [Installer](https://github.com/luchina-gabriel/osx-proxmox/blob/main/install.sh): `install.sh`
- [VM Setup](https://github.com/luchina-gabriel/osx-proxmox/blob/main/setup): `setup`

### EFI Boot Profiles

- [NVIDIA Profile](https://github.com/luchina-gabriel/osx-proxmox/blob/main/EFI/Source/EFI-Nvidia-HS/EFI/OC/config.plist): `EFI/Source/EFI-Nvidia-HS/EFI/OC/config.plist`
- [VM Profile](https://github.com/luchina-gabriel/osx-proxmox/tree/main/EFI/Source/EFI-VirtualMachine-Only): `EFI/Source/EFI-VirtualMachine-Only`
- [Pikera Enabled](https://github.com/luchina-gabriel/osx-proxmox/tree/main/EFI/Source/EFI-pikera-ON): `EFI/Source/EFI-pikera-ON`
- [Pikera Disabled](https://github.com/luchina-gabriel/osx-proxmox/tree/main/EFI/Source/EFI-pikera-OFF): `EFI/Source/EFI-pikera-OFF`
- [OpenCore Bootloader](https://github.com/luchina-gabriel/osx-proxmox/blob/main/EFI/Source/EFI-Nvidia-HS/EFI/OC/OpenCore.efi): `EFI/Source/EFI-Nvidia-HS/EFI/OC/OpenCore.efi`

### Recovery Utility

- [Recovery CLI](https://github.com/luchina-gabriel/osx-proxmox/blob/main/tools/macrecovery/macrecovery.py): `tools/macrecovery/macrecovery.py`
- **Apple Recovery Service**
- [Image Download](https://github.com/luchina-gabriel/osx-proxmox/blob/main/tools/macrecovery/macrecovery.py): `tools/macrecovery/macrecovery.py`
- [Chunk Verification](https://github.com/luchina-gabriel/osx-proxmox/blob/main/tools/macrecovery/macrecovery.py): `tools/macrecovery/macrecovery.py`
- **Recovery Images**

### Patches and Reports

- [Proxmox Reports](https://github.com/luchina-gabriel/osx-proxmox/tree/main/Artefacts): `Artefacts`
- [VM Patches](https://github.com/luchina-gabriel/osx-proxmox/tree/main/Patches): `Patches`

### Other components

- **Proxmox Operator**
- **Proxmox VE**

## Connections

- Proxmox Operator → Installer: runs (evidence: `README.md`)
- Installer → VM Setup: hands off
- VM Setup → Proxmox VE: configures (evidence: `README.md`)
- VM Setup → NVIDIA Profile: selects
- VM Setup → VM Profile: selects
- VM Setup → Pikera Enabled: selects
- VM Setup → Pikera Disabled: selects
- NVIDIA Profile → OpenCore Bootloader: configures
- Proxmox Operator → Recovery CLI: invokes
- Recovery CLI → Apple Recovery Service: requests metadata (evidence: `tools/macrecovery/macrecovery.py`)
- Recovery CLI → Image Download: starts download (evidence: `tools/macrecovery/macrecovery.py`)
- Image Download → Apple Recovery Service: fetches image (evidence: `tools/macrecovery/macrecovery.py`)
- Image Download → Recovery Images: writes image (evidence: `tools/macrecovery/macrecovery.py`)
- Recovery CLI → Chunk Verification: verifies image (evidence: `tools/macrecovery/macrecovery.py`)
- Chunk Verification → Recovery Images: reads image (evidence: `tools/macrecovery/macrecovery.py`)
- Proxmox Operator → Proxmox Reports: consults
- Proxmox Operator → VM Patches: applies