Environment variables

Owner: environment-variable inventory (docs/INDEX.md). Machine sources: HIPFIRE_* token scan of Rust, Python, and shell sources under the repo (excluding target/, .git/, etc.). Config schema owner: CONFIG.md (crates/hipfire-config/src/lib.rs + crates/hipfire-runtime/src/config.rs). Last checked: 2026-07-31.

For persistent user configuration, prefer hipfire config set ... and ~/.hipfire/config.toml. Schema-declared environment variables are retained as one-shot/compatibility overrides. The native CLI resolves stable typed fields and experimental [developer] values into one versioned daemon snapshot; see CONFIG.md.

This page has two layers:

1. Manual (normative for operators) — precedence, product-facing knobs, LFM/Redline branch scope, and pointers. Defaults here are grounded in CLI/runtime source cited inline.
2. Generated inventory — exhaustive name → example source path table from the scan. Presence in the inventory means the token appears in source; it does not mean the knob is supported, stable, or admitted.

Detailed procedures belong in domain owners (CONFIG.md, SERVE.md, multi-gpu.md, REDLINE.md, VALIDATION.md, methodology pages). This file does not host validation matrices or benchmark floors.

Coverage check for top-level docs: scripts/check-env-docs.py (every HIPFIRE_* in AGENTS.md / README.md / CONTRIBUTING.md must appear somewhere in this file).

Manual — precedence

1. Built-in typed defaults in hipfire-config / RuntimeConfig.
2. Registry card recommended_settings from registry/v1.json.
3. Global ~/.hipfire/config.toml.
4. Per-model overlay from ~/.hipfire/models.toml.
5. Compatibility environment layer for schema-declared HIPFIRE_* names.
6. One-shot CLI flags for the current command.

Legacy config.json, models.json, and per_model_config.json are read only as migration inputs when their TOML successors do not exist. Invoking the daemon binary directly still resolves local TOML plus compatibility variables before GPU initialization, but does not add registry/per-model policy that was not supplied by a native client.

Ladder for speculation selector (product path): HIPFIRE_SPECULATION / --spec > per-model > global > default auto.

Effective sampling send order (run/serve): CLI flags > per-model > registry recommended_settings > daemon/HFQ/arch fallback (field omitted when only a bare global default would apply). Global-only sampling edits are not sent; registry sampling blocks are inert metadata — see CONFIG.md / MODELS.md. Chat keeps a global session snapshot exception (CHAT.md).

TOML replacement for experimental variables

Production engine code no longer reads the ambient environment for kernel, architecture, replay, or diagnostic behavior. Stable controls use typed schema keys. Residual experiments use a flat global-only namespace:

[developer]
gfx1151_gate_up_wave64 = true
deepseek4_attn = "twin"

The generic compatibility rule is HIPFIRE_FOO=value → developer.foo = "value" at startup. This preserves existing harnesses while making TOML the persistent and navigable surface. [developer] values are process-scoped, excluded from registry and per-model policy, and frozen before GPU initialization. The only direct production environment reads left are bootstrap locations needed to discover config or launch the process (for example HIPFIRE_HOME, binary paths, registry URL, kernel cache, spill path, and quant diagnostic output).

Manual — product / operator knobs

Values and defaults below match hipfire-config, the native CLI, and/or RuntimeConfig as of the check date. Full key tables: CONFIG.md.

Paths and process

KV / attention / prompt

Speculation / DFlash / MTP / n-gram / DSpark

Vision tower sidecar

Graph / MMQ / prefill

LFM (arch 11) — branch-scoped optimized prefill

Eager LFM prefill remains available when the batch flag is off or the GPU is not gfx1201. On gfx1201 with HIPFIRE_LFM2_PREFILL_BATCH=1, selection is GPU+flag only with no post-selection fallback — unsupported cohorts fail closed at the runtime fixture validation/guard (exact 350M dense MQ4 fixture only). Source symbol validate_350m_mq4_admission is a fixture-shape check only; its name does not create a product admission — admissions.yml remains the sole authority (schema v2; exactly one earned retained-PM4 product row).

