# Hardware Tier Mapping in Dream Server: Configuration and Implementation Guide

> Learn about hardware tier mapping in Dream Server. This guide explains how it auto-matches host GPUs to optimal LLM binaries, configuring model weights and backend parameters for efficient performance.

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

---

**Hardware tier mapping in Dream Server automatically matches your host machine's GPU specifications to the optimal quantized LLM binary, configuring the appropriate model weights, context window size, and GPU backend parameters based on detection logic in [`installers/lib/tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/tier-map.sh).**

Dream Server implements hardware tier mapping to eliminate manual model selection by categorizing host machines into predefined performance tiers. This system, maintained in the Light-Heart-Labs/DreamServer repository, automatically maps hardware capabilities to specific GGUF files, Hugging Face download URLs, and runtime configurations required for the [`llama.cpp`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/llama.cpp) server deployment.

## How Hardware Tier Detection Works

The tier detection process executes during the installer's detect phase and comprises five distinct resolution steps:

1. **Detect Hardware**: The [`installers/lib/detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/detection.sh) script analyzes GPU type, VRAM capacity, and platform characteristics to set the `TIER` variable (e.g., `0`, `1`, `2`, `3`, `4`, `ARC`, `NV_ULTRA`, or `CLOUD`).

2. **Resolve Model Profile**: The functions `normalize_model_profile` and `effective_model_profile` determine whether to apply the user-requested model profile (`qwen` or `gemma4`) to the detected hardware tier.

3. **Set Tier Configuration**: The system invokes either `set_qwen_tier_config` (default) or `set_gemma4_tier_config` to populate tier-specific variables including `TIER_NAME`, `LLM_MODEL`, `GGUF_FILE`, `GGUF_URL`, `GGUF_SHA256`, `MAX_CONTEXT`, and `LLM_MODEL_SIZE_MB`.

4. **Apply Runtime Defaults**: The `configure_llama_runtime_defaults` function may override the Docker image configuration when non-default profiles require specific GPU backend settings like `GPU_BACKEND="sycl"` or `N_GPU_LAYERS=99`.

5. **Expose Configuration**: After `resolve_tier_config` completes, the installer consumes these variables to download the model file, generate the Docker Compose stack via [`scripts/resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/scripts/resolve-compose-stack.sh), and initialize the LLM server.

## Configuration Files and Core Functions

All hardware tier logic resides in modular shell scripts that separate detection from mapping decisions.

### Primary Mapping Logic

The file **[`installers/lib/tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/tier-map.sh)** contains the central mapping implementation. It defines the `case $TIER in … esac` blocks within `set_qwen_tier_config` and `set_gemma4_tier_config` that match hardware tiers to specific model binaries.

For macOS systems, an equivalent implementation exists at **[`installers/macos/lib/tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/macos/lib/tier-map.sh)**, mirroring the Linux version's functionality.

### Hardware Detection

The **[`installers/lib/detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/detection.sh)** script performs the initial hardware analysis, setting the `TIER` variable based on available GPU compute resources. This script is typically invoked during the preflight phase by **[`installers/phases/01-preflight.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/phases/01-preflight.sh)**.

## Model Profile Mappings

Dream Server maintains separate configuration tables for different model families, allowing users to select alternative LLM architectures optimized for specific hardware capabilities.

### Qwen Profile (Default)

The Qwen profile maps standard numerical tiers to quantized Qwen models. For example, tier `1` (Entry Level) configures:
- **Model**: `qwen3.5-9b`
- **File Size**: Approximately 5.68 GB
- **Context Window**: 16,384 tokens (`MAX_CONTEXT=16384`)
- **GGUF File**: Specific quantized filename mapped via `GGUF_FILE`

### Gemma-4 Profile

The Gemma-4 profile supports specialized hardware like Intel Arc GPUs. Tier `ARC_LITE` maps to:
- **Model**: `gemma-4-e2b-it`
- **GPU Backend**: `sycl`
- **GPU Layers**: 99 (`N_GPU_LAYERS=99`)

Both profiles handle edge cases including cloud API configurations (`CLOUD`) and ultra-high-memory NVIDIA GPUs (`NV_ULTRA`).

## Practical Configuration Examples

The following examples demonstrate how to interact with the tier mapping system directly from the repository.

### Resolve Current Tier Configuration

```bash

# Source detection and tier mapping libraries

source ./dream-server/installers/lib/detection.sh   # sets $TIER

source ./dream-server/installers/lib/tier-map.sh

# Execute resolution to populate variables

resolve_tier_config

echo "Detected tier: $TIER_NAME"
echo "Model to run:   $LLM_MODEL"
echo "GGUF file:      $GGUF_FILE"
echo "Max context:    $MAX_CONTEXT"

```

### Query Model for Specific Tier

```bash
source ./dream-server/installers/lib/tier-map.sh

# Retrieve model identifier for tier 3

tier_to_model 3

# Output: qwen3-30b-a3b

```

### Override Model Profile via Environment Variable

```bash

# Switch to Gemma-4 model family

export MODEL_PROFILE=gemma4
source ./dream-server/installers/lib/detection.sh
source ./dream-server/installers/lib/tier-map.sh

resolve_tier_config
echo "Using profile $MODEL_PROFILE_EFFECTIVE, model $LLM_MODEL"

```

## Summary

- **Hardware tier mapping** automatically selects LLM binaries based on GPU VRAM, type, and platform characteristics detected by [`installers/lib/detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/detection.sh).

- **Configuration resides in [`installers/lib/tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/tier-map.sh)**, specifically within the `set_qwen_tier_config` and `set_gemma4_tier_config` functions that populate variables like `GGUF_FILE`, `MAX_CONTEXT`, and `GPU_BACKEND`.

- **Dual profile support** allows switching between Qwen (default) and Gemma-4 model families by setting the `MODEL_PROFILE` environment variable before running `resolve_tier_config`.

- **Five-step resolution flow** moves from hardware detection through profile resolution, tier configuration, runtime defaults, and finally exposes variables for Docker Compose generation.

## Frequently Asked Questions

### How does Dream Server detect my hardware tier automatically?

The [`installers/lib/detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/detection.sh) script analyzes your system's GPU type, VRAM amount, and platform architecture to assign a `TIER` value (such as `1`, `ARC`, or `NV_ULTRA`). This value determines which model configuration block executes in [`tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/tier-map.sh) during the `resolve_tier_config` call.

### Can I force Dream Server to use a different model than my tier suggests?

Yes, set the `MODEL_PROFILE` environment variable to `gemma4` or `qwen` before running the installer. The `effective_model_profile` function in [`tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/tier-map.sh) checks this variable and overrides the default mapping, though the target model must still be compatible with your hardware capabilities.

### Where are tier mappings configured for macOS systems?

macOS tier mappings live in [`installers/macos/lib/tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/macos/lib/tier-map.sh), which mirrors the Linux implementation at [`installers/lib/tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/tier-map.sh). Both files contain identical `case` statement logic for mapping tiers to models, ensuring consistent behavior across platforms.

### How do I add support for a new GPU type to the tier system?

Edit the `case $TIER in … esac` blocks in `set_qwen_tier_config` (or `set_gemma4_tier_config`) within [`installers/lib/tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/tier-map.sh) to define the new tier. You must specify `TIER_NAME`, `LLM_MODEL`, `GGUF_FILE`, `GGUF_URL`, `GGUF_SHA256`, `MAX_CONTEXT`, and optional GPU backend variables like `N_GPU_LAYERS`.