OpenCore Post-Boot Patcher (OCPBP)

Architecture Defined · Queued Behind Golden Gate

Offline macOS Recovery USB root-patching workflow designed for cook0001/OpenCore-Legacy-Patcher to eliminate post-install SSH workarounds on unsupported Macs.

Status note: The OCPBP architecture and target-scoped OCLP design plan are complete and queued to implement immediately after the Golden Gate kernel bring-up milestone clears external USB boot.

Why OCPBP Exists

Zero-SSH Offline Root Patching Before First Desktop Boot

macOS Tahoe / Legacy USB & GPU

Freshly installed macOS on unsupported Macs often boots without GPU acceleration, a working WindowServer, or legacy USB HID input — forcing users into SSH sessions or blind scripts just to apply root patches.

  • Single-USB Model: Pairs Apple's version-matched macOS Recovery (BaseSystem) with a dedicated OCPBP payload volume on the installer USB.
  • Exact Tooling Match: Uses Recovery's built-in /usr/bin/kmutil, /usr/sbin/bless, /usr/sbin/diskutil, and mount_apfs rather than bundling a second 30 GB macOS install.
  • 100% Offline: Pre-stages matching Universal-Binaries.dmg, KDK, and MetallibSupportPkg assets on USB so patching needs no Wi-Fi or Ethernet in Recovery.

3-Part USB Layout

Partition / Volume Role Contents & Guarantees
1. USB OpenCore ESP (EFI) Pre-boot Configuration Model-specific OpenCore config enforcing SIP / Authenticated-Root flags (csr-active-config) and SecureBootModel=Disabled independently of internal NVRAM.
2. Installer / Recovery (BaseSystem) Bootable Environment Cleanly boots with basic GOP/VESA graphics and Apple USB drivers while providing version-exact kmutil, bless, and APFS snapshot utilities.
3. Companion OCPBP Volume Offline Payload Store APFS / JHFS+ volume preserving POSIX permissions and symlinks: headless OCLP CLI/TUI (zero wxPython/AppKit dependency), Universal-Binaries.dmg, matching KDK, Metallib, and /Volumes/OCPBP/ocpbp.command.

Target Three-Step User Workflow

  • Step 1 — Install & Shut Down: Install macOS onto internal storage using the USB installer as usual, then power off.
  • Step 2 — Boot Recovery & Launch ocpbp: Hold Option → select EFI Boot → boot OCPBP / Installer Recovery, open Terminal, and launch ocpbp against the target internal volume.
  • Step 3 — Offline Patch, Snapshot & Reboot: OCPBP resolves the target APFS System + Data + Preboot group, verifies SIP/AR preflight, stages offline KDK/Metallib and root patches, rebuilds kernel collections via kmutil, runs bless --create-snapshot, syncs OpenCore to internal EFI if missing, and reboots into an already-patched desktop.
/Volumes/OCPBP/ocpbp.command --target_vol "/Volumes/Macintosh HD" --offline_assets_dir /Volumes/OCPBP

Planned OCLP Root-Cause Refactors

Component Current Assumption Removed Target-Scoped Behavior
Host Hardware vs. Target OS Probe Assumes booted kernel equals patched OS via sw_vers / uname() Probes live hardware from IORegistry while resolving target build from <target>/System/Library/CoreServices/SystemVersion.plist and Cryptex metadata.
RootVolumeMount & APFSSnapshot Hardcodes / and /System/Volumes/Update/mnt1 Parameterizes APFS volume group resolution (System + Data + Preboot UUID) and safe temporary mount points for Recovery.
PatchSysVolume & KernelDebugKitMerge Hardcodes Data paths to /Library/Application Support and local /Library/Developer/KDKs Routes System/Data writes and offline KDK/Metallib staging strictly to the selected target volume without modifying /.
Headless Recovery Runtime & Builder Eagerly imports wx_gui and applescript at module load Defers GUI imports for headless CLI/TUI execution, adds SIP/AR and internal-ESP sync preflights, and adds a “Build OCPBP USB” option to USB creation.