# What Information Is Included in the Dream Server Tier Configuration?

> Discover what information is in the Dream Server tier configuration. Learn about model identifiers, download URLs, and GPU settings that define LLM execution.

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

---

**The Dream Server tier configuration contains model identifiers, download URLs, SHA256 checksums, context window limits, and GPU backend settings that define which LLM runs on detected hardware.**

Dream Server classifies host hardware into numbered tiers (0 through 4) and special categories like `CLOUD`, `NV_ULTRA`, and `ARC`. According to the Light-Heart-Labs/DreamServer source code, each tier maps to a specific configuration block in [`installers/lib/tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/tier-map.sh) that populates variables driving the entire deployment stack.

## Core Tier Configuration Variables

When `resolve_tier_config()` executes, it exports a set of environment variables that describe the target model and its runtime requirements. These variables include:

- **TIER_NAME** – Human-readable label shown in installer summaries (e.g., `"Entry Level"` or `"NVIDIA Ultra (90GB+)"`).
- **LLM_MODEL** – The model identifier used by the dashboard-api and model-swap logic (e.g., `"qwen3.5-9b"` or `"anthropic/claude-sonnet-4-5-20250514"`).
- **GGUF_FILE** – Filename of the GGUF-format checkpoint to download (e.g., `Qwen3.5-9B-Q4_K_M.gguf`).
- **GGUF_URL** – Direct download URL, typically from Hugging Face (e.g., `https://huggingface.co/unsloth/Qwen3.5-9B-GGUF/resolve/main/Qwen3.5-9B-Q4_K_M.gguf`).
- **GGUF_SHA256** – SHA-256 checksum for integrity verification of the downloaded file.
- **MAX_CONTEXT** – Maximum token context window supported by the model (e.g., `16384` or `131072`), used by the llama.cpp server.
- **LLM_MODEL_SIZE_MB** – Approximate model size in megabytes, enabling the installer to validate hardware capacity.
- **GPU_BACKEND** *(optional)* – Required GPU runtime such as `sycl` for Intel Arc or `cuda` for NVIDIA.
- **N_GPU_LAYERS** *(optional)* – Number of layers to offload to GPU when using the SYCL backend (e.g., `99`).

## How Tier Resolution Works

The configuration resolution follows a structured pipeline defined in [`installers/lib/tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/tier-map.sh).

First, the hardware detection phase ([`installers/phases/02-detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/phases/02-detection.sh)) sets the `TIER` variable based on available RAM, VRAM, and GPU type. Then `resolve_tier_config()` determines which model profile to use via `effective_model_profile()`, choosing between `qwen` and `gemma4` profiles.

Depending on the profile selected, the function calls either `set_qwen_tier_config()` or `set_gemma4_tier_config()` to populate the variables listed above. Finally, `configure_llama_runtime_defaults()` may override Docker image tags when a Gemma 4 model is selected.

## Usage Across the Installer

The tier configuration variables are referenced throughout the Dream Server installation process:

- **Requirements Validation** – [`installers/phases/04-requirements.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/phases/04-requirements.sh) compares `TIER` and `MAX_CONTEXT` against available system memory to ensure the hardware can host the selected model.
- **Summary Output** – [`installers/phases/13-summary.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/phases/13-summary.sh) prints `TIER_NAME`, `LLM_MODEL`, and model size in the final installation report.
- **Docker Compose Generation** – [`scripts/resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/scripts/resolve-compose-stack.sh) uses `GPU_BACKEND` and model information to build the compose overlay that launches the LLM service.
- **Dashboard API** – [`extensions/services/dashboard-api/routers/setup.py`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/extensions/services/dashboard-api/routers/setup.py) exposes tier configuration metadata via FastAPI endpoints.

## Inspecting Tier Configuration Programmatically

You can resolve and inspect tier configuration values using Bash or Python.

Resolve a tier and display the configuration block:

```bash

# Assume TIER has been set by the detection phase

source "./installers/lib/tier-map.sh"

# Populate the tier-specific variables

resolve_tier_config

# Show the configuration

echo "Tier: $TIER ($TIER_NAME)"
echo "Model: $LLM_MODEL"
echo "GGUF file: $GGUF_FILE"
echo "Download URL: $GGUF_URL"
echo "Checksum: $GGUF_SHA256"
echo "Max context: $MAX_CONTEXT"
echo "GPU backend: ${GPU_BACKEND:-none}"

```

Programmatically retrieve the model name for a specific tier:

```python
import subprocess, os, shlex

def tier_to_model(tier: str) -> str:
    # Calls the Bash helper to echo the model name

    cmd = f". ./installers/lib/tier-map.sh && resolve_tier_config && echo $LLM_MODEL"
    result = subprocess.check_output(['bash', '-c', cmd],
                                     env={**os.environ, 'TIER': tier},
                                     text=True).strip()
    return result

print(tier_to_model("3"))   # → qwen3-30b-a3b (or gemma-4-26b-a4b-it if gemma4 profile)

```

## Summary

- The Dream Server tier configuration includes **model metadata** (`LLM_MODEL`, `TIER_NAME`), **download specifications** (`GGUF_FILE`, `GGUF_URL`, `GGUF_SHA256`), and **runtime parameters** (`MAX_CONTEXT`, `GPU_BACKEND`, `N_GPU_LAYERS`).
- Resolution occurs via `resolve_tier_config()` in [`installers/lib/tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/tier-map.sh), which selects between Qwen and Gemma4 model profiles based on hardware detection.
- Configuration variables drive requirements validation, installer summaries, Docker compose generation, and dashboard API responses.

## Frequently Asked Questions

### How does Dream Server determine which tier configuration to use?

The installer runs hardware detection in [`installers/phases/02-detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/phases/02-detection.sh) to set the `TIER` variable. This numeric or special-category value is passed to `resolve_tier_config()` in [`installers/lib/tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/tier-map.sh), which maps it to the appropriate model configuration block.

### What is the difference between Qwen and Gemma4 tier configurations?

The `effective_model_profile()` function determines whether to use `set_qwen_tier_config()` or `set_gemma4_tier_config()`. Both populate the same set of variables, but they reference different model families, checkpoint URLs, and may trigger different Docker image tags via `configure_llama_runtime_defaults()`.

### Why does the tier configuration include SHA256 checksums?

The **GGUF_SHA256** variable provides integrity verification for downloaded model files. The installer validates the downloaded GGUF file against this checksum before proceeding with deployment, ensuring the model data has not been corrupted or tampered with during transfer.

### Can I manually override the automatic tier selection?

Yes. If you set the `TIER` environment variable manually before running the installer, `resolve_tier_config()` will use your specified value rather than the auto-detected tier. This allows advanced users to force specific model profiles on hardware that would otherwise default to different configurations.