28allday
a5c460c328
Interactive installer for running macOS on QEMU/KVM with OpenCore. Supports High Sierra through Tahoe, multi-VM management, Samba shares, USB passthrough, SMBIOS generation, and a gum-based TUI manager. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
291 lines
8.4 KiB
Markdown
291 lines
8.4 KiB
Markdown
# OSX For Omarchy
|
|
|
|
Run macOS in a virtual machine on [Omarchy](https://omarchy.com) 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](https://omarchy.com) (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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
./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](https://github.com/kholia/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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
nano ~/OSX-KVM/vms/<vm-name>/start-macos.sh
|
|
```
|
|
|
|
Modify these values near the top:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](https://omarchy.com) - The Arch Linux distribution this was built for
|
|
- [OSX-KVM](https://github.com/kholia/OSX-KVM) - QEMU/KVM macOS virtualization framework
|
|
- [OpenCore](https://github.com/acidanthera/OpenCorePkg) - macOS bootloader
|
|
- [GenSMBIOS](https://github.com/corpnewt/GenSMBIOS) - SMBIOS data generator
|
|
- [ChimeraOS](https://chimeraos.org/) - Inspiration for session management
|
|
|
|
## License
|
|
|
|
This project is provided as-is for the Omarchy community.
|