OSX-For-Omarchy/README.md

OSX For Omarchy

Run macOS in a virtual machine on Omarchy using QEMU/KVM and OpenCore.

One script sets up everything - packages, KVM, OVMF firmware, OpenCore bootloader, macOS recovery download, virtual disk creation, Samba shared folders, USB passthrough, and a TUI manager. Supports multiple VMs with different macOS versions running side by side.

Supported macOS Versions

Version	Name	CPU Model	Minimum RAM
10.13	High Sierra	Penryn	4GB
10.14	Mojave	Penryn	4GB
10.15	Catalina	Penryn	4GB
11	Big Sur	Penryn	8GB
12	Monterey	Penryn	8GB
13	Ventura	Haswell	8GB
14	Sonoma (recommended)	Skylake	8GB
15	Sequoia	Skylake	8GB
26	Tahoe (beta)	Skylake	16GB

Requirements

• OS: Omarchy (Arch Linux)
• CPU: Intel VT-x or AMD-V enabled in BIOS
• RAM: 8GB+ system RAM (16GB+ recommended)
• Disk: 64GB+ free space per VM
• AUR Helper: yay (for dmg2img and cdrtools)

Quick Start

git clone https://github.com/28allday/OSX-For-Omarchy.git
cd OSX-For-Omarchy
chmod +x osx-kvm-installer.sh
./osx-kvm-installer.sh

The installer is fully interactive and handles everything automatically.

Usage

Keybindings

Action	Keybind
Open VM Manager TUI	Super + Alt + A
Release mouse from VM	Ctrl + Alt + G

Command-Line Options

./osx-kvm-installer.sh              # Full setup (first run)
./osx-kvm-installer.sh --create-vm  # Create a new VM (skip system setup)

After Installation

Launch VMs from:

• The application menu (desktop entries are created per VM)
• The VM Manager TUI (Super+Alt+A)
• Directly: ~/OSX-KVM/vms/<vm-name>/start-macos.sh

First Boot Instructions

1. In the OpenCore menu, select "macOS Base System"
2. Wait for Recovery to load
3. Open Disk Utility from the menu
4. Select the QEMU HARDDISK and click Erase
   • Name: Macintosh HD, Format: APFS
5. Close Disk Utility, select Reinstall macOS
6. Follow the installation wizard (30-60 minutes, multiple reboots)
7. After installation, select "Macintosh HD" in OpenCore to boot normally

What Gets Installed

Packages

Official repos (pacman): qemu-full, libvirt, virt-manager, dnsmasq, edk2-ovmf, swtpm, git, wget, python, python-pip, p7zip, openbsd-netcat, screen, htop

AUR (yay): dmg2img, cdrtools

Optional: samba (for shared folders), usbutils (for USB passthrough), gum (for TUI manager)

System Configuration

Component	What It Does
User groups	Adds user to kvm, libvirt, input
libvirtd	Enabled and started
KVM module	ignore_msrs=1 configured in /etc/modprobe.d/kvm.conf
IOMMU	Checked (optional, for GPU/USB passthrough)

Repository

Clones OSX-KVM to ~/OSX-KVM/, which provides:

• OpenCore bootloader (pre-configured for QEMU)
• OVMF firmware files
• macOS recovery image downloader (fetch-macOS-v2.py)
• macserial tool for SMBIOS generation

Features

Multi-VM Support

Create and manage multiple macOS VMs with different versions. Each VM gets:

• Its own directory under ~/OSX-KVM/vms/<vm-name>/
• Unique SSH port (deterministic, based on VM name)
• Unique MAC address
• Independent disk image, config, and launcher script
• Desktop menu entry

VM Manager TUI

A gum-based terminal UI accessible via Super+Alt+A that lets you:

• View all VMs with resource details
• Create new VMs
• Delete VMs
• View VM details (RAM, CPU, disk size)

The TUI opens as a centered, floating, pinned window in Hyprland.

Samba Shared Folders

Optionally set up a shared folder between Linux and macOS:

• Default path: ~/macos-shared
• Accessible in macOS via Finder > Go > Connect to Server
• Address: smb://<your-ip>/macos-shared

USB Passthrough

Pass USB devices directly to the VM:

• Lists all connected USB devices (filtering out hubs/controllers)
• Select devices by number
• Devices are unavailable to the host while the VM runs

