Configuration reference

All configuration is read from HEAL_* environment variables (the nearest .env is auto-loaded and overrides the process environment). This page is generated from the settings schema, so it always matches the installed version.

Feature switches

Master toggles and opt-in behaviours.

Variable	Type	Default	Constraints	Description
HEAL_ENABLED	boolean	True	—	Master switch for the healing engine.
HEAL_LOCATOR_TIERS	string	selection	matches ^(selection|generation)$	Locator pipeline: 'selection' (candidates + index pick, default) or 'generation' (DOM prompt).
HEAL_HEAL_ASSERTIONS	boolean	False	—	Enable assertion-drift healing (opt-in).
HEAL_FORM_FILL	boolean	False	—	Allow form-diagnosis to fill fields (opt-in; diagnose-only by default).
HEAL_FIX_TIER	report / patch / in-place	report	—	Highest fix-application tier allowed.
HEAL_WARM_START	boolean	True	—	Preload known broken->healed locator mappings from the healing history.

Default model

The model used for every agent role unless overridden below. Point HEAL_BASE_URL at any OpenAI-compatible endpoint or use a pydantic-ai provider string in HEAL_MODEL (e.g. openai:gpt-4.1-mini).

Variable	Type	Default	Constraints	Description
HEAL_MODEL	string	—	—	Default model name (e.g. 'MiniMax-M2.5' or 'openai:gpt-4.1-mini').
HEAL_BASE_URL	string	—	—	Default OpenAI-compatible endpoint base URL.
HEAL_API_KEY	string	—	—	Default API key for the endpoint.
HEAL_OUTPUT_MODE	auto / tool / native / prompted	auto	—	Default structured-output mode.

Per-role overrides

Each agent role (triage, locator, vision, rca) can override the default model, endpoint, key and output mode. Unset values fall back to the defaults above — so HEAL_MODEL alone is enough for simple setups.

Variable	Type	Default	Constraints	Description
HEAL_TRIAGE_MODEL	string	—	—	Model for the triage agent (falls back to HEAL_MODEL).
HEAL_TRIAGE_BASE_URL	string	—	—	Endpoint for the triage agent (falls back to HEAL_BASE_URL).
HEAL_TRIAGE_API_KEY	string	—	—	API key for the triage agent (falls back to HEAL_API_KEY).
HEAL_TRIAGE_OUTPUT_MODE	auto / tool / native / prompted	—	—	Output mode for the triage agent (falls back to HEAL_OUTPUT_MODE).
HEAL_LOCATOR_MODEL	string	—	—	Model for the locator agent (falls back to HEAL_MODEL).
HEAL_LOCATOR_BASE_URL	string	—	—	Endpoint for the locator agent (falls back to HEAL_BASE_URL).
HEAL_LOCATOR_API_KEY	string	—	—	API key for the locator agent (falls back to HEAL_API_KEY).
HEAL_LOCATOR_OUTPUT_MODE	auto / tool / native / prompted	—	—	Output mode for the locator agent (falls back to HEAL_OUTPUT_MODE).
HEAL_VISION_MODEL	string	—	—	Vision model for screenshot analysis (falls back to HEAL_MODEL).
HEAL_VISION_BASE_URL	string	—	—	Endpoint for the vision agent (falls back to HEAL_BASE_URL).
HEAL_VISION_API_KEY	string	—	—	API key for the vision agent (falls back to HEAL_API_KEY).
HEAL_VISION_OUTPUT_MODE	auto / tool / native / prompted	—	—	Output mode for the vision agent (falls back to HEAL_OUTPUT_MODE).
HEAL_RCA_MODEL	string	—	—	Model for the root-cause-analysis agent (falls back to HEAL_MODEL).
HEAL_RCA_BASE_URL	string	—	—	Endpoint for the RCA agent (falls back to HEAL_BASE_URL).
HEAL_RCA_API_KEY	string	—	—	API key for the RCA agent (falls back to HEAL_API_KEY).
HEAL_RCA_OUTPUT_MODE	auto / tool / native / prompted	—	—	Output mode for the RCA agent (falls back to HEAL_OUTPUT_MODE).

Budgets

Caps that keep healing bounded in CI. Breaching the run cap degrades to RCA-only instead of failing the test run.

Variable	Type	Default	Constraints	Description
HEAL_MAX_FAILURE_SECONDS	number	60.0	> 0	Wall-clock cap per healing transaction.
HEAL_MAX_FAILURE_TOKENS	integer	50000	> 0	Token cap per healing transaction.
HEAL_MAX_RUN_TOKENS	integer	2000000	> 0	Token cap per test run; breach degrades to RCA-only.
HEAL_REQUEST_LIMIT	integer	8	> 0	Max LLM requests per agent run within one transaction.
HEAL_AGENT_RETRIES	integer	3	≥ 0	Output-validator retries per agent run.

Timing recovery

Variable	Type	Default	Constraints	Description
HEAL_READY_TIMEOUT_SECONDS	number	20.0	> 0	Max wait for page-ready in timing recovery.

Reporting

Where artifacts and cross-run history are written.

Variable	Type	Default	Constraints	Description
HEAL_REPORT_DIR	string	—	—	Report directory; defaults to /heal.
HEAL_HISTORY_DB	string	—	—	Path to the cross-run healing history SQLite db.

Other

Variable	Type	Default	Constraints	Description
HEAL_PROBE_CAPABILITIES	boolean	True	—	Verify the resolved output mode works before healing with it, and fall back to a mode that does. One tiny call per endpoint, cached for the run.