Environment variables
Part of the NovaFabric CLI reference. Both nova and novafabric run the same binary.
Environment variables
| Variable | Default | Description |
|---|---|---|
NOVAFABRIC_HOME |
~/.novafabric |
Root directory for all NovaFabric data. Controls the default locations of the capsule spool, registry DB, audit log, and token file. Set this for Docker (/data/nova), multi-user, or non-default-home deployments. |
NOVAFABRIC_DB_PATH |
~/.novafabric/registry.db |
Path to the SQLite registry database |
OPENLINEAGE_URL |
— | HTTP endpoint for nova lineage emit-openlineage (and auto-emit at capture) |
OPENLINEAGE_FILE |
— | File path for nova lineage emit-openlineage (fallback if URL not set) |
NOVAFABRIC_CAPSULE_DIR |
$NOVAFABRIC_HOME/capsules |
Capsule storage root; overrides the NOVAFABRIC_HOME-derived default for all commands |
NOVA_OBJECT_STORE_BACKEND |
filesystem |
OCS backend: filesystem, s3, gcs, or azure. Set to s3 for production deployments. |
NOVA_OBJECT_STORE_PATH |
$NOVAFABRIC_HOME/capsules |
Root path for the filesystem OCS backend. Ignored when NOVA_OBJECT_STORE_BACKEND=s3. |
NOVA_S3_BUCKET |
— | S3 bucket name for the S3 OCS backend. Required when NOVA_OBJECT_STORE_BACKEND=s3. |
NOVA_S3_ENDPOINT_URL |
— | S3-compatible endpoint URL (e.g. http://minio:9000 for MinIO). Defaults to AWS S3 when unset. |
NOVAFABRIC_SPAN_ID |
— | Root span id injected into the subprocess |
NOVAFABRIC_SUGGEST |
1 |
Set to 0 to disable the asset registration suggestion prompt after nova capture. |
NOVAFABRIC_COMMUNITY_HINT |
1 |
Set to 0 to hide the one-line pointer to GitHub Discussions that nova capture prints after the first capsule in a directory, and that nova --version prints to stderr. Shown only on an interactive terminal; it is plain text, never a network call. |
NOVAFABRIC_ENVIRONMENT |
— | Deployment-environment tag recorded on captured capsules as deployment_environment with environment_source: env-var (ADR-0126). Overridden by nova capture --environment; overrides the SDK deployment_environment= argument. Distinct from the env.lock technical environment. |
NOVAFABRIC_CAPTURE_STRICT |
off | Truthy (1/true/yes/on) makes a capture that would overlap another in the same process raise ConcurrentCaptureRefused instead of degrading to a scoped, contended capsule (ADR-0224 OQ-2; works today, opt-in). Equivalent to install_all(..., strict=True). See multi-agent capture. |
NOVAFABRIC_VARIANT |
— | ADR-0116 (experimental, record-only): id of the externally assigned A/B variant (arm), recorded verbatim as variant.variant_id. Must be set together with NOVAFABRIC_VARIANT_EXPERIMENT and NOVAFABRIC_VARIANT_SOURCE (an incomplete set warns and is ignored). Overridden by the nova capture --experiment/--variant/--variant-source flags; overrides the SDK variant= argument. |
NOVAFABRIC_VARIANT_EXPERIMENT |
— | ADR-0116: experiment id recorded verbatim as variant.experiment_id. |
NOVAFABRIC_VARIANT_SOURCE |
— | ADR-0116: the external system that assigned the arm (e.g. launchdarkly, statsig), recorded verbatim as variant.assignment_source. Never defaulted — NovaFabric never allocates variants. |
NOVAFABRIC_VARIANT_LABEL |
— | ADR-0116 (optional): human-readable arm name recorded verbatim as variant.variant_label. |
NOVAFABRIC_VARIANT_ASSIGNED_AT |
— | ADR-0116 (optional): RFC 3339 UTC timestamp of the external assignment, recorded verbatim as variant.assigned_at. Never substituted with the capture time; a malformed value warns and is dropped (the arm itself is still recorded). |
NOVAFABRIC_GLOBAL_RUN_ID |
— | Distributed-run contract: parent run ID injected by SlurmRunner/KubernetesRunner into worker subprocesses. |
NOVAFABRIC_PARENT_RUN_ID |
— | Distributed-run contract: direct parent run ID for child capsule linkage. |
NOVAFABRIC_RANK |
— | Distributed-run contract: MPI/DDP rank of this worker (integer, 0-based). |
NOVAFABRIC_WORLD_SIZE |
— | Distributed-run contract: total number of workers in this distributed run. |
NOVAFABRIC_DISTRIBUTION_ROLE |
— | Distributed-run contract: driver or worker. |
NOVAFABRIC_FAIL_MODE |
warn |
Distributed-run contract: warn (log + continue) or fail (raise). Controls behaviour when parent capsule is not found. |
NOVAFABRIC_PENDING_PARENT_TIMEOUT |
30 |
Distributed-run contract: seconds to wait for the parent capsule directory to appear before proceeding. |
NOVAFABRIC_INFERENCE_ENGINE |
— | Inference-determinism contract (recorded in env.lock hardware.inference): serving engine, e.g. vllm, tgi, sglang. Best-effort; omitted when unset. |
NOVAFABRIC_INFERENCE_ENGINE_VERSION |
— | Inference-determinism contract: serving-engine version string. |
NOVAFABRIC_INFERENCE_TP_SIZE |
— | Inference-determinism contract: tensor-parallel size (integer ≥ 1). |
NOVAFABRIC_INFERENCE_PP_SIZE |
— | Inference-determinism contract: pipeline-parallel size (integer ≥ 1). |
NOVAFABRIC_INFERENCE_DTYPE |
— | Inference-determinism contract: compute/storage dtype, e.g. bfloat16, float16, fp8. |
NOVAFABRIC_INFERENCE_BATCH_SIZE |
— | Inference-determinism contract: max/observed batch size (integer ≥ 1); batch invariance affects determinism. |
NOVAFABRIC_INFERENCE_ATTENTION_BACKEND |
— | Inference-determinism contract: attention backend identifier. |
NOVAFABRIC_INFERENCE_SEED |
— | Inference-determinism contract: inference RNG seed (integer). |
NOVAFABRIC_INFERENCE_DETERMINISTIC |
— | Inference-determinism contract: 1/true/yes/on if the engine ran in a documented deterministic mode. |
NOVAFABRIC_POSTGRES_DSN |
— | Postgres DSN for nova doctor --check-storage and nova migrate-to-postgres |
NOVA_DSN |
— | Postgres DSN for nova server start (ADR-0029 resolution order) |
NOVA_BACKEND |
sqlite |
Storage backend for nova server start |
NOVA_SERVER_CONFIG |
— | Absolute path to nova-server.yaml (overrides default search paths) |
NOVAFABRIC_SERVER_HOST |
127.0.0.1 |
Bind address for nova server start. |
NOVAFABRIC_SERVER_PORT |
8000 |
TCP port for nova server start. |
NOVAFABRIC_SERVER_BACKEND |
sqlite |
Storage backend for nova server start: sqlite or postgres. |
NOVAFABRIC_SERVER_DB_PATH |
$NOVAFABRIC_HOME/registry.db |
SQLite DB path for nova server start when NOVAFABRIC_SERVER_BACKEND=sqlite. |
NOVA_OIDC_ENABLED |
false |
Enable OIDC authentication on the server |
NOVA_OIDC_ISSUER_URL |
— | OIDC issuer URL (e.g. https://keycloak.example.com/realms/nova) |
NOVA_OIDC_CLIENT_ID |
— | OIDC client ID registered at the provider |
NOVAFABRIC_OFFLINE_KEY_PATH |
~/.novafabric/keys/offline-key.pem |
Path to the ed25519 private key for offline tokens |
NOVA_ADMIN_TOKEN |
— | Bearer token with admin role, used by nova server flush-jwks-cache |
NOVAFABRIC_CLUSTER_ID |
— | Cluster identifier for collector and HPC hub binaries |
NOVAFABRIC_HUB_ADDRESS |
— | NATS hub address (e.g. nats://hub:4222) for HPC hub binary |
NOVASEAL_KMS_ENDPOINT |
— | NovaSeal KMS endpoint URL for collector batch signing |
NOVAFABRIC_KMS_LOCAL_WAL |
0 |
Set to 1 to use local dev key (dev only; never in production) |
NOVAFABRIC_ENV |
— | Set to production to block LocalWAL key usage |
NOVAFABRIC_SPOOL_BASE |
/tmp/novafabric |
Base directory for per-job HPC spool (Slurm Prolog) |
NOVAFABRIC_SPOOL_DIR |
$NOVAFABRIC_HOME/spool |
Local event spool drained by novafabric-spool-forwarder; written by nova capture --emit-spool (ADR-0092 slice C, experimental) |
NOVAFABRIC_SPOOL_STREAM |
NOVA_EVIDENCE |
JetStream stream the spool forwarder publishes to (novafabric-spool-forwarder --stream) |
NOVAFABRIC_SPOOL_SUBJECT |
nova.evidence |
JetStream subject prefix for the spool forwarder; per-run subject is <prefix>.<run_id> |
NOVA_BYPASS_NOTIFY_FILE |
— | Path to JSONL file for bypass event notifications (v0.24.0) |
NOVA_BYPASS_NOTIFY_WEBHOOK |
— | HTTP(S) URL for bypass event webhook notifications (v0.24.0) |
NOVA_EVENTS_LOG |
— | Path of the local append-only lifecycle-event log (events.jsonl); enables the file sink (ADR-0137, experimental) |
NOVA_EVENTS_WEBHOOK |
— | Lifecycle-event webhook URL(s), comma-separated; user-configured only, no default destination (ADR-0137, experimental) |
NOVA_EVENTS_MAX_RETRIES |
2 |
Bounded webhook retry count for lifecycle-event delivery (ADR-0137) |
NOVA_EVENTS_TIMEOUT_S |
5.0 |
Per-request webhook timeout in seconds for lifecycle-event delivery (ADR-0137) |
NOVA_EVENTS_SIGN_SECRET |
— | HMAC-SHA256 shared secret; enables lifecycle-event signing. Never written to config, the log, or any payload (ADR-0137) |
NOVA_EVENTS_SIGN_KEYID |
default |
Key identifier recorded in the lifecycle-event signature.keyid (ADR-0137) |
NOVA_INTEGRATION |
0 |
Set to 1 to enable integration-gated tests (metadata scale, JanusGraph) (v0.24.0) |
NOVAFABRIC_HPC_STORAGE |
— | Set to spool to use the JSONL spool as NATS leaf store (no local NVMe) |
NOVAFABRIC_EPILOG_FLUSH_TIMEOUT |
50 |
Slurm Epilog flush timeout in seconds (must stay below Slurm's PrologEpilogTimeout) |
NOVA_NATS_URL |
— | NATS server URL for NATSJetStreamConsumer (Evidence Fabric Tier 2); e.g. nats://nats:4222. Requires pip install novafabric[nats] (v0.29.0) |
NOVA_NATS_STREAM |
nova-evidence |
NATS JetStream stream name for Evidence Fabric consumer (v0.29.0) |
NOVA_NATS_SUBJECT |
nova.evidence.> |
NATS subject filter for Evidence Fabric consumer (v0.29.0) |
NOVA_NATS_CONSUMER |
nova-evidence-consumer |
NATS durable consumer name for Evidence Fabric consumer (v0.29.0) |
NOVA_CLICKHOUSE_URL |
— | ClickHouse HTTP URL for ClickHouseAccumulator (Evidence Fabric Tier 2); e.g. http://clickhouse:8123. Requires pip install novafabric[clickhouse]. Also enables nova cost report (v0.29.0) |
NOVA_CLICKHOUSE_DB |
nova |
ClickHouse database name used by ClickHouseAccumulator and nova cost report. |
NOVA_CLICKHOUSE_USER |
default |
ClickHouse username for Evidence Fabric Tier 2 connection. |
NOVA_CLICKHOUSE_PASSWORD |
`` | ClickHouse password for Evidence Fabric Tier 2 connection. |
NOVA_COLLECTOR_TOKEN |
— | Bearer token required on every request to the HPC collector HTTP API. Unset = no auth (local-dev only). |
NOVA_COLLECTOR_HEALTH_FILE |
$NOVAFABRIC_HOME/collector.health |
Path to the collector health-check file written by nova serve --collector. |
NOVA_CAP003_ENABLED |
false |
Set to true to activate the dual-object-store erasure path (cap-003 compliance). Requires S3 GOVERNANCE Object Lock. |
NOVA_DLQ_DIR |
— | Directory for the dead-letter queue. When set, events that fail forwarding are written here instead of dropped. |
NOVA_LIBSPOOL_PATH |
— | Absolute path to libspool.so for the CFFI collector spool. Auto-discovered from NOVA_LIBSPOOL_PATH; falls back to the bundled .so. |
NOVAFABRIC_REPLAY_QUEUE_PATH |
— | Socket/FIFO path used by the mocked replay engine to inject synthetic events into a running subprocess. Set automatically by nova replay --mode mocked. |
NOVAFABRIC_EVIDENCE_DIR |
$NOVAFABRIC_HOME/evidence |
Override directory for compliance evidence bundles (cap-001/002/004/005). Used by nova assure and serve endpoints. |
NOVAFABRIC_TOOL_PERMISSION_DB_PATH |
— | SQLite path for the tool-permission policy DB. Defaults to in-memory when unset (permissions are not persisted across restarts). |
NOVAFABRIC_GAIA_OCI_DIGEST |
— | OCI image digest pin for the GAIA eval container. Unset = default published digest. Override to use a private mirror or a specific version. |
NOVAFABRIC_GAIA_OCI_IMAGE |
— | OCI image reference for the GAIA eval container. Override to use a private registry. |
NOVAFABRIC_AGENTBENCH_OCI_DIGEST |
— | OCI image digest pin for the AgentBench eval container. |
NOVAFABRIC_AGENTBENCH_OCI_IMAGE |
— | OCI image reference for the AgentBench eval container. |
NOVAFABRIC_MMLU_OCI_DIGEST |
— | OCI image digest pin for the MMLU eval container. |
NOVAFABRIC_MMLU_OCI_IMAGE |
— | OCI image reference for the MMLU eval container. |
NOVAFABRIC_SWE_BENCH_OCI_DIGEST |
— | OCI image digest pin for the SWE-bench eval container. |
NOVAFABRIC_SWE_BENCH_OCI_IMAGE |
— | OCI image reference for the SWE-bench eval container. |