Environment variables

InvarLock keeps environment configuration narrow. Comparison intent belongs in request.yaml. Environment variables are alternatives for command options that supply secrets, independent verification anchors, OCI launch choices, and caller-owned provider resources.

Reference

• Surface: Public CLI, OCI launcher, provider-resource, and security environment variables
• Stability: Documented variables are public operator inputs; repository-test and add-in-internal variables are excluded
• Use this page when: Supplying key paths, independent verifier anchors, runtime-image identity, device selection, or caller-owned provider support

An explicit command option wins over its environment alternative. Empty values do not satisfy required paths, digests, fingerprints, or identities.

Diagram

Explicit command options override environment alternatives, while request YAML retains comparison intent and cannot set signing keys, independent trust anchors, or caller-owned host controls.

Transaction inputs

The receipt destination intentionally has no environment alternative. It must be an explicit new path outside the immutable evidence pack.

Variables contain key paths, not private-key bytes. Keep the evidence-signing key in a separate, caller-controlled location. Run-mode workers never receive that key: the host validates their side results and performs evidence signing and publication itself.

Host OCI worker launch

When the host CLI receives a valid execution.mode: run request, it automatically launches the transaction in Docker or Podman. These variables mirror the evaluate options:

If the image reference contains @sha256:..., it must agree with INVARLOCK_RUNTIME_IMAGE_DIGEST when both are supplied. If the image reference has no embedded digest, the separate digest is required and the launcher forms the immutable reference. Mutable tags without a pinned digest are rejected.

Each side image must already exist locally. The launcher uses --pull=never, disables networking, sets a read-only container root, drops capabilities, enables no-new-privileges, bounds process count, and provides a temporary filesystem. It also applies caller-owned CPU and memory ceilings and a numeric non-root identity. The prepared job and schedule, side artifact, and side support resources are mounted read-only. Each worker receives its own writable output directory and cannot read the other side's artifact. The host validates the closed side results before it computes, signs, or publishes evidence.

The submitted request cannot set these host controls. Its validated provider timeout_seconds and authenticated schedule length determine a finite outer worker deadline, capped at 24 hours. Timeout cleanup addresses the exact engine-issued container ID before terminating the attached engine process.

cuda exposes all available GPUs to the selected side worker. An indexed selection such as cuda:1 exposes that host GPU as cuda inside that worker. CPU/CPU and distinct explicit CUDA indexes may run in parallel. Generic CUDA, the same explicit CUDA index, and CPU/CUDA pairs run sequentially. These rules control worker scheduling; the authenticated schedule and record IDs establish the measurement pairing.

The auto entrypoint selects the NVIDIA entrypoint profile for TensorRT-LLM and the Python profile for the other first-party providers. Image, digest, device, and entrypoint defaults are resolved independently for baseline and subject after applying their per-side overrides.

Image-digest agreement identifies declared image bytes. It is not execution attestation and does not prove which physical host executed them.

Canonical Hugging Face runtime images

The repository has distinct CPU and CUDA image definitions. They are not interchangeable. Both build targets require the authenticated source commit, bundle path, and bundle digest described in the runtime-provider guide:

--runtime-device cuda and the matching environment variables expose a GPU to the selected worker. They do not install CUDA-enabled PyTorch in an image. Select an image built from runtime/Dockerfile.cuda for CUDA Hugging Face evaluation, and require make runtime-smoke-cuda on the intended NVIDIA host before relying on that image/device combination.

Example run environment

export INVARLOCK_RUNTIME_IMAGE='registry.example/invarlock-runtime-cuda@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
export INVARLOCK_RUNTIME_IMAGE_DIGEST='sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
export INVARLOCK_CONTAINER_ENGINE=docker
export INVARLOCK_RUNTIME_DEVICE=cuda
export INVARLOCK_SIGNING_KEY=keys/evidence-signer.pem

invarlock evaluate release-check/request.yaml

Replace the illustrative digest with the exact local CUDA image identity. Keep the signing-key path in a caller-controlled location; the host reads it only when signing the validated evidence bundle.

Equivalent explicit options are often clearer for one-off runs:

invarlock evaluate release-check/request.yaml \
  --signing-key keys/evidence-signer.pem \
  --runtime-image registry.example/invarlock-runtime-cuda@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
  --runtime-image-digest sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
  --container-engine docker \
  --runtime-device cuda

Import requests do not launch OCI workers and do not require these image, engine, device, or entrypoint inputs.

Optional provider resources

The GGUF (llama_cpp) add-in requires all three values together:

The TensorRT-LLM add-in requires both values together:

The Hugging Face vision-text add-in requires both values together:

Resource roots must be absolute non-symbolic directories. Support values must be portable relative paths beneath the root. Missing members, extra partial configuration, path escape, and symbolic-link transitions fail closed.

The primary artifact path remains in request.yaml. Executable, source, and tokenizer-support resources remain caller-controlled when they are provider inputs. The TensorRT-LLM runner is instead installed in and authenticated from the selected runtime image; a submitted request cannot replace it.

Security switches

These variables are false unless set to 1, true, yes, or on:

The strict run path explicitly disables network, remote code, and third-party runtime discovery inside each side worker. An installed scorer instead runs in the host evaluation or verification process after provider facts are authenticated. Authorize it only after reviewing the exact descriptor and package identity pinned by the request and policy. Independent verification must make its own authorization decision.

Validation and failure behavior

Operational guidance

• Prefer explicit options for one-off invocations and narrowly scoped environment variables in automation.
• Keep private-key bytes out of environment variables.
• Keep artifact, schedule, runtime, signer, and policy anchors outside the submitted bundle and source them through a separate trusted path.
• Keep dataset mapping, policy, built-in metric or scorer binding, and provider settings in the authenticated request, not environment variables.
• Record the exact image digest and engine/device selection with the comparison record; do not infer them from a mutable shell profile later.

Variables used only by repository tests, image builds, or add-in runner internals are not part of this public inventory. Treat this page and invarlock COMMAND --help as the supported operator surface.

Related documentation

• Command-line interface lists the matching command options.
• Evaluation request separates comparison intent from host authority.
• Runtime providers defines provider-specific identity and resource requirements.
• Evaluation lifecycle describes validation and publication boundaries.