Documentation · Help
Advanced configuration
Folders, environment variables, /etc/osx-reims.conf and the OpenCore choice.
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.
Most people do not need to change anything here. These options are for keeping VMs somewhere else, using Reims vGPU from another folder or understanding the advanced boot choices.
Default folders
| Folder | Contents |
|---|---|
/opt/osx-reims/ |
The program, installed by the package |
/opt/osx-reims/cache/, full/, logs/, state/ and backup/ |
Installers, full images, logs, state and backups, created by setup for your user |
/opt/reims-vgpu/ |
Reims vGPU (REIMS_ROOT) |
/opt/reims-vgpu/vm/disks/rails/ |
The VMs (RAILS_DIR) |
/opt/reims-vgpu/vm/disks/rails/macos-<number>/ |
One VM, with its identity and its settings |
Environment variables
| Variable | What it sets | Default |
|---|---|---|
REIMS_ROOT |
The Reims vGPU folder | /opt/reims-vgpu |
RAILS_DIR |
The VM folder | <REIMS_ROOT>/vm/disks/rails |
MACRECOVERY |
Alternative path to macrecovery.py, which downloads the recovery from Apple |
The one shipped in the package |
QMP_TIMEOUT |
Seconds to wait for each control command sent to a running VM | 5 |
NO_COLOR |
Turns off terminal colors | Not set |
UPDATE_CHECK_URL |
Where the published OSX-REIMS version is read from | https://osx-reims.com.br/app/latest.json |
Example, for a single command:
RAILS_DIR=/mnt/vms/rails osx-reims listThe /etc/osx-reims.conf file
To fix an option permanently, create the optional /etc/osx-reims.conf file, with one KEY=VALUE line per option:
# VM folder on another disk
RAILS_DIR=/mnt/vms/rails| Key | What it sets | Default |
|---|---|---|
REIMS_ROOT |
The Reims vGPU folder | /opt/reims-vgpu |
RAILS_DIR |
The VM folder | <REIMS_ROOT>/vm/disks/rails |
REIMS_VGPU_REF |
The Reims vGPU commit setup uses |
The tested commit |
UPDATE_CHECK_URL |
Where the published version is read from; empty turns the check off | https://osx-reims.com.br/app/latest.json |
HOST_PROFILE |
desktop or appliance (below) |
desktop |
FORCE_SCREEN |
window or fullscreen for every VM on this computer |
Not set |
FORCE_BACKEND |
wayland or x11 for every VM on this computer |
Not set |
CONSOLE_NOTICE_FILE |
A file whose first line the console's main screen shows (below) | Not set |
SETUP_OS_ID, SETUP_OS_VERSION |
The tested system; setup and doctor warn on any other |
ubuntu, 26.04 |
SETUP_OS_NAME |
The system's name in the messages about it and its login | Ubuntu |
- The file is used only when it is owned by root and not writable by other users. That is why you create it with
sudo. - Lines starting with
#are comments, and one pair of quotes around the value is accepted. - Other keys are ignored and named in the log.
- Environment variables take precedence over the file.
- Each log's header says whether the file was used or ignored, and why.
To choose the Reims vGPU version, prefer osx-reims update-reims over setting REIMS_VGPU_REF. See Reims vGPU version.
FORCE_SCREEN and FORCE_BACKEND are for a computer that always shows the VM the same way, such as a kiosk. They come before each VM's saved choice and after that start's own answer, so --fullscreen, --windowed, --x11, --wayland and the settings menu still win.
The new-version check
OSX-REIMS fetches one address on its own: UPDATE_CHECK_URL, a small JSON saying which version is published, the name of its .deb and that file's SHA-256. The check happens at most once a day, in the background, and nothing is sent beyond the request for the file. To turn it off, leave the key empty:
UPDATE_CHECK_URL=With it empty, OSX-REIMS fetches nothing from the internet on its own, and osx-reims update still installs the package you downloaded — it just has nothing to compare the version or the hash against.
Host profile
HOST_PROFILE says what kind of computer this is:
desktop, the default and what every installation without the file gets: an ordinary Linux desktop where someone installed the package. Nothing changes.appliance: a computer whose whole job is OSX-REIMS, installed from an image, with no desktop environment and no login screen.
The value is set, never detected; an unknown value is logged and read as desktop. On an appliance, automatic login is not offered (there is no login screen to skip), the autostart messages say the VM opens when the computer starts, and the VM's start screen says only how to give the keyboard back and that the console comes back when the VM is shut down. doctor shows a Host profile row, and each log header has a Profile: line.
Important
Changing RAILS_DIR does not move existing VMs: they stay in the old folder and no longer show up. The new folder must be writable by your user.
A notice on the main screen
CONSOLE_NOTICE_FILE names a file that another program on the computer keeps up to date — vGPU OS writes the address of its web panel there —, and the console's main screen shows that file's first line under "Choose an option:". The file must be owned by root or by the console's user and not writable by other users; the line must be at most 200 characters, with no control characters. Anything else shows nothing. While it waits for a key, the screen looks at the file every 3 seconds and redraws itself when the line changes. Without the key, the main screen is the usual one.
Which OpenCore starts the VM
Every VM comes with its own OpenCore boot disk. For an installed VM, the settings menu (C › O) offers:
| Option | --opencore |
What it is |
|---|---|---|
| VM boot disk | image |
The OpenCore that came with the VM. It is the default and the recommended choice |
| macOS disk | esp |
The OpenCore in the EFI partition of the macOS disk itself |
With macOS disk, the macOS disk starts on its own, with nothing beside it.
- The choice is saved and becomes that VM's default. It is only offered for VMs that went through their first start.
- Each OpenCore carries its own configuration. Switching between them can change the identity macOS sees, such as the serial number, and with it iCloud, iMessage and FaceTime.
startwarns you before starting. - When you switch back to VM boot disk, the firmware boot order is reset so the VM starts from its own boot disk again. Nothing else has to be restored.
Installing OpenCore into the macOS disk's EFI
When you choose macOS disk, OSX-REIMS reads that disk's EFI and offers what fits what is there:
| The EFI | What is offered |
|---|---|
| already has an OpenCore | use it as it is, or replace it with the VM's |
| has no OpenCore yet | install this VM's OpenCore into it |
| is missing, is not FAT or has no room | nothing: the reason is shown and the VM keeps its own boot disk |
What is copied is the VM's own OpenCore, so the identity (SMBIOS, serial number) goes with it and macOS goes on seeing the same computer. In that copy, and only in it, the boot picker is turned off, because there is a single system to start in that disk: hold ESC while the VM starts to open it anyway.
Important
An EFI that is already there is never written over: EFI/OC and EFI/BOOT are moved whole to EFI.osx-reims-bak, in the same partition. A second install stops instead of replacing that backup — open the EFI from inside macOS and delete that folder to install again.
The macOS disk is written once, at the end, and only the blocks that changed (about 9 MB). That write is read back and compared before the choice is saved, so a failure anywhere leaves the VM starting exactly as it did. The VM must be shut down, and none of this needs sudo: the partition is read, changed in a temporary file and written back, never mounted.
--opencore esp on the command line does not install by itself: putting an EFI into the macOS disk changes that disk, and that is asked for in the menu. The option only refuses a disk with nothing to start. To give that answer in advance — a program with a person behind it, such as a web panel —, add --install-esp: when the EFI has no OpenCore, the VM's own is installed there first, with the same refusals as the menu; an OpenCore already there is used as it is, never replaced.
Running without questions
Commands accept -y to run without questions, using the option values or the defaults. To see a VM's boot command without starting it:
osx-reims start 10 --dry-runEvery option is in Commands.