Documentation · Getting started
Your first VM
Create a VM, install macOS and learn to operate it.
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.
Once osx-reims setup has prepared the computer (see Installation), creating a VM takes just a few questions. If you already have macOS installed in another VM, see Importing a VM.
Create the VM
Open the console and choose Create new VM. OSX-REIMS shows the existing VMs and asks for:
- VM number, from 10 to 99. The default is the first free number.
- macOS installer:
1Recovery: downloaded from Apple's servers; installing macOS uses the internet;2Full: a full installer image you already have, with no macOS download.
- macOS version: Ventura (13), Sonoma (14), Sequoia (15) or Tahoe (26). Ventura is the default, and versions whose recovery was already downloaded are marked. With a full image, the version comes from the image itself.
- macOS disk size, such as
256Gor1T. The default is256G; the disk only uses space as it fills up.
After the summary, confirm Create the VM?. OSX-REIMS then:
- downloads the recovery from Apple, which can take a few minutes, or reuses one already downloaded;
- generates the VM's identity and its OpenCore boot disk;
- creates the VM, with the macOS disk and a copy of the installer.
At the end, the console offers to start the VM right away: press S.
Full installer image
The image must be a disk created with createinstallmedia, with an "Install macOS" volume named after the version, usually a .iso, .img or .cdr file. The installer app, CD/DVD images (ISO 9660), compressed DMGs and qcow2 or vmdk images do not work.
Put images in /opt/osx-reims/full/ so the menu offers them; you can also type the path of another file. When the file system allows it, the VM gets a clone of the image that takes no space; otherwise, a copy.
Install macOS
Start the VM from the console, right after creating it or in Manage VMs, or with osx-reims start <number>. On the first start, OSX-REIMS asks for the VM's settings:
- Memory, such as
8Gor16G(default:8G); - Processors, from 1 to 32 (default:
4); - Screen: a normal window (the default) or full screen, taking the whole monitor;
- Display server: your session's Wayland or X11 (default: the server your session runs).
The answers are saved in the VM and become its defaults — the next starts do not ask again. The refresh rate (the monitor's), the network (NAT) and sound (on) are not asked: they keep their defaults until you change them. See VM settings.
The summary shows the macOS installation mode. Confirm Start the VM?. On the first start, the installer is attached to the VM automatically, and the VM opens in its own window. Click the window to give macOS the keyboard; Ctrl+Alt+Super, pressed together, give the keyboard back to Ubuntu.
- In the OpenCore menu, choose the installer. With a full image, the entry is Install macOS followed by the version name.
- In the installer, open Disk Utility and erase the REIMS macOS disk as APFS.
- Go back and install macOS on that disk. The VM may restart a few times during the installation.
Tip
The suggested memory and processor values are not minimum requirements: choose them to suit your computer. In full screen, give the keyboard back to Ubuntu with Ctrl+Alt+Super and use Alt+Tab to get back to the terminal.
Note
If the macOS installation is interrupted half way — the VM shut down or restarted before macOS finished —, there is no need to delete the VM: in C › I (Installer), or with osx-reims start <number> --attach-installer, the installer is attached again for that start, without erasing the disk.
Starting and operating the VM
After its first start, the VM shows as Installed and has every setting saved. From then on, start shows a summary of what it will use and asks only:
| Key | Option |
|---|---|
S |
Start: starts the VM with the settings in the summary |
C |
Change: changes a setting before starting |
Q |
Cancel: does not start the VM |
C holds memory, processors, screen, display server, OpenCore, the installer, GPU, refresh rate, network, sound, nested VMs and starting with the computer. Each one is explained in VM settings.
OpenCore is the one setting listed only for an installed VM, and the default is the one that came with the VM:
| Option | What it is |
|---|---|
| VM boot disk | The OpenCore that came with the VM (recommended) |
| macOS disk | The OpenCore in the macOS disk's own EFI, which OSX-REIMS can install for you |
Keep VM boot disk unless you want the macOS disk to start on its own. More in Advanced configuration.
While the VM is open:
- shut it down from the Apple menu › Shut Down, inside macOS;
- closing the VM window powers the VM off at once, like pulling its plug: use the Apple menu instead;
- keep the terminal open while you use the VM; closing it does not shut the VM down;
- in the terminal, the
S,R,FandTkeys, pressed twice, shut down, restart, force off or terminate the VM (see Console).
With the network on NAT, the default, the start summary also shows the VM's SSH port, localhost:22 followed by the VM number (for example, localhost:2210 for VM 10). To use it, turn on Remote Login in macOS. With the network on the bridge, the VM has an address of its own on the network and is reached through it.
VM states
| State | Meaning |
|---|---|
| Ready to install | Created with an installer; the next start opens the macOS installation |
| Ready for first use | Imported, or created without an installer; not started yet |
| Installed | Already went through its first start and boots from its own disk |
| Starting | Starting |
| Running | Running |
| Faulty (incomplete disk) | The VM disk is incomplete; share the log when asking for help |
| Faulty (no base disk) | The VM's base disk is missing; share the log when asking for help |
From the terminal
The same steps, without the menu:
osx-reims create -i 11 -m sonoma -s 256G -y
osx-reims start 11 -r 16G -c 6 --fullscreenEvery option is in Commands.