How to Force a Specific Hardware Tier During ODS Installation

You can force a specific hardware tier during ODS installation by using the --tier <value> CLI flag or setting the TIER=<value> environment variable, which causes the installer to set TIER_FORCED=true and skip automatic GPU detection.

The Osmantic/ODS installer automatically determines your hardware capabilities during the detection phase to select an appropriate AI model tier. However, when you need to override this behavior to force a specific hardware tier during ODS installation—whether for testing alternative models, running CI pipelines, or locking a configuration—you can bypass the auto-detection logic entirely.

Understanding Hardware Tier Detection

By default, ODS runs a detection phase that analyzes your GPU type, memory size, and host architecture to assign a tier. This logic resides in installers/phases/02-detection.sh. When you supply a tier manually, the installer sets the TIER_FORCED flag, causing the detection script to skip GPU-based inference and use your specified value instead.

Method 1: Using the --tier CLI Flag

The top-level installation script ods/install.sh includes argument parsing logic that accepts a --tier flag. When provided, the installer stores the value in the TIER variable before the detection phase executes.

./install.sh --tier 2

According to the source code in ods/install.sh, the parse_args function processes this flag and exports it to subsequent phases. This method is ideal for quick, one-off overrides directly from the command line.

Method 2: Using the TIER Environment Variable

You can also pre-define the TIER variable in your shell environment. The detection script (installers/phases/02-detection.sh) reads this value through the parameter expansion TIER_REQUESTED="${TIER:-}". If a value is present, the script sets TIER_FORCED=true, bypassing hardware probes.

export TIER=NV_ULTRA
./install.sh

This approach is preferred for automation scripts, Docker containers, or CI environments where you want the setting to persist across multiple installer invocations.

Valid Hardware Tier Values

ODS accepts both numeric and named identifiers for tier selection. These values are defined in installers/lib/tier-map.sh within the resolve_tier_config() function, which maps each tier to a specific model, GGUF file, URL, and context size.

Numeric tiers:

• 0 – Minimal/Edge
• 1 – Entry Level (resolves to Qwen-9B)
• 2 – Prosumer
• 3 – Enthusiast
• 4 – Maximum

Named tiers:

• CLOUD
• NV_ULTRA (resolves to NVIDIA-Ultra model, or a substitution on aarch64)
• SH_LARGE
• SH_COMPACT
• ARC
• ARC_LITE

Implementation Details

When you force a tier, the following execution flow occurs:

1. Flag Parsing: ods/install.sh captures the --tier argument or inherits the TIER environment variable.
2. Detection Bypass: In installers/phases/02-detection.sh (lines 37-39), the script checks TIER_REQUESTED. If populated, it sets TIER_FORCED=true and skips hardware detection.
3. Tier Resolution: The resolve_tier_config() function in installers/lib/tier-map.sh (lines 12-19, 313-394) uses the forced TIER value to configure TIER_NAME, LLM_MODEL, GGUF_FILE, GGUF_URL, and MAX_CONTEXT.

Practical Code Examples

Force tier 2 (Prosumer) for a non-interactive installation:

./install.sh --non-interactive --tier 2

Use the environment variable method for persistent configuration:

export TIER=SH_COMPACT
./install.sh --non-interactive

Combine the tier flag with specific backend options:

./install.sh --tier NV_ULTRA --gpu-backend nvidia --dry-run

In each scenario, the installer skips automatic GPU detection and calls resolve_tier_config() with your forced tier, ensuring the specified model configuration applies regardless of actual hardware capabilities.

Summary

• Use --tier <value> for command-line overrides or TIER=<value> for environment-based configuration.
• Valid identifiers include numeric tiers (0 through 4) and named tiers like NV_ULTRA, CLOUD, and ARC.
• The detection script in installers/phases/02-detection.sh sets TIER_FORCED=true when a tier is supplied, bypassing hardware probes.
• Tier resolution occurs in installers/lib/tier-map.sh via the resolve_tier_config() function, which maps your selection to specific model files and parameters.

Frequently Asked Questions

What happens if I specify an invalid tier value?

If you provide a tier value not recognized by the resolve_tier_config() function in installers/lib/tier-map.sh, the installer will likely fail during the configuration phase with an error indicating the tier cannot be resolved. Always use the canonical identifiers listed in the tier-map definitions.

Can I force a tier that requires more GPU memory than my system has?

Yes, the installer will accept the forced tier and attempt to proceed, but the LLM service may fail to load or run poorly if your hardware lacks sufficient VRAM. Forcing a tier overrides the safety checks that normally prevent incompatible model selection.

Does forcing a tier affect other installer phases?

Forcing a tier primarily affects the detection and configuration phases. The installer skips GPU-based tier inference in installers/phases/02-detection.sh but continues with standard requirements checking, service installation, and model downloading based on the forced configuration.

Is the TIER_FORCED flag available for inspection after installation?

Yes, TIER_FORCED is set as an internal variable during the installation process. While it is primarily used internally by scripts like 02-detection.sh and tier-map.sh, you can verify that a tier was forced by checking the installation logs or by inspecting the generated configuration files that reference the TIER variable.

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