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

Dream Server performs GPU detection through the detect_gpu() function in 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). 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:

# 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:

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, 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. The installer then proceeds with CPU-only configuration, selecting the appropriate Docker Compose overlay for non-GPU inference.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}