Skip to content
vGPU OS
Documentation: First setup

Documentation · Getting started

First setup

What happens on the first start: network, hardware, graphics drivers, OSX-REIMS and graphics validation.

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.

On the first boot after installation, vGPU OS finishes configuring the computer on its own. This is where the video drivers are chosen for your machine. The network cable must be connected.

Loading screen

Between the boot menu and any vGPU OS screen, the loading screen appears, showing Starting vGPU OS: it may take a minute, and the console opens on its own. Do not switch terminals (Ctrl+Alt+F1 to F6) while it is on screen.

The five stages

The welcome screen (Welcome to vGPU OS 0.1.2) lists what will be done:

  1. Check the network. Without internet, the setup explains that it needs a wired connection with DHCP and asks whether to try again — connect the cable and confirm.
  2. Examine the hardware. Processor, virtualization, KVM, IOMMU, and each GPU, with the driver in use and which one the monitor is connected to.
  3. Install the video drivers. The setup shows the plan — Debian driver and firmware packages for each GPU, kernel modules, and, if IOMMU is present, the proposed kernel command line — and asks Install it now?. Nothing is installed without this confirmation.
  4. Install OSX-REIMS, including what it needs to compile Reims vGPU.
  5. Validate the graphics, checking that the GPU actually responds to Vulkan — not software rendering.

The disk is not modified beyond installing software.

Optional questions

  • IOMMU. If the firmware offers IOMMU, the setup asks whether to enable it in the kernel. It is not required for Reims vGPU; accepting requires a restart.
  • NVIDIA. With an NVIDIA GPU, the setup asks whether to install the proprietary driver from Debian's non-free repository and NVIDIA's Vulkan. CUDA is never installed.

One automatic restart

The firmware of some GPUs is only read when the driver starts. When this happens, the setup warns that the computer will restart and continue on its own — nothing else is needed. After the restart, Continuing the first setup after the restart. appears.

Result

The setup ends with First setup is finished. and the graphics verdict:

State Meaning
READY The GPU was validated with Vulkan (Graphics: ready on screen). Everything is ready
SOFTWARE There is no usable GPU (or you accepted software rendering). macOS will be very slow
FAIL The GPU did not pass validation. OSX-REIMS is not prepared; see Troubleshooting

OSX-REIMS opens next

With graphics ready, the OSX-REIMS console opens on its own, in full screen. The first time, it:

  1. shows the OSX-REIMS license, which must be accepted on this computer;
  2. prepares the environment in stages — system, GPU and Vulkan, groups, KVM, Rust, downloading and compiling Reims vGPU and its QEMU. The vgpu-user password may be requested in the stages that need administrator access.

The compilation downloads code from GitHub and takes several minutes. At the end, the OSX-REIMS main menu appears, ready for Create new VM. To create and operate VMs, follow the OSX-REIMS documentation: First VM (opens in a new tab).

Rerunning the first setup

If the setup stopped partway (no network, for example) or you changed the GPU, you can run it again from the terminal:

sudo vgpu-os-firstboot --force

See how to open a terminal in Commands.