CASK / serve / multi-GPU

HIPFIRE_CASK_OFF is a retired compatibility name. The current Rust control plane does not consume it; use an empty memory.cask.sidecar and keep memory.cask.auto_attach=false instead. The old name remains only in a loader diagnostic and developer harness exports pending their cleanup.

Redline / retained replay

Policy owner: REDLINE.md (shipped / ref-pinned). Timing is not route-certified without same-report timed-arm proof. Registry admission is not canonical certification.

Chat template

Perf / diag (common)

Kernel-selector and arch-specific HIPFIRE_GFX* / HIPFIRE_RDNA* / HIPFIRE_MOE_* levers are research/power-user. Centralized FeatureFlags controls now have typed TOML keys under kernel or diagnostic.kernel; defaults and safety remain source-defined and none are registry-authorized.

Manual — top-level doc references

The canonical documentation checker requires every HIPFIRE_* token in AGENTS.md, README.md, and CONTRIBUTING.md to appear in this file. Tokens historically routed from those surfaces (keep listed even if a root file is later thinned):

HIPFIRE_ATTN_FLASH, HIPFIRE_DDTREE_ (prefix family; concrete vars in inventory), HIPFIRE_DFLASH_DRAFT, HIPFIRE_GRAPH, HIPFIRE_HOST_TIMING, HIPFIRE_KV_MODE, HIPFIRE_LM_HEAD_F16, HIPFIRE_LOCAL, HIPFIRE_NORMALIZE_PROMPT, HIPFIRE_PROMPT_HEAT_JSON, HIPFIRE_PROMPT_HEAT_LIMIT, HIPFIRE_PROMPT_TOKEN_HEAT, HIPFIRE_VERIFY_GRAPH.

Manual — TOML key → legacy environment compatibility

Compatibility map from the hipfire-config schema. TOML is the supported persistent surface. The native CLI sends typed policy directly to the daemon; it does not project these values into the child environment. The names below are accepted only as compatibility/one-shot input to the resolver. Message- field-only keys (temperature, thinking, …) have no compatibility alias.

Copyable user, developer, and retained-PM4 TOML profiles are in docs/configs/.

Manual — Cargo features (not env)

crates/hipfire-runtime/Cargo.toml default features (checked 2026-07-19):

arch-qwen35, arch-qwen35-vl, arch-llama, arch-qwen2, arch-deepseek4, arch-cohere2moe, arch-dots-ocr, deltanet.

hipfire-arch-lfm2moe / hipfire-arch-minimax are linked as ordinary dependencies on the loader/runtime graph (not named in that default feature list). Feature toggles are build-time, not HIPFIRE_* env.

Generated inventory

Do not hand-edit rows below except by re-running the source scan. Generation method: token scan over visible *.rs, *.py, and *.sh, excluding ignored/generated files. Columns: variable; up to two lexical source paths. Count: 737

Maintenance

# Independently verify concrete Rust HIPFIRE_* reads against table rows.
scripts/regen-env-vars-doc.sh

# Shipped env/docs coverage and production-ownership check.
python3 scripts/check-env-docs.py

Also match std::env::var_os("HIPFIRE_…") (e.g. HIPFIRE_KERNEL_CACHE in compiler.rs) — token scan catches the name regardless of var vs var_os.

When adding a user-facing knob:

1. Prefer a typed field + validation in crates/hipfire-config/src/lib.rs (CONFIG.md).
2. Add the env name to product docs only if operators must set it outside config.
3. Re-scan so the generated inventory stays complete.
4. Do not document unearned or widened LFM defaults here (multi-cohort, path/extension selection of .mq4, automatic runtime default for non-.mq4r, or generic default-on beyond the exact sealed admissions.yml evidence row). That LFM row is registry evidence without current automatic runtime wiring; only mq4r_redline_default auto-selects (.mq4r + exact GPU arch + pp=tp=1). Planned broader admissions may not be documented as shipped.

Last inventory verification: 2026-07-29.

Batched attention (SP1)