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 →

Path A

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	Works on Linux and Windows — Windows reads your ACPI tables natively, nothing to download. macOS needs you to supply a DSDT folder
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

Path B

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/
ls

Once you spot it in the list, switch into it and run the script:

cd /Volumes/your-usb-name
./UnPlugged.command

Confirm 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-installer

What comes out the other side:

./offline-installer/EFI/ — your usual EFI, unchanged ./offline-installer/com.apple.recovery.boot/ — the boot environment ./offline-installer/ExFAT/InstallAssistant.pkg — the actual installer ./offline-installer/ExFAT/UnPlugged.command

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/sdX

UnPlugged 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.

After either path

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.kext

Then 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.

Troubleshooting

iCloud Fix For Unable To Sign In Nor Log In

If iCloud, iMessage, or FaceTime fail to authenticate, the most common cause is a burned SMBIOS identity — a serial number that's already been used to sign into iCloud on another machine (real Mac, VM, or another Hackintosh).

Fix checklist

Work through these together — a partial fix (e.g. new serial but old ROM) usually still fails:

Use a Mac model (SMBIOS) that actually matches your CPU generation — check Dortania's guide for your CPU and confirm it supports your macOS version
Generate a fresh Serial Number, Board Serial (MLB), and System UUID — never reuse one from a guide, video, or old config
Set ROM to your real network adapter's MAC address (not random)
Sign out of Apple ID, clear iCloud/account caches, and reset NVRAM before signing in again
Confirm system date/time is correct and set to automatic
Once sign-in succeeds, keep this identity permanently — don't regenerate it on reinstall

Tools to generate the values above:

GenSMBIOS — generates a valid Serial, MLB, and UUID
ProperTree — GUI editor for config.plist

Where to put the SMBIOS values

All SMBIOS values live inside your EFI partition, at EFI/OC/config.plist, under PlatformInfo → Generic:

Field	What it is
`SystemProductName`	The Mac model you're spoofing (e.g. `iMac19,1`)
`SystemSerialNumber`	The fresh Serial Number
`MLB`	The Board Serial
`SystemUUID`	The fresh System UUID
`ROM`	Your real network adapter's MAC address (as raw hex)

How to edit them:

Open config.plist with ProperTree or OpenCore Configurator
Navigate to PlatformInfo → Generic
Paste in the freshly generated Serial, MLB, UUID, and your real ROM value
Save the file, then copy the updated config.plist back onto your EFI partition (EFI/OC/)
Reboot for the new identity to take effect