Documentation · Using OSX-REIMS
Console
The OSX-REIMS menu: create and manage VMs, view logs and maintain the computer.
This documentation covers OSX-REIMS 0.3.0, alpha software. Commands and options may change between versions; when in doubt, check osx-reims --help on the installed version.
The console is the OSX-REIMS menu in the terminal. It gathers what you need day to day: creating and managing VMs, viewing logs and maintaining the computer.
Opening the console
- From the applications menu, open OSX-REIMS. The console opens in a terminal window, 160 × 35 characters in Ptyxis, Ubuntu's default terminal, and in GNOME Terminal. The window closes when you quit; if the console exits with an error, it stays open until you press Enter.
- Or run this in a terminal:
osx-reimsThe console needs an interactive terminal. For automation, use the commands.
Main screen
The main screen lists the VMs, with the number, macOS version and state of each, and shows the menu:
| Key | Option |
|---|---|
1 |
Create new VM: creates a VM (see Your first VM) |
2 |
Import VM disk: creates a VM from the QCOW2 disk of a macOS already installed in another VM (see Importing a VM) |
3 |
Manage VMs: starts, shuts down and restarts VMs |
4 |
View logs: lists the recent logs |
5 |
Maintenance: deletes VMs, cleans the cache and checks the computer |
Q |
Quit: leaves the console |
Just press the option's key.
Note
While the environment is not ready (on first use or after an update), the screen shows why and offers S (Prepare environment), which runs osx-reims setup. Creating, importing and managing VMs are unavailable until then.
Managing VMs
Manage VMs lists the VMs and asks for a number. If the VM is shut down, the console asks for memory, processors and, once the VM has gone through its first start, which OpenCore to use. Then it starts the VM.
If the chosen VM is already running, the console offers:
| Key | Option |
|---|---|
S |
Shut down: macOS closes everything safely (recommended) |
R |
Restart: forced restart, without saving |
F |
Force power off: cuts the VM's power |
T |
Terminate process: when the VM does not respond |
C |
Cancel: does nothing |
When shutting down, OSX-REIMS waits up to 60 seconds for macOS. If macOS does not shut down, there may be a confirmation in the VM window or an app preventing the shutdown. You then choose Wait longer, Force power off or Cancel (the VM keeps running).
While the VM is open
The VM opens in its own window. To shut it down, use the Apple menu › Shut Down, inside macOS. Keep the terminal open while you use the VM.
In the terminal, these keys act on the VM. Press the same key twice within 5 seconds to confirm:
| Key | What it does |
|---|---|
S |
Asks macOS to shut down |
R |
Forces the VM to restart |
F |
Forces the VM to power off; anything unsaved is lost |
T |
Terminates the VM process; anything unsaved is lost |
The first Ctrl+C only warns that the VM is still running; a second one within 5 seconds asks macOS to shut down. Closing the terminal does not shut the VM down.
Viewing logs
View logs lists the 15 most recent runs, with date, action, VM and result. Type a log's number and press Enter to open it; the arrow keys and PgUp/PgDn scroll, and Q goes back. Enter without a number returns to the menu.
| Result | Meaning |
|---|---|
| Done | The action finished |
| Nothing was done | Nothing was done |
| Cancelled | The action was cancelled |
| Failed | The action failed |
| Terminal closed with the VM running | The terminal was closed while the VM was on |
| unfinished | The action is in progress or was interrupted |
Logs are kept in /opt/osx-reims/logs/, up to the 100 most recent. To ask for help, share the log of the run with the problem and a doctor log (see Troubleshooting).
Maintenance
| Key | Option |
|---|---|
1 |
Delete a VM: deletes a VM that is shut down |
2 |
Delete all VMs: deletes every VM; all must be shut down |
3 |
Clean cache: deletes the downloaded macOS installers |
4 |
Check this computer: runs doctor, whose log is the one to share when asking for help |
5 |
Prepare environment: runs setup |
6 |
Update Reims vGPU: tested or latest version, with the VMs shut down |
B |
Back: returns to the main menu |
Deleting VMs and cleaning the cache always ask for confirmation, and the default answer is no. Deleting a VM cannot be undone.