ModelForge/.env.example

# ITWorx ModelForge 1.2.1 — configuration example
#
# Generated by scripts/generate_configuration_docs.py. Do not edit by hand.
# Copy to .env and fill in the values marked REQUIRED. See docs/CONFIGURATION.md.
#
# Secrets are intentionally empty here. This file is committed to the repository, so a
# real value placed in it would be published with the release.

# Deployment profile. 'production' turns on every fail-closed startup rule; 'development' and 'test' report the same problems without refusing to start.
MODELFORGE_ENV=development

# Interface the API binds inside its container. Leave at 0.0.0.0.
MODELFORGE_API_HOST=0.0.0.0

# Port the API listens on inside its container.
MODELFORGE_API_PORT=8000

# Pre-parser request-body limit for public and operator control-plane routes.
MODELFORGE_CONTROL_PLANE_MAX_PAYLOAD_BYTES=1048576

# Name this process reports in logs and audit events.
MODELFORGE_SERVICE_NAME=modelforge-api

# Structured log level: DEBUG, INFO, WARNING or ERROR.
MODELFORGE_LOG_LEVEL=INFO

# SQLAlchemy URL for the API's non-owner modelforge_runtime role. It may read the audit trail and execute the canonical append function, but cannot mutate audit tables directly. (REQUIRED in production)
MODELFORGE_DATABASE_URL=

# SQLAlchemy URL for the non-superuser modelforge schema-owner role. Set only in the one-shot migration process; production API startup refuses when this secret is present.
MODELFORGE_MIGRATION_DATABASE_URL=

# Redis URL for transient request payloads and queues. (REQUIRED in production)
MODELFORGE_REDIS_URL=redis://localhost:6379/0

# Comma-separated exact origins allowed to call the API from a browser. A wildcard is refused in production because requests are credentialed.
MODELFORGE_CORS_ORIGINS=http://localhost:3000

# Operator API key guarding every admin route. Generate at least 32 random characters; ModelForge never mints one for you. (REQUIRED in production)
MODELFORGE_OPERATOR_API_KEY=

# Optional Hugging Face token, used only for acquiring gated repositories. It is never passed to a runtime and never leaves the control plane.
MODELFORGE_HF_TOKEN=

# Base64 AES-256 key for backup encryption. Without it no backup can be produced, and without the same key no backup can be restored — store it outside this deployment. (REQUIRED in production)
MODELFORGE_BACKUP_ENCRYPTION_KEY=

# Identifier recorded in each backup manifest so a restore can name the key it needs.
MODELFORGE_BACKUP_ENCRYPTION_KEY_ID=modelforge-backup-key-1

# Hugging Face cache root inside the container.
MODELFORGE_HF_HOME=/data/hf-cache

# Verified model artifact root. Must exist and be writable.
MODELFORGE_ARTIFACT_ROOT=/data/artifacts

# Where acquired artifacts are held until their checks pass.
MODELFORGE_QUARANTINE_ROOT=/data/quarantine

# Artifact root as a runtime worker sees it on a compute node.
MODELFORGE_RUNTIME_ARTIFACT_ROOT=/models/model-registry

# Backup destination. Must exist and be writable, or backups fail closed.
MODELFORGE_BACKUP_ROOT=/data/backups

# Working directory a restore stages into before it commits.
MODELFORGE_BACKUP_RESTORE_ROOT=/data/restore

# Per-request timeout for Hugging Face metadata calls.
MODELFORGE_HF_TIMEOUT_SECONDS=30

# How long a resolved upstream snapshot stays cached.
MODELFORGE_HF_SNAPSHOT_TTL_SECONDS=3600

# Whether model repositories may execute their own Python. Always false in production; startup refuses any other value there.
MODELFORGE_ALLOW_REMOTE_CODE=false

# Collect GPU telemetry on this host.
MODELFORGE_ENABLE_GPU_TELEMETRY=true

# Run a hardware inventory pass when the process starts.
MODELFORGE_HARDWARE_REFRESH_ON_STARTUP=false

# Interval between hardware inventory passes.
MODELFORGE_HARDWARE_POLL_INTERVAL_SECONDS=30

# Explicit node identity. Leave empty to use the persisted file.
MODELFORGE_NODE_IDENTITY=

# 'persisted' keeps a node's identity across restarts; 'auto' derives it.
MODELFORGE_NODE_IDENTITY_MODE=auto

# Where a persisted node identity is stored.
MODELFORGE_NODE_IDENTITY_FILE=/data/state/node-id

# Silence after which a node is considered stale.
MODELFORGE_NODE_STALE_AFTER_SECONDS=30

# Silence after which a node is considered offline. Must exceed the stale threshold.
MODELFORGE_NODE_OFFLINE_AFTER_SECONDS=90

# How often node liveness is re-evaluated.
MODELFORGE_LIVENESS_POLL_INTERVAL_SECONDS=5

# Clock skew tolerated on an agent report before refusal.
MODELFORGE_AGENT_MAX_CLOCK_SKEW_SECONDS=300

