Config

Owner: daemon / user config keys (docs/INDEX.md). Machine sources:

• Native schema + resolution: crates/hipfire-config/src/lib.rs
• Versioned CLI/daemon handoff: hipfire_config::ProcessConfig
• Compact runtime snapshots: hipfire_runtime::config::RuntimeConfig and rdna_compute::feature_flags::FeatureFlags

Last checked: 2026-07-21.

Persistent stores under ~/.hipfire/:

1. Global — sparse typed config.toml; missing keys inherit schema defaults.
2. Per-model overlay (primary) — models.toml: aliases, local paths, registry identities, and sparse per-model overrides.
3. Migration inputs — config.json, models.json, and per_model_config.json. Migration writes TOML and preserves the JSON files for rollback.

Copyable sparse profiles for users, kernel developers, and retained-PM4 work live in docs/configs/. They include direct mappings from historical HIPFIRE_* inputs to their persistent TOML keys. Apply a whole bundle with the dedicated profile command:

hipfire config profile set default
hipfire config profile set dev
hipfire config profile set redline
hipfire config profile create lab
hipfire config profile              # interactive wizard

Selection replaces the complete sparse global config.toml with the chosen built-in or custom profile layer (no stale keys remain). Custom snapshots live under ~/.hipfire/profiles/<name>.toml. Profile names are not schema fields and are never written into config.toml. The Settings TUI and CLI share the hipfire-config helpers. Profiles are global-only.

Edit global settings interactively with hipfire config. Per-model overlays use the typed commands: hipfire config <tag> list|get|set|reset .... Global non-interactive edits use hipfire config list|get|set|reset ....

Precedence (operator view): one-shot CLI values > legacy-compatible process env > per-model override > global TOML > registry card (recommended_settings) > built-in defaults. hipfire config explain prints the winning source and shadowed candidates. Direct daemon invocation resolves the same local TOML plus compatibility environment before GPU startup.

TOML is the supported persistent surface. Environment variables named in the schema are compatibility/one-shot overrides, not a second persistent config system. The native CLI serializes a versioned, schema-validated ProcessConfig to the daemon before the GPU is initialized. The daemon revalidates it and lowers it directly into RuntimeConfig and FeatureFlags; it does not materialize TOML values as process environment variables. Sparse architecture-sensitive fields remain absent so existing compiled defaults are unchanged.

Process and diagnostic keys are global-only. hipfire config <model> set ... rejects them because the daemon snapshots these values once; claiming a per-model override inside a long-lived serve process would be misleading.

This page is the normative key/default/enum table. CASK/TriAttention and PFlash are experimental opt-ins; multi-GPU topology lives in its linked owner rather than a duplicated matrix here.

Process-wide hardware and kernel policy

Use the native config commands; the flat spelling shown in hipfire config list remains accepted as a migration alias:

hipfire config set kernel.mmq auto
hipfire config set kernel.fp16 true
hipfire config set fusions.qkv_bias true
hipfire config set diagnostic.gemm_dump false

auto means the existing architecture/model policy wins. These keys default to auto and do not materialize an environment value until explicitly set:

Stable/default-on and safety controls:

The following default-off keys are experimental kernel-route overrides. They are typed booleans, process-scoped, and visible in hipfire config list with per-key help:

Diagnostic booleans all default off: diagnostic.prompt_token_heat, diagnostic.prompt_heat_json, diagnostic.draft_gemm_dump, diagnostic.draft_subphase, diagnostic.mmq_quantize_only, diagnostic.blob_force, diagnostic.gemm_dump, and diagnostic.qkv_bias.

Process-wide scalar policy is typed as well:

Developer-only scalar and variant controls live below diagnostic.kernel so they remain visible and typed without becoming registry-authorized product defaults:

Every field currently read by the centralized RuntimeConfig and FeatureFlags snapshots has a schema mapping and crosses the CLI/daemon boundary in the versioned ProcessConfig; no child-environment projection is used.

Experimental developer controls

The long tail of kernel experiments and diagnostics is available in one flat, global-only TOML namespace instead of as hundreds of ambient process switches:

[developer]
gfx1151_gate_up_wave64 = true
deepseek4_attn = "twin"
replay_pm4_queues = 4

The CLI accepts the same keys (hipfire config set developer.gfx1151_gate_up_wave64 true) and preserves the supplied scalar spelling. A legacy HIPFIRE_FOO=value one-shot maps to developer.foo = "value" during startup resolution. Developer values are snapshotted before GPU initialization, sent in ProcessConfig, and read only from that immutable snapshot. They are never registry-authorized or valid in a per-model overlay. Prefer a typed schema key whenever one exists.

Direct production reads of HIPFIRE_* are restricted to bootstrap paths that must be known before config discovery or process launch: home/model roots, binary/registry locations, kernel cache, spill directory, and quant diagnostic output. Examples and tests may still inject compatibility variables before startup.

Generation / sampling

Reasoning contract (three independent axes)

Thinking controls are three orthogonal axes. A field’s meaning never depends on model family:

