hyfervisor

Virtualization tool for live-debugging the macOS kernel on Apple Silicon Macs

Lets you live-debug kernels Apple doesn’t officially support, similar to QEMU on Linux

• Boot a self-built XNU kernel alongside custom kexts
• Supports booting KASAN kernels
• Can check coverage via breakpoints (unstable and slow)
• GUI access to 1TR

Screenshots

Features

• Run macOS virtual machines
• Hardware acceleration (CPU, memory, graphics, networking, audio)
• GDB debug stub support
• Load custom kernels/kexts

Requirements

• Apple Silicon Mac (M1/M2/M3/M4/M5)
• macOS 12.0 or later
• Bypassing AMFI on the host Mac (choose one):
  • Disable AMFI by adding amfi_get_out_of_my_way=1 to the host machine's boot-args.
  • Use amfidont, which patches AMFI behavior at runtime as an alternative to persistent boot-arg changes.

Build

# Full build
make all

# Installation tool
make hyfervisor-InstallationTool-Objective-C

# Main app
make hyfervisor-Objective-C

# Clean
make clean

Usage

# 1. Install the VM
./build/Build/Products/Release/hyfervisor-InstallationTool-Objective-C <ipsw path> [vm bundle path]

# 2. Launch the app
# This requires bypassing AMFI, so either disable it in the boot-args or use `sudo amfidont --path <hyfervisor path>`
./build/Build/Products/Release/hyfervisor.app/Contents/MacOS/hyfervisor
# or from CLI with a custom bundle path:
# ./build/Build/Products/Release/hyfervisor.app/Contents/MacOS/hyfervisor /path/to/VM.bundle

Pass an explicit VM bundle path if you want the VM artifacts somewhere other than ~/VM.bundle. You can supply the path as the second argument to the installer and as the first argument to hyfervisor so both tools operate on the same VM bundle.

Debug Console (Kernel Serial)

To get kernel serial logs, both host and guest must be configured:

• Host: run hyfervisor from a terminal so host stdin/stdout are attached.
• Guest: set serial/debug boot-args.

1. Launch hyfervisor from Terminal

Do not launch with Finder if you want live serial output.

./build/Build/Products/Release/hyfervisor.app/Contents/MacOS/hyfervisor

Optional logging to file:

./build/Build/Products/Release/hyfervisor.app/Contents/MacOS/hyfervisor 2>&1 | tee serial.log

2. Recovery step

Use hyfervisor's recovery boot path (Recovery Restart), then in Recovery Terminal run:

csrutil disable
csrutil authenticated-root disable

3. Reboot to normal mode and set boot-args

After rebooting the guest to normal mode:

sudo nvram boot-args="-v keepsyms=1 debug=0x14e serial=3"
sudo reboot

Verify:

nvram -p | grep boot-args

If output is still minimal, use a DEVELOPMENT/DEBUG kernel build. RELEASE kernels often print much less to serial.

---