Environment Variables
Overview
| Aspect |
Details |
| Purpose |
Environment-level toggles for network access, evaluation, snapshots, and docs tooling. |
| Audience |
CLI users and operators tuning runtime behavior. |
| Scope |
CLI commands and programmatic runs; config values override env when both are set. |
| Network |
Offline by default; network must be explicitly enabled. |
| Source of truth |
docs/reference/env-vars.md, src/invarlock/cli/commands/*, src/invarlock/cli/backend_runtime.py, src/invarlock/runtime_security.py, src/invarlock/core/runner.py. |
Quick Start
# Allow model + dataset downloads for a single command
INVARLOCK_ALLOW_NETWORK=1 invarlock evaluate --baseline gpt2 --subject gpt2
# Force evaluation device for a one-off compare/evaluate run
INVARLOCK_EVAL_DEVICE=cpu INVARLOCK_ALLOW_NETWORK=1 \
invarlock evaluate --baseline gpt2 --subject gpt2 --device cpu
Concepts
- Offline-first: all network access is opt-in and must be explicitly enabled.
- Precedence: when a setting exists in both env + config/CLI, the winner is
setting-specific (see the matrix below).
- Auditability: selected env flags are recorded in
report.meta.env_flags for
traceability.
Precedence (conflict cases)
- CLI/config values for assurance-critical policy (strictness, drift/acceptance bands, overhead skip, tiny relax).
- Env overrides only for explicitly env-scoped toggles (for example, downloads and calibration materialization).
- Packaged defaults when no explicit setting exists.
Key override matrix
| Setting |
Env var |
Config/CLI |
Winner rule |
How to confirm |
| Calibration materialize |
INVARLOCK_ALLOW_CALIBRATION_MATERIALIZE |
context.eval.materialize_calibration / context.eval.allow_iterable_calibration |
Env wins. |
Config shows in report.context; env is not recorded. |
| Network downloads |
INVARLOCK_ALLOW_NETWORK |
— |
Env-only toggle. |
Not recorded; rely on env. |
| Offline datasets |
HF_DATASETS_OFFLINE |
— |
Env-only toggle. |
Not recorded; rely on env. |
Conflict examples
| Scenario |
Result |
Fix |
context.run.skip_overhead_check: true in --profile release |
Overhead check is skipped and recorded in guard_overhead.source. |
Set context.run.skip_overhead_check: false for full overhead enforcement. |
context.run.tiny_relax: true |
Tiny-relax gating is enabled from config and recorded in auto.tiny_relax. |
Remove or set to false for full policy strictness. |
Reference
Network & data
| Variable |
Default |
Purpose |
INVARLOCK_ALLOW_NETWORK |
unset |
Enable outbound downloads for models/datasets. |
HF_DATASETS_OFFLINE |
unset |
Force Hugging Face datasets to use local cache only. |
Model loading
| Variable |
Default |
Purpose |
INVARLOCK_ALLOW_REMOTE_CODE |
unset |
Explicitly allow remote model code execution. |
INVARLOCK_ALLOW_REMOTE_CODE is the only environment gate for remote model
code execution. Use INVARLOCK_ALLOW_REMOTE_CODE=1 or --allow-remote-code
when remote code is required.
Evaluation & pairing
| Variable |
Default |
Purpose |
INVARLOCK_BOOTSTRAP_BCA |
unset |
Prefer BCa bootstrap CIs when sample size allows. |
INVARLOCK_TINY_RELAX |
unset |
Doctor-only hint for tiny local demos (does not drive assurance gates). |
INVARLOCK_EVAL_DEVICE |
unset |
Force evaluation device (cpu, cuda, mps). |
INVARLOCK_STORE_EVAL_WINDOWS |
1 |
Store token windows in reports (set 0 to disable). |
INVARLOCK_ALLOW_CALIBRATION_MATERIALIZE |
unset |
Allow materializing iterables lacking __len__. |
Dataset preparation
| Variable |
Default |
Purpose |
INVARLOCK_CAPACITY_FAST |
unset |
Approximate capacity estimation for quick runs. |
INVARLOCK_DEDUP_TEXTS |
unset |
Exact-text dedupe before tokenization. |
INVARLOCK_HF_DATASETS_CACHE |
unset |
Override the writable fallback cache used when HF dataset loads hit a shared-cache lock/permission error. |
| Variable |
Default |
Purpose |
INVARLOCK_OMP_THREADS |
1 |
Thread caps for determinism preset. |
INVARLOCK_DEBUG_TRACE |
unset |
Verbose debug traces for data/eval paths. |
INVARLOCK_LIGHT_IMPORT |
unset |
Avoid heavy imports for docs/tests. |
Checkpointing & snapshots
| Variable |
Default |
Purpose |
INVARLOCK_SNAPSHOT_MODE |
auto |
auto, bytes, or chunked snapshot strategy. |
INVARLOCK_SNAPSHOT_AUTO_RAM_FRACTION |
0.4 |
RAM fraction threshold for auto mode. |
INVARLOCK_SNAPSHOT_THRESHOLD_MB |
768 |
Size threshold for chunked snapshots. |
Model export
| Variable |
Default |
Purpose |
INVARLOCK_EXPORT_MODEL |
unset |
Enable HF export during model-export capable CLI flows. |
INVARLOCK_EXPORT_DIR |
unset |
Target directory for model export. |
Guarding & evidence
| Variable |
Default |
Purpose |
INVARLOCK_ASSERT_GUARDS |
unset |
Enable guard runtime assertions. |
INVARLOCK_EVIDENCE_DEBUG |
unset |
Emit guards_evidence.json for audit. |
Primary-metric gate bounds are profile/config settings (primary_metric.acceptance_range
and primary_metric.drift_band), not environment overrides.
Strictness/tiny-relax/overhead-skip are also config/profile policy:
context.eval.strict / context.eval.strict_errors, context.run.strict_guard_prepare,
context.run.tiny_relax, context.run.skip_overhead_check.
Config loading
| Variable |
Default |
Purpose |
INVARLOCK_CONFIG_ROOT |
unset |
Override packaged runtime/ data. |
INVARLOCK_ALLOW_CONFIG_INCLUDE_OUTSIDE |
unset |
Allow YAML !include outside config dir. |
Reporting & telemetry
| Variable |
Default |
Purpose |
INVARLOCK_TELEMETRY |
unset |
Emit single-line telemetry summary. |
Plugins
| Variable |
Default |
Purpose |
INVARLOCK_ALLOW_THIRD_PARTY_PLUGINS |
unset |
Enable third-party plugin discovery. |
INVARLOCK_MINIMAL |
unset |
Show minimal plugin list in invarlock advanced plugins. |
Runtime enforcement
| Variable |
Default |
Purpose |
INVARLOCK_ALLOW_HOST_EXECUTION |
unset |
Advanced/internal host-execution override. Prefer invarlock evaluate --execution-mode host for the public compare/evaluate path. |
INVARLOCK_CONTAINER_EXECUTION |
unset |
Internal recursion guard marking runtime-container execution. |
INVARLOCK_CONTAINER_ENGINE |
unset |
Force the OCI engine used for default runtime-container execution (podman or docker). |
INVARLOCK_RUNTIME_IMAGE |
unset |
Override the OCI image used for containerized model execution. |
INVARLOCK_RUNTIME_IMAGE_DIGEST |
unset |
Supply the immutable digest recorded into runtime.manifest.json. |
Docs build
| Variable |
Default |
Purpose |
INVARLOCK_DOCS_MERMAID |
unset |
Enable Mermaid diagrams in MkDocs. |
INVARLOCK_DOCS_EXTRA_JS |
unset |
Extra JavaScript URLs for docs build. |
Troubleshooting
- Downloads blocked: set
INVARLOCK_ALLOW_NETWORK=1 and retry.
- Multiple container engines installed: set
INVARLOCK_CONTAINER_ENGINE=podman or INVARLOCK_CONTAINER_ENGINE=docker.
- HF dataset cache lock/permission errors on local reruns: set
INVARLOCK_HF_DATASETS_CACHE=/path/to/writable/cache or let InvarLock retry under its own writable cache.
- Calibration iterables fail: use
INVARLOCK_ALLOW_CALIBRATION_MATERIALIZE=1.
- Third-party plugins missing: set
INVARLOCK_ALLOW_THIRD_PARTY_PLUGINS=1 or use --allow-third-party-plugins.
Observability
report.meta.env_flags records selected env toggles.- reports capture telemetry and policy digests derived from these flags.