# How Dream Server Detects NVIDIA, Intel Arc, and AMD GPUs: Complete Technical Guide

> Discover how Dream Server's detect_gpu function identifies NVIDIA Intel Arc and AMD GPUs via vendor specific stages for optimal performance. Learn the technical details.

- Repository: [Light Heart Labs/DreamServer](https://github.com/Light-Heart-Labs/DreamServer)
- Tags: deep-dive
- Published: 2026-05-18

---

**Dream Server performs GPU detection through the `detect_gpu()` function in [`dream-server/installers/lib/detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dream-server/installers/lib/detection.sh), which executes three vendor-specific detection stages to identify NVIDIA, Intel Arc, and AMD APU hardware before falling back to CPU-only mode.**

The open-source DreamServer repository by Light-Heart-Labs implements a hardware-agnostic detection system that automatically identifies GPU vendors during installation. This Bash-based library scans PCI vendor IDs, parses kernel driver interfaces, and queries specialized tooling to configure the appropriate Docker Compose backend for machine learning inference.

## NVIDIA GPU Detection Methods

Dream Server detects NVIDIA hardware through a multi-layered approach that handles both native Linux and Windows Subsystem for Linux (WSL2) environments.

### Native Linux PCI Scanning

The script first iterates through `/sys/class/drm/card*/device/vendor` files searching for the NVIDIA PCI vendor ID `0x10de` (lines 80-115 of [`detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/detection.sh)). When found, the system invokes `nvidia-smi` with `--query-gpu=name,memory.total` to extract the device name and VRAM capacity. The parser sets `GPU_BACKEND="nvidia"` and classifies the memory type as `discrete` (or `unified` if the query returns `[N/A]`), populating `GPU_NAME`, `GPU_VRAM`, and `GPU_COUNT` variables.

### WSL2 Fallback Handling

On WSL2 systems where `/sys/class/drm` lacks `card*` entries, the detection logic falls back to examining the kernel release string for patterns matching "microsoft|wsl" (lines 90-95). If detected, the script verifies `nvidia-smi` availability and queries GPU properties through that interface rather than sysfs, ensuring NVIDIA GPUs remain detectable in virtualized Windows environments.

## Intel Arc GPU Detection

For Intel Arc discrete GPUs, Dream Server employs `lspci` to scan for VGA controllers matching "VGA.*Intel.*Arc" (lines 145-172). The validation process confirms the vendor ID `0x8086` and filters device IDs against known Arc ranges: `0x56a0-0x56c1` or `0x5690-0x569f`. Upon successful identification, the script reads `lmem_total_bytes` from the device sysfs node to determine VRAM, sets `GPU_BACKEND="intel"`, and extracts the product name from either the `product_name` sysfs entry or `lspci` output.

## AMD APU Detection Logic

AMD hardware detection (lines 374-416) targets both discrete GPUs and APUs with unified memory architectures. The routine scans for PCI vendor ID `0x1002`, then reads two critical memory metrics: `mem_info_vram_total` (dedicated VRAM) and `mem_info_gtt_total` (GTT/system RAM accessible to the GPU). Dream Server classifies the device as an APU with unified memory when `GTT >= 16 GB` and `VRAM <= 4 GB`, or when `GTT >= 32 GB` regardless of VRAM size. This classification sets `GPU_MEMORY_TYPE="unified"` and `GPU_BACKEND="amd"`, while the product name is extracted from `product_name` if present.

## CPU-Only Fallback Mode

If no supported GPU is detected across all three vendor stages, the `detect_gpu()` function executes its fallback path (lines 519-527), setting `GPU_BACKEND="cpu"` and reporting "None (CPU-only mode)". This ensures the installer can proceed with CPU-based inference when no compatible hardware is present.

## Implementing GPU Detection in Practice

You can integrate Dream Server's detection library into custom installation scripts or validation tools:

```bash

# Source the detection library

source "$SCRIPT_DIR/installers/lib/detection.sh"

# Execute hardware detection

detect_gpu

# Evaluate results and configure environment

if [[ "$GPU_BACKEND" == "nvidia" ]]; then
    echo "✅ NVIDIA GPU detected: $GPU_NAME (${GPU_VRAM} MB VRAM)"
elif [[ "$GPU_BACKEND" == "intel" ]]; then
    echo "✅ Intel Arc detected: $GPU_NAME (${GPU_VRAM} MB VRAM)"
elif [[ "$GPU_BACKEND" == "amd" ]]; then
    echo "✅ AMD APU detected (unified memory): $GPU_NAME (${GPU_VRAM} MB VRAM)"
else
    echo "⚠️ No GPU found – falling back to CPU mode"
fi

```

The detection results persist as environment variables that downstream Python services can consume:

```python
import os

gpu_backend = os.getenv("GPU_BACKEND", "cpu")
gpu_name = os.getenv("GPU_NAME", "None")
gpu_vram_mb = int(os.getenv("GPU_VRAM", "0"))

print(f"GPU backend: {gpu_backend}, name: {gpu_name}, VRAM: {gpu_vram_mb} MB")

```

## Summary

- **Dream Server GPU detection** relies on [`dream-server/installers/lib/detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dream-server/installers/lib/detection.sh), a pure-Bash hardware library containing the `detect_gpu()` function.
- **NVIDIA detection** checks PCI vendor ID `0x10de` in `/sys/class/drm` and uses `nvidia-smi` queries, with special handling for WSL2 kernel environments.
- **Intel Arc detection** validates device IDs in ranges `0x56a0-0x56c1` and `0x5690-0x569f`, reading `lmem_total_bytes` for VRAM capacity.
- **AMD APU detection** identifies unified memory configurations by comparing `mem_info_vram_total` against `mem_info_gtt_total`, triggering when GTT exceeds 16 GB while VRAM remains below 4 GB.
- **Automatic fallback** to `GPU_BACKEND="cpu"` ensures installation continuity on unsupported hardware.

## Frequently Asked Questions

### How does Dream Server detect NVIDIA GPUs in WSL2 environments?

When `/sys/class/drm` contains no `card*` entries, Dream Server checks if the kernel release string contains "microsoft" or "wsl" and verifies `nvidia-smi` presence. If both conditions are met, it uses `nvidia-smi` directly to query GPU name and memory totals rather than relying on sysfs PCI enumeration.

### What PCI vendor ID ranges does Dream Server use to identify Intel Arc GPUs?

The script filters Intel devices for PCI vendor ID `0x8086` and validates device IDs against two specific hexadecimal ranges: `0x56a0` through `0x56c1` and `0x5690` through `0x569f`. Only devices matching these ranges are classified as Intel Arc GPUs.

### How does Dream Server determine if an AMD GPU is an APU with unified memory?

The detection logic reads `mem_info_gtt_total` (system RAM allocated to GPU) and `mem_info_vram_total` (dedicated VRAM) from sysfs. If GTT is at least 16 GB while VRAM is 4 GB or less, or if GTT exceeds 32 GB, Dream Server sets `GPU_MEMORY_TYPE="unified"` and treats the device as an APU rather than a discrete GPU.

### What happens if no supported GPU is detected during Dream Server installation?

If the `detect_gpu()` function fails to identify NVIDIA, Intel Arc, or AMD hardware, it sets `GPU_BACKEND="cpu"` and reports "None (CPU-only mode)" at lines 519-527 of [`detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/detection.sh). The installer then proceeds with CPU-only configuration, selecting the appropriate Docker Compose overlay for non-GPU inference.