SMBIOS Generation

Generate unique SMBIOS data for iCloud/iMessage compatibility:

• Uses macserial from OSX-KVM
• Auto-selects appropriate Mac model based on macOS version:
  • High Sierra - Catalina: iMac19,1
  • Big Sur - Monterey: iMacPro1,1
  • Ventura+: MacPro7,1
• Generates serial number, MLB, and UUID
• Saved to <vm-dir>/.smbios for manual OpenCore configuration

Boot Arguments

Configure OpenCore boot arguments per VM:

Argument	Purpose
-v	Verbose boot (see boot messages)
debug=0x100	Debug mode (don't reboot on panic)
keepsyms=1	Keep symbols for debugging
-no_compat_check	Skip compatibility check
amfi_get_out_of_my_way=1	Disable AMFI (for unsigned kexts)

Version-Specific QEMU Configuration

Each macOS version gets tuned QEMU settings:

• CPU model: Penryn for older versions, Haswell for Ventura, Skylake for Sonoma+
• Network: vmxnet3 for High Sierra/Mojave, virtio-net-pci for Catalina+
• Display: vmware-svga for older versions, virtio with GTK GL acceleration for modern versions

Legacy Migration

If you have an older single-VM installation, the script detects it and offers to migrate to the new multi-VM structure automatically.

Directory Structure

~/OSX-KVM/
├── OpenCore/              # OpenCore bootloader (from OSX-KVM repo)
├── OVMF_CODE_4M.fd       # UEFI firmware
├── OVMF_VARS-1920x1080.fd
├── fetch-macOS-v2.py      # macOS downloader
├── tools/
│   └── GenSMBIOS/         # SMBIOS generator (if used)
└── vms/
    ├── sonoma/
    │   ├── start-macos.sh       # VM launcher
    │   ├── mac_hdd_ng.img       # Virtual disk (qcow2)
    │   ├── BaseSystem.img       # macOS recovery image
    │   ├── .macos-version       # Display name
    │   ├── .vm-config           # RAM, CPU, version config
    │   └── .smbios              # SMBIOS data (if generated)
    └── ventura/
        └── ...

SSH Access

Each VM gets a unique SSH port (10022-10999) forwarded from localhost. After enabling Remote Login in macOS System Settings:

ssh -p <port> localhost

The port is shown when launching the VM and is saved in the launcher script.

Customization

Changing VM Resources

Edit the launcher script directly:

nano ~/OSX-KVM/vms/<vm-name>/start-macos.sh

Modify these values near the top:

ALLOCATED_RAM="8192"   # MiB
CPU_CORES="4"
CPU_THREADS="8"

Changing Display Resolution

The default OVMF firmware is configured for 1920x1080. To change resolution, use a different OVMF_VARS file from the OSX-KVM repo.

Troubleshooting

KVM not accessible

# Check KVM exists
ls -la /dev/kvm

# Fix permissions
sudo chmod 666 /dev/kvm

# Verify groups
groups | grep kvm

VM won't boot / black screen

• Ensure ignore_msrs=1 is set: cat /sys/module/kvm/parameters/ignore_msrs
• Try verbose boot: add -v to boot arguments in OpenCore
• Check QEMU output in the terminal for errors

No network in macOS

• Verify libvirtd is running: systemctl status libvirtd
• Check the VM's MAC address isn't conflicting with another VM
• Try restarting the VM

iCloud/iMessage not working

• Generate SMBIOS data (run installer again or use GenSMBIOS manually)
• Apply SMBIOS values in OpenCore config.plist
• Use the correct Mac model for your macOS version

Shared folder not accessible

# Check Samba is running
systemctl status smb nmb

# Test connection
smbclient -L localhost -U $USER

# Re-set Samba password
sudo smbpasswd -a $USER

IOMMU not enabled

Add to your kernel boot parameters:

• Intel: intel_iommu=on iommu=pt
• AMD: amd_iommu=on iommu=pt

Then update your bootloader config and reboot.

Credits

• Omarchy - The Arch Linux distribution this was built for
• OSX-KVM - QEMU/KVM macOS virtualization framework
• OpenCore - macOS bootloader
• GenSMBIOS - SMBIOS data generator
• ChimeraOS - Inspiration for session management

License

This project is provided as-is for the Omarchy community.