Hardware Tier Mapping in Dream Server: Configuration and Implementation Guide

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.

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 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 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, 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 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, mirroring the Linux version's functionality.

Hardware Detection

The 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.

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

# 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

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

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

• Configuration resides in 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 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 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 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, which mirrors the Linux implementation at 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 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.

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