Skip to content
Documentation: Daily use

Documentation · Usage

Daily use

The vGPU OS session: the OSX-REIMS console, full-screen VMs, monitor, sound, the VMs’ network, backup, restart and power off.

Alpha

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

After the first setup, vGPU OS behaves like an appliance: turn it on, and the OSX-REIMS console opens. There is no desktop, graphical login, or file manager.

Turning on the computer

  1. The boot menu is hidden and the system boots directly (press Esc while it loads to see the menu).
  2. The Starting vGPU OS loading screen covers the startup.
  3. The OSX-REIMS console opens in full screen.

If a boot fails, the boot menu automatically appears again on the next one, for a few seconds.

The OSX-REIMS console

It is the same interface as OSX-REIMS on Ubuntu: create, import, manage, and maintain VMs, and view logs. On vGPU OS it takes up the whole screen and the header shows the version with the +vgpuos suffix, for example v0.6.0+vgpuos1. Right under the menu is the address of the web panel, such as Web panel: https://<address>.

The complete console documentation is on the OSX-REIMS site: Console (opens in a new tab), First VM (opens in a new tab), and VM settings (opens in a new tab).

Differences on vGPU OS:

  • VM windows always open in full screen, in the same Wayland compositor as the console;
  • each VM's GPU can be chosen in the VM settings when there is more than one. See GPUs and drivers;
  • each VM has sound, its network on NAT or on a bridge, and its refresh rate, as on Ubuntu (see below);
  • everything the console does with the VMs can also be done from the web panel, from another computer on the network.

To give the keyboard to macOS, click the VM's screen; to give it back to vGPU OS, press Ctrl+Alt+Super together.

Going back from macOS to the console

The VM takes up the entire screen. To return to the console, shut down macOS from the Apple menu → Shut Down; the VM closes and the console appears again. The options to shut down, restart, and force-stop the VM are also in the console, under Manage VMs, and in the web panel.

Automatic start

In the VM settings, in OSX-REIMS, mark the VM to start on its own. When you turn on the computer, vGPU OS opens the console and the VM starts right after, all the way to the macOS screen — without a single keypress along the way.

Restarting and shutting down the computer

When you exit the OSX-REIMS console (Quit option), a session menu appears:

Key Action
Enter Opens the console again
d The monitor: resolution and refresh rate
a The sound: where it comes out and the volume
s Opens a terminal (advanced)
r Restarts the computer
p Shuts down the computer

Monitor: resolution and refresh rate

The monitor starts in the mode it reports as its preferred one, which is often 60 Hz on a monitor that can do 120 or 144 Hz. Since a VM gets the monitor's refresh rate when it starts, it is worth choosing the right mode:

  • the d key in the session menu, vgpu-os display in a terminal, or This computer › Monitor in the web panel;
  • the new mode is tried for 15 seconds and kept only if you confirm it. If the monitor goes black, do nothing: the previous mode comes back by itself;
  • the chosen mode applies to that monitor, on that port, at every boot. vgpu-os display reset goes back to the monitor's own mode;
  • while a VM is running, the mode cannot be changed.

Each VM also has its own refresh rate in the OSX-REIMS settings: automatic (the monitor's, the default) or a fixed rate.

Sound

The VMs have sound: macOS plays through vGPU OS' sound output, and OpenCore plays its boot chime in new VMs. Choose where the sound comes out — the monitor's HDMI or DisplayPort, the board's speakers or a USB headset — and the volume:

  • the a key in the session menu, vgpu-os sound in a terminal, or This computer › Sound in the web panel.

The choice and the volume are kept for the next boots, and a change reaches a running VM at once. In each VM's settings, in OSX-REIMS, sound can be turned off.

The VMs' network

Each VM uses NAT, the default: it reaches the internet through vGPU OS' address and is reached from it alone. With the bridge, the VM gets an address of its own from the router and can be reached from any computer on the network, while vGPU OS keeps its own address.

  1. Turn the bridge on once: in the OSX-REIMS console, Maintenance › VM network, or in the web panel, Maintenance › VM network. It needs a wired network port; the network stops for a few seconds.
  2. When starting the VM, choose Bridge in its Network setting.

Backup & Restore

A whole VM can become a single file and be restored later, over itself or as a new VM: in the OSX-REIMS console, Backup & Restore (key 6), or in the web panel's Backup & Restore tab.

Warning

The backups are in /opt/osx-reims/backup, on the same disk as the VMs. A disk failure or a reinstall erases both. To keep a backup, copy the file to another computer over SSH.

Terminal and remote access

For diagnostics and maintenance, there are four ways to reach a Linux terminal, always with the vgpu-user user:

  • the s option in the session menu;
  • Ctrl+Alt+F2 opens a text login screen; Ctrl+Alt+F1 returns to the session;
  • SSH from another computer on the network;
  • the Terminal tab of the web panel.

To watch the GPUs' use, run nvtop in one of these terminals.

The available commands are in Commands.