Environment Variable Reference¶

Complete reference for all configuration environment variables.

Time to read: ~10 min Prerequisites: None

Configuration Cascade¶

Configuration priority hierarchy and feature toggles overview.

Overview¶

Configuration is managed through environment variables. Set these in:

• .env file in the project root
• Shell environment (export VAR=value)
• Container environment (docker-compose.prod.yml service environment: blocks)

Priority: Environment > .env > Defaults (pydantic-settings resolution order). The settings classes read .env via env_file=".env" (no env_prefix on the main Settings class, so env vars are the uppercased field names; exceptions are noted per row).

Database¶

Format: postgresql+asyncpg://user:password@host:port/database

Examples:

# Local development
DATABASE_URL=postgresql+asyncpg://security:password@localhost:5432/security

# Docker container
DATABASE_URL=postgresql+asyncpg://security:password@postgres:5432/security

Redis¶

Connection¶

Format: redis://[password@]host:port[/database] or rediss:// for TLS

Examples:

# Local development
REDIS_URL=redis://localhost:6379/0

# Docker container
REDIS_URL=redis://redis:6379/0

# With password
REDIS_URL=redis://:password@localhost:6379/0

# TLS
REDIS_URL=rediss://redis-host:6379/0

Redis SSL/TLS¶

AI Services¶

Service URLs¶

Note: In deployed containers all five router services are reached through the AI Gateway on ai-gateway:8090 — e.g. http://ai-gateway:8090/florence, /clip, /enrichment, /enrich-lt (set by docker-compose.prod.yml; .env.example ships the host-side equivalents on localhost:8090). The localhost:809x defaults above are the standalone-service dev ports. The standalone Nemotron LLM (compose service ai-llm) is the only AI service not routed through the gateway; the gateway routes /yolo26 /clip /florence /enrichment /enrich-lt (ai/gateway/main.py).

Warning: Use HTTPS in production to prevent MITM attacks.

Service Authentication¶

Service Timeouts¶

Enrichment Feature Toggles¶

These control enrichment behaviors in the backend. Defaults are designed for “rich context”, but you can disable them if you’re resource constrained or running without those services.

Florence Feature Toggles¶

Re-ID / Scene Change Tuning¶

Note: REID_SIMILARITY_THRESHOLD is tuned to the OSNet-AIN x1.0 person-vector space (512-d); the CLIP-era 0.85 would drop every legitimate OSNet match. The 0.7 default is PROVISIONAL pending calibration against real household galleries.

Image Quality Assessment¶

Enrichment Circuit Breakers¶

CLIP Circuit Breakers¶

Florence Circuit Breakers¶

AI Service Retries¶

AI Concurrency¶

Note: The default is resolved at startup by _get_default_inference_limit() in backend/core/config.py: 20 when running free-threaded Python (3.13t/3.14t with the GIL disabled), 4 on standard GIL builds.

Nemotron Context Window¶

Note: NEMOTRON_CONTEXT_WINDOW reads from the CTX_SIZE env var (validation_alias="CTX_SIZE" — single source of truth shared with llama.cpp). docker-compose.prod.yml passes CTX_SIZE=262144 (8 parallel slots x 32K) and PARALLEL=8 to both the ai-llm and backend containers — the backend block's defaults mirror the ai-llm service — so the backend divides the same pool by the same slot count. docker-compose.ghcr.yml passes CTX_SIZE=4096 / PARALLEL=2 to its backend: that file's ai-llm service sets only CTX_SIZE=4096, and the ghcr ai-llm image bakes PARALLEL=2 (ai/nemotron/Dockerfile) with no override passed.

Note: PARALLEL maps to llama_slot_count (validation_alias="PARALLEL") — llama.cpp's --parallel slot count. Slots share one CTX_SIZE pool, so the per-request budget above is derived as CTX_SIZE / PARALLEL.

AI Warmup Settings¶

Camera Integration¶

Camera images are expected at: {FOSCAM_BASE_PATH}/{camera_name}/

File Watcher¶

Note: Enable polling for Docker Desktop on macOS/Windows where inotify doesn't work across volume mounts.

Detection Settings¶

Fast Path Settings¶

High-confidence detections can bypass batching for immediate alerts.

Status: The fast path is DISABLED by default. The threshold ships at 2.0 (an impossible value > 1.0) and the object-type list ships empty, as a second safety net — fast path bypasses enrichment, which caused Nemotron to produce inaccurate scores (NEM-5525). Do not lower the threshold or add object types without first adding enrichment to the fast-path code path.

Batch Processing¶

Retention¶

GPU Monitoring¶

Recommended values:

• 1-2s: Real-time debugging
• 5s: Balanced (default)
• 15-30s: Lower overhead under pressure
• 60s: Minimal monitoring

Deduplication¶

Severity Thresholds¶

Risk score ranges for severity levels. See Risk Levels Reference.

Constraint: 0 <= low_max < medium_max < high_max <= 100

Logging¶

API Server¶

Authentication¶

Example:

API_KEY_ENABLED=true
API_KEYS=["key1-here", "key2-here"]