# Pre-parser request-body limit for enrollment and authenticated Node Agent reports.
MODELFORGE_NODE_AGENT_MAX_PAYLOAD_BYTES=4194304

# Run the node liveness monitor in this process.
MODELFORGE_NODE_LIVENESS_MONITOR_ENABLED=false

# Maximum inputs accepted in a single capability invocation.
MODELFORGE_GATEWAY_MAX_BATCH_SIZE=8

# Maximum characters per input item.
MODELFORGE_GATEWAY_MAX_INPUT_CHARACTERS=8192

# Maximum accepted request body size.
MODELFORGE_GATEWAY_MAX_PAYLOAD_BYTES=65536

# Total time a capability invocation may take. Must exceed the queue timeout.
MODELFORGE_GATEWAY_REQUEST_TIMEOUT_SECONDS=45

# How long a request may wait for capacity before rejection.
MODELFORGE_GATEWAY_QUEUE_TIMEOUT_SECONDS=30

# Lease held by a serving job before it is reclaimed.
MODELFORGE_SERVING_JOB_LEASE_SECONDS=120

# How long a request payload survives in Redis.
MODELFORGE_SERVING_PAYLOAD_TTL_SECONDS=120

# VRAM never offered to a placement, as an absolute floor.
MODELFORGE_SCHEDULER_SAFETY_RESERVE_BYTES=1073741824

# VRAM never offered to a placement, as a fraction. Half a device leaves nothing schedulable.
MODELFORGE_SCHEDULER_SAFETY_RESERVE_PERCENTAGE=0.05

# Headroom reserved for runtime overhead per node.
MODELFORGE_SCHEDULER_RUNTIME_MARGIN_BYTES=268435456

# Absolute headroom added to each deployment estimate.
MODELFORGE_SCHEDULER_DEPLOYMENT_MARGIN_BYTES=134217728

# Proportional headroom added to each estimate.
MODELFORGE_SCHEDULER_DEPLOYMENT_MARGIN_PERCENTAGE=0.1

# Queued requests accepted before capacity rejection begins.
MODELFORGE_SCHEDULER_GLOBAL_QUEUE_LIMIT=128

# Telemetry age past which admission is blocked rather than extrapolated.
MODELFORGE_SCHEDULER_TELEMETRY_STALE_SECONDS=90

# How long pressure must hold before the state changes.
MODELFORGE_SCHEDULER_PRESSURE_STABLE_SECONDS=30

# Minimum interval between evictions on a node.
MODELFORGE_SCHEDULER_EVICTION_COOLDOWN_SECONDS=60

# Placement decisions retained for inspection.
MODELFORGE_SCHEDULER_PLACEMENT_HISTORY_LIMIT=500

# Seed the candidate and project registries from manifests.
MODELFORGE_REGISTRY_SEED_ON_STARTUP=false

# Reconcile abandoned serving work in this process.
MODELFORGE_SERVING_RECONCILIATION_ENABLED=false

# Interval between serving reconciliation passes.
MODELFORGE_SERVING_RECONCILIATION_INTERVAL_SECONDS=5

# Roll back incomplete lifecycle operations at startup.
MODELFORGE_LIFECYCLE_RECONCILIATION_ENABLED=false

# Report interrupted migration cutovers at startup. They are never auto-resolved: external alias truth cannot be inferred after a crash.
MODELFORGE_MIGRATION_RECONCILIATION_ENABLED=false

# Run SLO and alert evaluation in this process.
MODELFORGE_OBSERVABILITY_MONITOR_ENABLED=false

# Interval between observability evaluation passes.
MODELFORGE_OBSERVABILITY_POLL_INTERVAL_SECONDS=60

# Reconcile interrupted backups and restores at startup.
MODELFORGE_RECOVERY_RECONCILIATION_ENABLED=false

# pg_dump executable. Must match the server major version.
MODELFORGE_BACKUP_PG_DUMP_PATH=pg_dump

# pg_restore executable.
MODELFORGE_BACKUP_PG_RESTORE_PATH=pg_restore

# psql executable.
MODELFORGE_BACKUP_PSQL_PATH=psql

# Timeout for a dump or restore command.
MODELFORGE_BACKUP_COMMAND_TIMEOUT_SECONDS=1800

# Age past which the newest verified backup raises BACKUP_STALE.
MODELFORGE_BACKUP_STALE_AFTER_SECONDS=93600

# Free space below which a backup refuses to start.
MODELFORGE_BACKUP_MINIMUM_FREE_BYTES=1073741824

# Required free space as a multiple of the estimated size.
MODELFORGE_BACKUP_CAPACITY_HEADROOM_RATIO=3.0

# Whether a restore may overwrite the live database. Keep false outside a rehearsal.
MODELFORGE_RESTORE_ALLOW_PRODUCTION_TARGET=false

# --------------------------------------------------------------------------
# Deployment variables. Read by Compose, the Node Agent and the Runtime Worker
# rather than by the control-plane process - an operator still has to set them.
# --------------------------------------------------------------------------

# Host address the control-plane database is published on. Defaults to 127.0.0.1; publishing it more widely exposes provenance, credential hashes and the audit trail.
MODELFORGE_POSTGRES_BIND=

