Documentation · Getting started
Overview
What OSX-REIMS is, how it works and where its files live on your computer.
This documentation covers OSX-REIMS 0.6.0, alpha software. Commands and options may change between versions; when in doubt, check osx-reims --help on the installed version.
OSX-REIMS creates and manages macOS virtual machines on Ubuntu. It uses Reims vGPU (opens in a new tab), a paravirtualized GPU for macOS that QEMU presents to the VM and that uses Vulkan to accelerate macOS graphics.
Everything lives in a single program: a console with menus for day-to-day operation and terminal commands for everything the menu does.
Important
OSX-REIMS is an experimental project, for study, experimentation and testing. It does not replace an Apple computer: performance and stability are nowhere near a Mac’s, and features that rely on Apple hardware, services and integrations may not work. Do not use the VM as your main machine or for work you depend on. To use macOS day to day, with stability and support, buy a Mac.
Note
OSX-REIMS is exclusive to Universo Hackintosh members with an active membership on the Hackintosh - Avançado or Hackintosh - vGPU OS tier. Each version's package is downloaded with the Gerar meu link de download (Get my download link) button in the #osx-reims channel of the members' Discord; the way to it is in Getting OSX-REIMS.
It is experimental alpha software, provided without warranty and without technical support. Technical questions and problems go to the #osx-reims-chat channel, a space for members to help each other (see Asking for help).
How it works
- Install. You install the OSX-REIMS
.debpackage on Ubuntu Desktop 26.04 LTS. - Prepare. The
osx-reims setupcommand prepares the computer: system packages, GPU and KVM access, Rust, and Reims vGPU, which is downloaded and built on your computer. - Create a VM. In the menu, Create new VM creates the VM with an empty disk, OpenCore and the macOS installer: the recovery, downloaded from Apple's servers, or a full installer image. If you already have macOS installed in another VM, Import VM disk creates the VM from its QCOW2 disk.
- Install macOS. On its first start, the VM opens the macOS installer. An imported VM boots straight into the macOS on its disk.
- Everyday use. From the menu you start, shut down and restart VMs, view the logs and maintain the computer. Each VM keeps its own settings — memory, processors, screen, display server, GPU, network, sound — so starting it is one keypress, and a VM can even open by itself when the computer is turned on. A whole VM can also be turned into a backup file and restored later.
What every VM gets
- A ready EFI. Every VM comes with OpenCore already configured; you don't need to build an EFI. Four files it uses (
AppleMCEReporterDisabler.kext,VMHide.kext,ReimsVgpu.kextandHfsPlus.efi) are downloaded from their sources when the VM is created, with their fingerprints checked, and kept for later VMs — see License. - Its own identity. A serial number, MLB, UUID, ROM and MAC address are generated for each VM, so two VMs never share an identity.
- Graphics acceleration. macOS uses the Reims vGPU virtual GPU, with Apple's own driver, and the graphics work goes to the computer's GPU through Vulkan. On macOS Tahoe,
ReimsVgpu.kexthas the driver use more of the GPU. - Network and sound. The VM reaches the network through NAT or, with the bridge on, with an address of its own on the computer's network. macOS's sound plays through Ubuntu's sound server.
- Its own settings. Memory, processors, screen (window or full screen), display server, OpenCore, GPU, refresh rate, network and sound are saved in the VM's folder and become its defaults. See VM settings.
Where files live
| Path | What it is |
|---|---|
/opt/osx-reims/ |
The program, installed by the package, with the license in assets/licenses/ |
/opt/osx-reims/logs/ |
One log per action; the latest is also in latest.log |
/opt/osx-reims/cache/ |
The recovery downloaded from Apple, reused by later creations |
/opt/osx-reims/full/ |
Full installer images, offered by the menu when creating a VM |
/opt/osx-reims/state/ |
The setup result and the record of the license acceptance |
/opt/osx-reims/backup/ |
The VMs' backups, one file per backup |
/opt/reims-vgpu/ |
Reims vGPU, downloaded and built by setup |
/opt/reims-vgpu/vm/disks/rails/ |
The VMs, one macos-<ID> folder each, with its identity and its settings |
Next steps
- Requirements: what your computer needs.
- Getting OSX-REIMS: how to become a member and download the package on Discord.
- Installation: installing the package and preparing Ubuntu.
- Your first VM: creating a VM and installing macOS.
- Importing a VM: using the disk of a macOS already installed in another VM.
- VM settings: memory, processors, screen, display server, GPU, network, sound and autostart.
- Backup and restore: keeping a whole VM in one file and putting it back.