Rate Limiting¶

WebSocket¶

TLS/HTTPS Configuration¶

Modern Configuration (Recommended)¶

Legacy Configuration (Deprecated)¶

CORS¶

Notifications¶

Email (SMTP)¶

Webhooks¶

General¶

Queue Settings¶

Queue Overflow Policy Options¶

When the queue reaches QUEUE_MAX_SIZE, the system applies the configured overflow policy:

Consequences by policy:

• dlq (default): Overflowed items are moved to dlq:detection_queue or dlq:analysis_queue. No data loss but requires monitoring DLQ depth. Use /api/dlq/stats to check and /api/dlq/requeue-all/{queue_name} to recover items.

• reject: New detections are dropped when queue is full. Backend logs error Queue overflow: item rejected. Useful for alerting on capacity issues but causes immediate data loss.

• drop_oldest: Oldest queued items are removed to make space. Prioritizes freshness over completeness. May result in missed security events from earlier timeframes.

Recommendation: Use dlq (default) for production deployments. Monitor hsi:queue:dlq:* Redis keys or the /api/dlq/stats endpoint to detect overflow conditions.

Dead Letter Queue (DLQ)¶

Video Processing¶

Clip Generation¶

Service Health¶

Note: Set to false in containerized deployments where restart scripts aren't available.

Admin Endpoints¶

Security: Admin endpoints are enabled by default for single-user local deployments; network binding to 127.0.0.1 is the primary security boundary. The require_admin_access dependency (backend/api/routes/admin.py) gates on ADMIN_ENABLED alone — the DEBUG=true pairing in the config.py comment is not enforced in the route code.

Cache TTL Settings¶

Internal Service Timeouts¶

Worker Supervisor¶

Orchestrator Settings¶

Job Management¶

Pagination¶

Transcode Cache¶

Settings come from TranscodeCacheSettings (env_prefix="TRANSCODE_CACHE_").

Thumbnail Settings¶

Hardware Acceleration¶

Falls back to software encoding (libx264) when NVENC is unavailable. There is no HARDWARE_ACCEL_DEVICE variable — device selection is NVENC-only.

Performance Profiling¶

Slow Query Logging¶

Request Logging¶

REQUEST_LOGGING_BODY / REQUEST_LOGGING_HEADERS do not exist in the code — the request-logging layer (ObservabilityMiddleware, which merged RequestLoggingMiddleware in with NEM-5558) has no body/header options.

Request Recording¶

The recordings directory is not env-configurable — REQUEST_RECORDING_DIR does not exist; recordings land in data/recordings (DEFAULT_RECORDINGS_DIR, a constructor argument of RequestRecorderMiddleware).

HSTS Configuration¶

Only HSTS_PRELOAD is an env variable (config field passed to SecurityHeadersMiddleware in backend/main.py). The HSTS header itself is always sent on HTTPS responses with constructor defaults max-age=31536000 (1 year) and includeSubDomains=true — HSTS_ENABLED, HSTS_MAX_AGE and HSTS_INCLUDE_SUBDOMAINS are middleware constructor arguments, not env-configurable.

Idempotency¶

Background Evaluation¶

BACKGROUND_EVAL_ENABLED/BACKGROUND_EVAL_INTERVAL do not exist under those names. Evaluation is idle-gated, not fixed-interval: the documented "3600 s interval" had no counterpart in code — the closest knob, BACKGROUND_EVALUATION_POLL_INTERVAL, is the 5 s condition check.

Orphan File Cleanup¶

Configuration for periodic cleanup of orphaned files (files on disk without corresponding database records).

Safety: Files younger than ORPHAN_CLEANUP_AGE_THRESHOLD_HOURS are skipped to allow for incomplete processing. This prevents deletion of files that may still be in use.

Model Zoo¶

Configuration for the Model Zoo, which provides on-demand AI model loading during enrichment.

The Model Zoo contains supplementary AI models loaded on-demand during batch processing:

• License plate detection (yolo11-license-plate)
• Face detection (yolo11-face)
• OCR text extraction (paddleocr)
• Clothing segmentation (segformer-b2-clothes)
• Violence detection
• Weather classification
• And more

Note: Models are loaded sequentially within a ~1,650 MB VRAM budget (shared with the primary Nemotron and YOLO26 models).

Frontend (Build-Time)¶

The VITE_* variables are embedded at frontend build time; the FRONTEND_* port variables are consumed by docker-compose.prod.yml at deploy time:

FRONTEND_PORT=5173 is dead in docker-compose.prod.yml — the compose file never references it (5173 only survives as the Vite dev-server target in frontend/Dockerfile). It is still consumed by scripts/test-docker.sh and a setup.py port-scanner entry, but it does not affect deployed frontend ports.

Synthetic Benchmark¶

Next Steps¶

• Risk Levels Reference - Severity configuration details
• Troubleshooting - Configuration issues

See Also¶

• AI Configuration - AI-specific configuration
• Batching Logic - Batch timing configuration
• Local Setup - Development environment setup

Back to Operator Hub | Developer Hub