Skip to content
vGPU OS
Documentation: Overview

Documentation · Getting started

Overview

What vGPU OS is, how it relates to OSX-REIMS and what happens from the USB stick to macOS.

Alpha

This documentation covers vGPU OS 0.1.2, in alpha. Screens and commands may change between versions; to see the installed version, use vgpu-os version.

vGPU OS is a dedicated operating system, based on Debian 13 (trixie), that exists only to run OSX-REIMS (opens in a new tab). It is distributed as a bootable ISO: you write it to a USB drive, install it on a disk, and the computer then boots straight into the console for your macOS VMs.

A second way to use OSX-REIMS

vGPU OS does not replace OSX-REIMS on Ubuntu. They are two paths to the same result:

Path For whom What you keep
Ubuntu Desktop + OSX-REIMS .deb package Those who already use Ubuntu and want the VMs alongside everything else Ubuntu, the desktop, and the drivers
vGPU OS (ISO) Those who want a computer just for macOS VMs Nothing but the VMs: the system takes care of the rest

In both cases, OSX-REIMS creates the same VMs, with the same built-in EFI, and fetches Reims vGPU from the same source, compiling it on your computer.

What comes with vGPU OS

  • Minimal Debian 13, with no desktop environment, login manager, or file manager.
  • A text-based installer that takes up an entire disk (UEFI, x86_64).
  • A first setup that checks the network, examines the hardware, installs only the video drivers the computer needs, installs OSX-REIMS, and proves that graphics work.
  • A dedicated session: the OSX-REIMS console in full screen, with the macOS window opened in the same Wayland compositor. The Linux underneath stays out of the way.
  • A loading screen between the boot menu and the session, so a computer that is starting up never looks frozen.

What is not included in the ISO, on purpose: the proprietary NVIDIA driver, CUDA, Vulkan drivers, GPU firmware, and Reims vGPU. All of these are installed later, from each one's official source. See GPUs and drivers.

From USB drive to macOS

  1. Get the ISO from the #vgpu-os channel on Discord.
  2. Write the USB drive and install: choose the disk, confirm, set the password.
  3. The first setup runs on its own on first boot, with the network cable connected.
  4. The OSX-REIMS console opens, shows the license, and prepares the environment (compiles Reims vGPU).
  5. Create the first VM in OSX-REIMS and install macOS. From there, see Daily use.

Note

The vGPU OS and OSX-REIMS screens are in English. This documentation quotes on-screen text as it appears.

Who does what

  • vGPU OS installs the system, prepares the hardware and the session, and hands the machine over to OSX-REIMS.
  • OSX-REIMS creates, runs, and maintains the macOS VMs. Its documentation is at osx-reims.com (opens in a new tab).
  • Reims vGPU is the Vulkan-accelerated virtual GPU used by the VMs, a third-party open-source project: reims-vgpu.com (opens in a new tab).

OSX-REIMS does not depend on vGPU OS: it keeps working the same way on Ubuntu, and vGPU OS uses it only through the interfaces that already existed.

Alpha stage

vGPU OS 0.1.2 is experimental software, provided without warranty and without technical support. It takes up an entire disk, does not yet support in-place updates, and is intended for study and testing — not for data you depend on. A macOS VM is not a substitute for a Mac.