# OSX For Omarchy

## 🎬 Video Demo

[![Watch the video](https://img.youtube.com/vi/DrN2SCCslQk/0.jpg)](https://youtu.be/DrN2SCCslQk)

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.