Thinking budget map (legacy named presets → integer, only when the loaded model’s contract still accepts the named-cap route):

Rules:

• Mode, effort, and cap are independent. Setting reasoning_effort=low does not invent a think-token cap; setting thinking_budget=high does not change effort.
• Effort-native models (Qwen3.8, Ornith 1.5, DeepSeek V4, Muse Glimmer) have no registry or built-in think-token cap by default. Qwen3.8 and Ornith 1.5 accept the explicit integer cap through the validated Qwen continuation path. DeepSeek V4 and Muse Glimmer expose effort but no parent-defined independent think-token cap, so integer and named cap fields are dropped with a visible warning.
• Registry cards may keep intentional reasoning_effort defaults. Omitting a budget field is the correct uncapped signal — do not pin effort-native tags to a hipfire named cap.
• Thinking disabled wins: effort and cap are dropped with a warning.
• Recognizable unsupported / cross-family values are normalized or dropped with [WARN: INVALID CONFIG] (server log + OpenAI response metadata under hipfire.reasoning / hipfire.config_warnings). Malformed types and out-of-range integers remain hard errors.
• Template probing only checks whether semantic effort is native; it never changes field meaning.

Family examples (full HTTP surface: SERVE.md):

Effective sampling send order (request_f64 / request_u64 / run): explicit CLI or HTTP request > per-model TOML overlay > registry recommended_settings > daemon/HFQ/arch fallback. This applies to temperature, top_p, top_k, min_p, presence_penalty, and repeat_penalty. Bare global sampling values are deliberately not transmitted on the current run/serve path; if one shadows a registry recommendation, the card value is recovered for that model. Registry entry sampling blocks are legacy metadata — the resolver reads recommended_settings; see MODELS.md.

prompt.system (legacy spelling system_prompt) is the corresponding request-scoped framing default. A client-supplied system or developer message wins; otherwise a per-model TOML value or registry-card system_prompt is inserted before the first user message.

KV cache

Resolution of auto: registry entry default_kv_mode if present and valid; else universal fallback q8. There is no per-arch implicit FWHT table.

turbo* values remain accepted aliases for validation/compat; resolution maps them in resolveKvMode.

kv_adaptive is opt-in. With adaptive on, max_seq is the context guaranteed at the floor tier. Daemon param overrides HIPFIRE_KV_ADAPTIVE when set through CLI load path.

--kv-backend vmm enables on-demand HIP VMM mapping for single-GPU Qwen3.5 q8, asym3, and fwht3 KV caches. The default remains contiguous. VMM currently does not compose with pipeline/expert parallelism or CASK/TriAttention eviction.

Legacy one-shot alias: HIPFIRE_KV_MODE (see env-vars.md).

Attention

Lowered directly into the daemon snapshot. HIPFIRE_ATTN_FLASH remains a legacy one-shot alias. The Qwen3.5 MTP head inherits the trunk flash_mode / attention_flash_mode (it does not pin a separate non-flash path).

Speculative decode

Only one mechanism runs. Canonical selector:

• off — AR only.
• auto — cascade by availability / eligibility; legacy mode knobs filter each mechanism. Under auto, DSpark can win over in-trunk MTP when a DSpark sidecar is present (CLI comments).
• Forced mechanism names bypass heuristics; missing prerequisites fall back to AR with a warning.

Legacy one-shot alias: HIPFIRE_SPECULATION. CLI: --spec.

Mechanism knobs

Legacy compatibility input still wins at the top of the startup ladder for the corresponding knobs, but the engine receives only the resolved immutable snapshot. Full aliases: env-vars.md.

Vision tower

• off (default) — never load a tower sidecar. The registry/sibling file is not wired, and even an explicit run --vision / serve --vision / HIPFIRE_VISION_SIDECAR path is skipped with one stderr line. The daemon enforces the same hard override for non-CLI clients, mirroring dflash_mode=off. Text loads pay no tower VRAM (~1 GB).
• auto — use the registry vision slot (or the <trunk-stem>-vision.hfq sibling beside the trunk) when present; silently text-only when absent.
• on — require the declared sidecar: the load fails closed with a pull hint when it cannot be resolved. A trunk with an embedded tower declares no sidecar and is unaffected by this key.

hipfire config set vision_mode auto
hipfire config qwen3.8:27b set vision_mode auto   # per-model overlay
HIPFIRE_VISION_MODE=auto hipfire run qwen3.8:27b  # one-shot

Loading detail: MODELS.md. Env inventory: env-vars.md.

MMQ screening

MMQ policy is configured with kernel.mmq = "auto" | true | false and the experimental weight-only route with kernel.wo_mmq. Screening only matters when MMQ is on. Daemon arch-gates the sweep (RDNA3/3.5 family in source comments). Legacy HIPFIRE_MMQ / HIPFIRE_WO_MMQ values remain one-shot compatibility overrides.

CASK / TriAttention eviction

Developer escapes use [developer] cask_off = true and force_a3b_eviction = true; the old names remain one-shot aliases.

