Install guide
From bare hardware to a bootable EFI
OCforge scans a machine, works out which macOS release its hardware can actually run, and assembles the OpenCore config.plist, kexts, and SSDTs to match. Two ways to get from there to an installed Mac — pick one below.
Path A
Regular build
The target machine has internet during install — the usual case. Build an EFI with the GUI, boot the normal macOS installer or recovery, done.
Read the steps →Path B
Offline installer
The target machine shouldn't or can't touch the internet mid-install — air-gapped, metered, or just unreliable Wi-Fi. Stage everything on a USB ahead of time instead.
Read the steps →The regular build
The GUI, on Windows: five tabs, no terminal required. It doesn't have to be the target machine itself, though it usually is.
Get the app
Grab OCforge-GUI-windows-x64.zip from the releases page and extract it.
Launch it
Run the .exe. On first launch it'll prompt you to install OCforge-CLI — accept, the GUI needs it to actually do anything.
Detect
Open the Detect tab and press Detect This PC. It reads out your specs — CPU, GPU, network, board, storage.
Plan
Switch to Plan, pick the macOS version you want to install, then press Generate Plan. It lays out the SMBIOS model, every kext, every SSDT, and any warnings — scroll all the way down the page to make sure nothing's flagged as broken before moving on.
Config
Open Config and press Generate Config.
Forge
Open Forge. It'll ask where the EFI should go — make a folder on your desktop, copy its path, and paste it into the textbox. Then you'll see four options:
| Option | Notes |
|---|---|
| Get the recovery image for that macOS | Worth leaving on — it's only ~600MB or a bit more, but it can be slow to fetch |
| Build SSDTs from your machine | Only works on Linux right now — Windows support is still a work in progress |
| Use the OpenCore debug build | Leave this off unless you specifically need debug logging |
| Get the offline image for that macOS | Leave this off — it takes ages; see the offline installer guide below if you actually need it |
The offline installer
For a target machine that shouldn't or can't touch the internet mid-install. The manual route below uses gibMacOS and UnPlugged — both by corpnewt, credit to them. There's also a one-command version further down if you'd rather let ocforge handle the staging.
Get gibMacOS
Download gibMacOS from corpnewt's GitHub and unzip it.
Run it
Use gibMacOS.bat — you'll need Python installed for it to run.
Pick your build
You'll see a long list of macOS versions. Scroll down first and make sure recovery-only mode is off — it should read R. Toggle Recovery-Only (Currently Off) — then pick the build you want. This downloads the full installer, not just the recovery.
Get the installer onto a USB
Once it's done downloading you'll have a handful of files: com_apple_MobileAsset_MacSoftwareUpdate, InstallAssistant.pkg, InstallInfo, MajorOSInfo, UpdateBrain. Only InstallAssistant.pkg matters here. Get a second USB — 20GB or more, formatted ExFAT — and copy that file onto it. Then grab UnPlugged.command (also corpnewt) and put it on the same USB.
Run UnPlugged from the installer
Boot the target machine into the macOS installer. Before anything else, open Disk Utility and format the target disk or partition as APFS, giving it any name you like.
Then go to Utilities → Terminal and find your USB's volume name:
cd /Volumes/
lsOnce you spot it in the list, switch into it and run the script:
cd /Volumes/your-usb-name
./UnPlugged.commandConfirm the detected macOS version with y, choose "Choose a locally discovered Install [macOS version].app", continue, then pick the disk you formatted earlier by its number and press enter.
Prefer the terminal? One command does steps 1–4
Same spec file as the regular path. This step is slow — it's downloading Apple's full installer image via gibMacOS under the hood.
ocforge offline-installer --spec my-pc.json --out ./offline-installerWhat comes out the other side:
Format your USB with a FAT32 partition (~1 GB — holds EFI/ and com.apple.recovery.boot/) and an ExFAT partition (the rest — everything under ExFAT/), then follow step 5 above from Terminal. Or skip the manual formatting and let ocforge do both:
ocforge offline-installer --spec my-pc.json --usb /dev/sdXUnPlugged itself still has to run from inside a booted macOS installer/Recovery — it's a bash script using diskutil/installer/asr, real macOS APIs nothing outside that environment has, so ocforge can't run it for you. It only handles getting everything into the layout UnPlugged expects.
Map your USB ports
Both paths above ship USBToolBox.kext — the driver — but not a map of your physical ports, which is specific to this exact board and has to be built once. Skip it and USB mostly works anyway; do it properly and every port reports the right speed and there's no 15-port ceiling surprise later.
Get the mapping app — on Windows
Not the kext you already have — a separate tool, USBToolBox/tool. Download Windows.zip from its releases and run Windows.exe — a terminal-style menu opens. Mapping happens on Windows, not macOS: only Windows can auto-detect USB2/USB3 companion port pairs and guess port types, and macOS 11.3+ has a broken XhciPortLimit that makes mapping from within macOS more painful. No Windows install handy? Boot a Hiren's BootCD PE USB and run the tool from its cmd (Shift+F10).
Discover every port
Press D for Discover Ports. Plug a device into one port at a time, wait for it to show up in the list, then unplug and move on — don't rush this.
Test each type properly:
| Port type | What to do |
|---|---|
| USB 3 Type-A | One device is usually enough (companion detection works on Windows); use a USB2 and USB3 device if you want to be sure |
| USB-C | Plug in, note it, unplug, flip the plug over, plug it back in — orientation can enumerate differently |
| Legacy USB 1.1 (old OHCI/UHCI boards) | Plug in a mouse or keyboard — most modern USB2 devices skip straight past the 1.1 personality |
| Internal-only (headers, built-in webcam/BT) | No device needed — just leave it typed correctly, you'll mark it internal below |
Type your ports and mind the 15-port cap
Press S for Select Ports. For each detected port, set its real type and mark it internal or external. Apple caps every USB controller at 15 mapped ports — most modern boards physically expose more, so the tool will warn you if you're over. Disable ports you'll genuinely never use (an unwired header, a dead legacy port) rather than cutting the last N in the list at random — check what each one is actually wired to first.
Build the map
Press K to build. Pick the USBToolBox kext format — it pairs with the USBToolBox.kext driver you already have installed. (The alternative, AppleUSBHostMergeProperties, is a native-Apple-style injector if you'd rather not depend on the third-party driver.) Out comes UTBMap.kext — a real kext folder, generated for this board specifically — plus a Ports.txt summary worth keeping for reference.
Add it to your EFI
Copy the whole folder in:
EFI/OC/Kexts/UTBMap.kextThen add a matching entry under Kernel → Add in config.plist — OCforge doesn't generate this one for you automatically, since it's tied to a map that doesn't exist until you've built it. The Editor tab's plist tree view (or ocforge plist show / save) is the quickest way: duplicate the existing USBToolBox.kext entry, change BundlePath to UTBMap.kext, leave everything else the same shape. Order matters — USBToolBox.kext must load before UTBMap.kext.
Reboot and check
Every port you mapped should now show its correct type in About This Mac → System Report → USB, instead of the generic fallback behavior USBToolBox uses with no map at all — and the boot log shouldn't show any "no personality found" or over-the-limit warnings.