GPU setup and troubleshooting

In the SoAI WebUI, start with the Hardware page. It shows the values SoAI can receive from the host, its driver, and the vendor tools. A GPU can be detected while some telemetry or controls remain unavailable, so identify the missing capability before changing the host.

Check access and the reported state

1. Open Hardware from the side navigation.
2. Review the GPU card, then select that GPU in Chart if you need its stored history.
3. Check whether the GPU control panel is present and which controls it contains.

The page requires Hardware read access (HARDWARE_READ). To grant it to a Standard user, an Administrator with ACL administration (ACL_ADMIN) selects the Settings button at the right of the header, then selects Settings from its menu and ACL. Open the Standard user group, enable Hardware read access (HARDWARE_READ), and select Save. The GPU control panel needs GPU tuning (HW_GPU_TUNING) as well, and that one is not merely off by default for Standard users: the Standard group cannot hold it at all, so an account that needs GPU control needs to be an Administrator.

Check the vendor tool and driver

If backend capability discovery times out, wait for the hardware query to finish before retrying. Read the reported cause: a missing tool, failed driver query, invalid response, or denied access needs the corresponding driver, system tool, or service-account permission check. Failed discovery does not establish that no compatible GPUs exist.

SoAI identifies GPUs before any vendor tool answers, so a card can appear on the page with very little attached to it. On Linux that first pass is a PCI scan, and on Windows it is a WMI query of the display adapters, with vendor telemetry merged onto that list afterwards. A GPU without telemetry reports why: usually the vendor tool is missing, while an NVIDIA card bound to a kernel driver other than the NVIDIA one reports instead that the driver is inactive. A tool that is installed but denied permission, and a tool that times out, both look the same as a missing tool, so run the tool yourself as the account SoAI runs under before concluding it is absent.

If the driver cannot report dedicated memory capacity reliably, Hardware shows it as unavailable with the cause. A previous reading can remain visible with its age while another GPU operation runs. It is not used as current capacity for model placement. Wait for that operation to finish and refresh Hardware; check the driver if capacity remains unavailable. Capacity and other sensors can be available independently.

A vendor tool does not make every setting available, and the Hardware page renders only the controls that the current device reports as supported. Part of AMD clock control also goes through the AMDGPU OverDrive files under /sys/class/drm rather than through amd-smi, which is why an AMD control can appear on a host whose amd-smi telemetry is thin, and why AMD and Intel changes can still fail on a host that does not grant the privileges those interfaces need. macOS (experimental) has no GPU collection path at all today, so the Hardware page lists no GPU there even on a machine that has one.

Readings are cached, so a fix does not show up the moment you make it. The GPU snapshot is held for 1 second (SYSTEM.HARDWARE.GPU_INFO_CACHE_TTL_SEC), the rest of the host snapshot for 2 seconds (SYSTEM.HARDWARE.HARDWARE_CACHE_TTL), and the vendor detection that decides which vendor tools are worth querying is held for 60 seconds (SYSTEM.HARDWARE.GPU_VENDOR_CACHE_TTL_SEC). Give the page a minute after installing amd-smi, xpu-smi, or a driver before deciding the install changed nothing. In the other direction, a probe that returns no GPUs while a GPU vendor is still detected on the host keeps the last inventory that had one rather than blanking the page, so a card that was genuinely removed or hidden can linger until a later probe succeeds.

Install a driver on SoAI OS

Open the Settings menu at the right of the header, select Settings, then Drivers. This tab is available only on SoAI OS to an Administrator with SoAI OS administration (HOST_MANAGEMENT_ADMIN). Follow SoAI OS GPU drivers for detection, preview, installation, and reboot guidance instead of changing host packages outside that workflow.

The Intel plan installs the graphics firmware, the Mesa drivers, and intel-gpu-tools, and it does not install xpu-smi, which is not available as a native Debian 13 package through SoAI OS. Intel telemetry and Intel controls therefore stay unavailable after a successful Intel driver install until you supply that tool yourself.

Controls are missing or rejected

A visible GPU is not enough for a hardware change. The signed-in account needs GPU tuning (HW_GPU_TUNING), the device must report the control, and the vendor backend must remain available. If a control disappears after a driver change, return to Hardware and inspect the current capability set instead of reusing an old value.

SoAI rejects hardware mutations while SYSTEM.RUNTIME.HARDWARE_MUTATION_DISABLED is enabled. An Administrator with Configuration changes (CONFIG_PATCH) can select the Settings button at the right of the header, then select Settings from its menu. Select Advanced in the page header, search for the complete configuration path, set Hardware mutation disabled to Off, and select Save.

A container looks the same as a missing driver. SoAI reads the hardware its own process can see, so a container started without GPU passthrough shows the card with no telemetry or does not list it at all, with nothing on the page to separate that from an uninstalled driver. Check passthrough on the host before reinstalling anything inside the container.

Related documentation

• GPU controls and tuning
• Hardware monitoring
• SoAI OS GPU drivers
• Troubleshooting
• Operational runbooks
• Known limitations and support boundaries