# Host address Redis is published on. Defaults to 127.0.0.1.
MODELFORGE_REDIS_BIND=

# Host address the API is published on. Defaults to 0.0.0.0 deliberately: the console and compute nodes need it, and every admin route is operator-authenticated.
MODELFORGE_API_BIND=

# Host address the console is published on. Defaults to 127.0.0.1.
MODELFORGE_WEB_BIND=

# Host port the database is published on. Defaults to 5432.
MODELFORGE_POSTGRES_PORT=

# Host port Redis is published on. Defaults to 6379.
MODELFORGE_REDIS_PORT=

# Host port the API is published on. Defaults to 8000.
MODELFORGE_API_PUBLISHED_PORT=

# Host port the console is published on. Defaults to 3000.
MODELFORGE_WEB_PORT=

# Host address for the DR rehearsal database. Loopback only.
MODELFORGE_DR_POSTGRES_BIND=

# Host address for the DR rehearsal API. Loopback only.
MODELFORGE_DR_API_BIND=

# API base URL compiled into the console. Vite inlines it at build time, so changing it requires rebuilding the console image, not restarting it.
VITE_API_BASE_URL=

# Production database name. Required by the production overlay.
MODELFORGE_POSTGRES_DB=

# Bootstrap/admin role used only by PostgreSQL provisioning; defaults to postgres.
MODELFORGE_POSTGRES_ADMIN_USER=

# Bootstrap/admin password; never passed to the migration or API container. (REQUIRED in production)
MODELFORGE_POSTGRES_ADMIN_PASSWORD=

# Raw password supplied to provisioning for the non-superuser modelforge owner role. (REQUIRED in production)
MODELFORGE_MIGRATION_DB_PASSWORD=

# Raw password supplied to provisioning for the non-owner modelforge_runtime role. (REQUIRED in production)
MODELFORGE_RUNTIME_DB_PASSWORD=

# Non-owner runtime-role URL passed only to the API container. (REQUIRED in production)
MODELFORGE_RUNTIME_DATABASE_URL=

# Exact version tag applied to built images and required when the production overlay is not given explicit API and web image references.
MODELFORGE_VERSION=

# Source commit stamped into images at build time.
MODELFORGE_COMMIT=

# Build timestamp stamped into images.
MODELFORGE_BUILT_AT=

# Exact tag or digest the production overlay runs for the API; never use latest.
MODELFORGE_API_IMAGE=

# Exact tag or digest the production overlay runs for the console; never use latest.
MODELFORGE_WEB_IMAGE=

# Exact release tag or digest for the standalone Node Agent. The local-build fallback is named local and never resolves to latest.
MODELFORGE_NODE_AGENT_IMAGE=

# Digest recorded as the running API build identity.
MODELFORGE_API_IMAGE_DIGEST=

# Volume or bind path backing the backup root.
MODELFORGE_BACKUP_VOLUME=

# Volume or bind path backing the restore staging root.
MODELFORGE_RESTORE_VOLUME=

# Volume or bind path holding the agent's persisted identity.
MODELFORGE_AGENT_STATE_VOLUME=

# Volume or bind path for the agent's Hugging Face cache.
MODELFORGE_AGENT_HF_CACHE_VOLUME=

# Volume or bind path for verified artifacts on a node.
MODELFORGE_AGENT_ARTIFACT_VOLUME=

# Volume or bind path for the node's quarantine area.
MODELFORGE_AGENT_QUARANTINE_VOLUME=

# URL the agent reports to. Outbound only; the control plane never dials a node.
MODELFORGE_AGENT_CONTROL_PLANE_URL=

# Single-use enrolment token. Consumed atomically: a storm against one token produces exactly one identity.
MODELFORGE_AGENT_ENROLLMENT_TOKEN=

# Hostname the agent enrols under.
MODELFORGE_AGENT_HOSTNAME=

# Accelerator contract: nvidia fails closed unless NVML inventory and telemetry are valid; cpu permits a legitimate CPU-only node; auto requires NVIDIA when injected devices are observed. Canonical GPU Compose deployments set nvidia explicitly.
MODELFORGE_AGENT_ACCELERATOR_MODE=

# Whether the agent verifies the control plane's certificate. True wherever TLS is real.
MODELFORGE_AGENT_TLS_VERIFY=

# Host address mapped for a private-CA deployment.
MODELFORGE_AGENT_CONTROL_PLANE_HOST_ADDRESS=

# Path to the private CA certificate the agent trusts.
MODELFORGE_AGENT_CA_CERT_PATH=

# Artifact root as the runtime worker sees it.
MODELFORGE_RUNTIME_WORKER_ARTIFACT_ROOT=

# Worker poll interval, in seconds.
MODELFORGE_RUNTIME_WORKER_POLL_INTERVAL_SECONDS=

# Source commit reported by the deployment.
MODELFORGE_SOURCE_COMMIT=

# Git reference reported by the deployment.
MODELFORGE_SOURCE_REFERENCE=

# Repository URL reported by the deployment.
MODELFORGE_SOURCE_REPOSITORY=