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_HISTORY_DB |
string | — | — | Path to the cross-run healing history SQLite db. |