TriAttention and CASK are experimental, opt-in features. A downloaded sidecar does not attach by default. To experiment, set cask_sidecar explicitly or set cask_auto_attach=true; set cask=true only when core-aware m-folding is also intended. Sidecar generation: hipfire sidecar-gen — CLI.md.

Prompt processing

Collapse \n{3,} → \n\n at engine entry. Legacy alias: HIPFIRE_NORMALIZE_PROMPT (0/false/off/no disable).

PFlash speculative prefill (experimental)

Off by default. Typed fields cover product PFlash policy; remaining experiments live under [developer] and retain matching HIPFIRE_PREFILL_* one-shot aliases. Detailed bypass reasons and serve wiring: SERVE.md / runtime PFlash module — not restated here.

Server / serve admission

Serve HTTP surface: SERVE.md. The corresponding HIPFIRE_MODEL, HIPFIRE_IDLE_TIMEOUT, HIPFIRE_MAX_REQUEST_BYTES, HIPFIRE_SERVE_MAX_QUEUE, HIPFIRE_SERVE_QUEUE_TIMEOUT_MS, and HIPFIRE_SERVE_MULTI_SLOT* names are legacy one-shot aliases.

Memory

memory.oom_guard

Compat env: HIPFIRE_OOM_GUARD. Used by kv_slots::preflight_alloc, the SlotPool arena check, and the CLI bench-sweep headroom path.

Two checks exist; only one is gated:

• Host MemAvailable headroom — gated by memory.oom_guard. Default auto turns it on for unified-memory APU arches (gfx1035 / gfx1036 / gfx1103 / gfx1150–gfx1152: GPU allocations come from system RAM, so an overshoot is a desktop-killing OOM), off for discrete GPUs (overshoot is a failed hipMalloc), and for GPU-less processes by host swap state (no swap → on). Explicit true/false force either way; auto logs its decision once.
• R9700 deployment-target VRAM budget (32 GiB class ceiling in preflight_alloc) — always runs, on every arch, whether the host headroom guard is active or not. A configuration that does not fit the deployment target is refused regardless of this box’s RAM.

scripts/run-bounded.sh (HIPFIRE_MEM_CAP) remains the hard cgroup backstop.

Prompt / assistant-turn cache

Multi-turn DFlash and the prefix cache: when a DFlash turn ends on EOS (or the think cap) mid-window, RepairForTerminal restores the pre-window recurrent state and replays only the consumed prefix so the prompt/prefix cache stays warm. The next turn prefills only the new suffix instead of a full cold prefill (the previous fail-closed path reset and invalidated the cache).

Chat template overrides

Lowered directly into the startup/load policy. HIPFIRE_CHAT_TEMPLATE_FILE and HIPFIRE_DEFAULT_CHATML remain legacy one-shot aliases.

Per-model overlay

hipfire config qwen3.5:9b set dflash_mode off
hipfire config qwen3.5:9b          # list resolved model policy

Only explicitly set keys are stored; others inherit global. Primary path: ~/.hipfire/models.toml. Legacy models.json and per_model_config.json are migration inputs and are not native write targets.

Legacy-compatible one-shot env overrides (examples)

Full inventory: env-vars.md. Prefer hipfire config set for persistent policy. Parent-process values still take precedence for one-shot bisects and compatibility:

HIPFIRE_KV_MODE=q8
HIPFIRE_ATTN_FLASH=never
HIPFIRE_NORMALIZE_PROMPT=0
HIPFIRE_SPECULATION=off
HIPFIRE_DFLASH_DRAFT=/path/to/draft.hfq
HIPFIRE_LOCAL=1
HIPFIRE_MODEL=qwen3.5:9b

Typed daemon snapshots

The CLI resolves TOML, registry, one-shot flags, and compatibility input into a versioned ProcessConfig before the GPU is initialized. The daemon revalidates that envelope and lowers stable runtime values through RuntimeConfig::from_process_config; FeatureFlags performs the corresponding kernel-policy lowering. Direct daemon invocation resolves local TOML plus the compatibility environment into the same ProcessConfig first. Neither path uses ambient variables in engine hot paths.

kernel.lm_head_f16 maps the live Qwen3.5/3.6 loader compatibility control HIPFIRE_LM_HEAD_F16; the duplicate unused RuntimeConfig member was removed. The similarly unused RuntimeConfig::dflash_draft member was removed rather than promoted. Draft selection remains part of the typed speculation/load policy and filename/registry discovery.

Note: CLI ddtree_budget default is 0 while bare RuntimeConfig default is 256 when only env/runtime path is used — CLI load params are the product path for hipfire run/serve.

Redline eligibility helper mq4r_redline_default (same file) is a narrow runtime-default predicate for replay backend selection (exact GPU arch gfx1100/gfx1151/gfx1201 + case-insensitive .mq4r + pp=tp=1; model-family agnostic, no arch_id gate; gfx1200 and all other arches remain opt-in), not a general config key and not Redline certification/registry admission. Built-in hip config profile or an explicit backend selection disables the automatic default. Policy: REDLINE.md.

Related