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 rootShell environment (export VAR=value) Container environment (docker-compose.yml) Priority: Environment > .env > Defaults
Database Variable Required Default Range Description DATABASE_URLYes - - PostgreSQL connection URL DATABASE_POOL_SIZENo 205-100 Base number of database connections in pool DATABASE_POOL_OVERFLOWNo 300-100 Additional connections beyond pool_size DATABASE_POOL_TIMEOUTNo 305-120s Seconds to wait for available connection DATABASE_POOL_RECYCLENo 1800300-7200 Seconds after which connections are recycled
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 Variable Required Default Range Description REDIS_URLNo redis://localhost:6379/0- Redis connection URL REDIS_PASSWORDNo - - Redis password for authentication REDIS_POOL_SIZENo 5010-500 Maximum Redis connections in pool REDIS_KEY_PREFIXNo hsi- Global prefix for all Redis keys
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 Variable Required Default Description REDIS_SSL_ENABLEDNo falseEnable SSL/TLS for Redis connections REDIS_SSL_CERT_REQSNo requiredSSL verification: none, optional, required REDIS_SSL_CA_CERTSNo - Path to CA certificate file (PEM) REDIS_SSL_CERTFILENo - Path to client certificate for mTLS REDIS_SSL_KEYFILENo - Path to client private key for mTLS REDIS_SSL_CHECK_HOSTNAMENo trueVerify server certificate hostname
AI Services Service URLs Variable Required Default Description YOLO26_URLNo http://localhost:8095YOLO26 detection service URL NEMOTRON_URLNo http://localhost:8091Nemotron LLM service URL FLORENCE_URLNo http://localhost:8092Florence-2 vision-language service URL CLIP_URLNo http://localhost:8093CLIP embedding service URL ENRICHMENT_URLNo http://localhost:8094Enrichment service URL (remote helpers)
Warning: Use HTTPS in production to prevent MITM attacks.
Service Authentication Variable Required Default Description YOLO26_API_KEYNo - API key for YOLO26 service NEMOTRON_API_KEYNo - API key for Nemotron service
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.
Variable Required Default Description VISION_EXTRACTION_ENABLEDNo trueEnable Florence-2 based vision extraction REID_ENABLEDNo trueEnable CLIP-based re-identification SCENE_CHANGE_ENABLEDNo trueEnable scene change detection
Florence Feature Toggles Variable Required Default Description FLORENCE_OCR_ENABLEDNo trueEnable OCR text extraction FLORENCE_DENSE_CAPTION_ENABLEDNo trueEnable dense region captioning FLORENCE_DETAILED_CAPTIONNo trueEnable detailed image captions
Re-ID / Scene Change Tuning Variable Required Default Range Description REID_SIMILARITY_THRESHOLDNo 0.850.5-1.0 Cosine similarity threshold for matching REID_TTL_HOURSNo 241-168 Redis TTL for embeddings REID_MAX_CONCURRENTNo 41-16 Max concurrent re-ID operations REID_TIMEOUT_SECONDSNo 5.01-30s Per-operation timeout for re-ID SCENE_CHANGE_THRESHOLDNo 0.900.5-1.0 SSIM threshold (below = change detected)
Image Quality Assessment Variable Required Default Range Description IMAGE_QUALITY_MIN_THRESHOLDNo 0.30.0-1.0 Minimum acceptable image quality
Enrichment Circuit Breakers Variable Required Default Range Description ENRICHMENT_CIRCUIT_FAILURE_THRESHOLDNo 51-50 Failures before circuit opens ENRICHMENT_CIRCUIT_RECOVERY_TIMEOUTNo 60.010-600 Seconds to wait before retry ENRICHMENT_CIRCUIT_HALF_OPEN_MAX_CALLSNo 31-10 Test calls in half-open state ENRICHMENT_CIRCUIT_SUCCESS_THRESHOLDNo 21-10 Successes required to close circuit
CLIP Circuit Breakers Variable Required Default Range Description CLIP_CIRCUIT_FAILURE_THRESHOLDNo 51-50 Failures before circuit opens CLIP_CIRCUIT_RECOVERY_TIMEOUTNo 60.010-600 Seconds to wait before retry CLIP_CIRCUIT_HALF_OPEN_MAX_CALLSNo 31-10 Test calls in half-open state CLIP_CIRCUIT_SUCCESS_THRESHOLDNo 21-10 Successes required to close circuit
Florence Circuit Breakers Variable Required Default Range Description FLORENCE_CIRCUIT_FAILURE_THRESHOLDNo 51-50 Failures before circuit opens FLORENCE_CIRCUIT_RECOVERY_TIMEOUTNo 60.010-600 Seconds to wait before retry FLORENCE_CIRCUIT_HALF_OPEN_MAX_CALLSNo 31-10 Test calls in half-open state FLORENCE_CIRCUIT_SUCCESS_THRESHOLDNo 21-10 Successes required to close circuit
Variable Required Default Range Description AI_CONNECT_TIMEOUTNo 10.01-60s Connection timeout AI_HEALTH_TIMEOUTNo 5.01-30s Health check timeout YOLO26_READ_TIMEOUTNo 30.05-120s Detection response timeout NEMOTRON_READ_TIMEOUTNo 120.030-600s LLM response timeout FLORENCE_READ_TIMEOUTNo 30.05-120s Florence-2 response timeout CLIP_READ_TIMEOUTNo 15.05-60s CLIP embedding generation timeout ENRICHMENT_READ_TIMEOUTNo 60.010-180s Enrichment service response timeout
AI Service Retries Variable Required Default Range Description DETECTOR_MAX_RETRIESNo 31-10 Retry attempts for YOLO26 detector NEMOTRON_MAX_RETRIESNo 31-10 Retry attempts for Nemotron LLM ENRICHMENT_MAX_RETRIESNo 31-10 Retry attempts for enrichment service
AI Concurrency Variable Required Default Range Description AI_MAX_CONCURRENT_INFERENCESNo 41-32 Max concurrent AI inference operations
Nemotron Context Window Variable Required Default Range Description NEMOTRON_CONTEXT_WINDOWNo 39001000-128000 Context window size in tokens NEMOTRON_MAX_OUTPUT_TOKENSNo 1536100-8192 Maximum tokens reserved for output
AI Warmup Settings Variable Required Default Range Description AI_WARMUP_ENABLEDNo true- Enable model warmup on startup AI_COLD_START_THRESHOLD_SECONDSNo 300.060-3600s Seconds before model is considered cold NEMOTRON_WARMUP_PROMPTNo - - Test prompt for Nemotron warmup
Camera Integration Variable Required Default Description FOSCAM_BASE_PATHNo /export/foscamBase directory for camera uploads
Camera images are expected at: {FOSCAM_BASE_PATH}/{camera_name}/
File Watcher Variable Required Default Range Description FILE_WATCHER_POLLINGNo false- Use polling instead of native events FILE_WATCHER_POLLING_INTERVALNo 1.00.1-30s Polling interval in seconds
Note: Enable polling for Docker Desktop on macOS/Windows where inotify doesn't work across volume mounts.
Detection Settings Variable Required Default Range Description DETECTION_CONFIDENCE_THRESHOLDNo 0.50.0-1.0 Minimum confidence for detections
Fast Path Settings High-confidence detections can bypass batching for immediate alerts.
Variable Required Default Range Description FAST_PATH_CONFIDENCE_THRESHOLDNo 0.900.0-1.0 Confidence threshold for fast path FAST_PATH_OBJECT_TYPESNo ["person"]- Object types eligible for fast path (JSON array)
Batch Processing Variable Required Default Range Description BATCH_WINDOW_SECONDSNo 90- Max time window for grouping detections BATCH_IDLE_TIMEOUT_SECONDSNo 30- Close batch after inactivity
Retention Variable Required Default Description RETENTION_DAYSNo 30Days to keep events and detections LOG_RETENTION_DAYSNo 7Days to keep log entries
GPU Monitoring Variable Required Default Range Description GPU_POLL_INTERVAL_SECONDSNo 5.01-60s GPU stats polling interval GPU_STATS_HISTORY_MINUTESNo 601-1440 Minutes of GPU history to retain
Recommended values:
1-2s: Real-time debugging 5s: Balanced (default) 15-30s: Lower overhead under pressure 60s: Minimal monitoring Deduplication Variable Required Default Range Description DEDUPE_TTL_SECONDSNo 30060-3600s TTL for file deduplication in Redis
Severity Thresholds Risk score ranges for severity levels. See Risk Levels Reference .
Variable Required Default Range Description SEVERITY_LOW_MAXNo 290-100 Max score for LOW severity SEVERITY_MEDIUM_MAXNo 590-100 Max score for MEDIUM severity SEVERITY_HIGH_MAXNo 840-100 Max score for HIGH severity
Constraint: 0 <= low_max < medium_max < high_max <= 100
Logging Variable Required Default Description LOG_LEVELNo WARNINGDEBUG, INFO, WARNING, ERROR, CRITICAL LOG_FILE_PATHNo data/logs/security.logPath for rotating log file LOG_FILE_MAX_BYTESNo 10485760Max size per log file (10MB) LOG_FILE_BACKUP_COUNTNo 7Number of backup files to keep LOG_DB_ENABLEDNo trueWrite logs to database LOG_DB_MIN_LEVELNo DEBUGMin level for database logging
API Server Variable Required Default Description DEBUGNo falseEnable debug mode (development only) API_HOSTNo 0.0.0.0Server bind address API_PORTNo 8000Server port
Authentication Variable Required Default Description API_KEY_ENABLEDNo falseEnable API key authentication API_KEYSNo []Valid API keys (JSON array)
Example:
API_KEY_ENABLED = true
API_KEYS =[ "key1-here" , "key2-here" ]
Rate Limiting Variable Required Default Range Description RATE_LIMIT_ENABLEDNo true- Enable rate limiting RATE_LIMIT_REQUESTS_PER_MINUTENo 601-10000 Standard tier limit RATE_LIMIT_BURSTNo 101-100 Burst allowance RATE_LIMIT_MEDIA_REQUESTS_PER_MINUTENo 1201-10000 Media tier limit RATE_LIMIT_WEBSOCKET_CONNECTIONS_PER_MINUTENo 101-100 WebSocket limit RATE_LIMIT_SEARCH_REQUESTS_PER_MINUTENo 301-1000 Search tier limit TRUSTED_PROXY_IPSNo ["127.0.0.1", "::1"]Trusted proxy IPs (CIDR supported)
WebSocket Variable Required Default Range Description WEBSOCKET_IDLE_TIMEOUT_SECONDSNo 30030-3600s Close idle connections after WEBSOCKET_PING_INTERVAL_SECONDSNo 305-120s Server heartbeat interval WEBSOCKET_MAX_MESSAGE_SIZENo 655361KB-1MB Max message size (bytes)
TLS/HTTPS Configuration Modern Configuration (Recommended) Variable Required Default Description TLS_MODENo disableddisabled, self_signed, or provided TLS_CERT_PATHIf provided - Path to certificate file (PEM) TLS_KEY_PATHIf provided - Path to private key file (PEM) TLS_CA_PATHNo - CA certificate for client verification TLS_VERIFY_CLIENTNo falseRequire client certificates (mTLS) TLS_MIN_VERSIONNo TLSv1.2Minimum TLS version
Legacy Configuration (Deprecated) Variable Required Default Description TLS_ENABLEDNo falseUse TLS_MODE instead TLS_CERT_FILENo - Use TLS_CERT_PATH instead TLS_KEY_FILENo - Use TLS_KEY_PATH instead TLS_AUTO_GENERATENo falseUse TLS_MODE=self_signed instead TLS_CERT_DIRNo data/certsDirectory for auto-generated certs
CORS Variable Required Default Description CORS_ORIGINSNo ["http://localhost:3000", "http://localhost:5173"]Allowed origins (JSON array)
Notifications Email (SMTP) Variable Required Default Description SMTP_HOSTNo - SMTP server hostname SMTP_PORTNo 587SMTP port (587 for TLS, 465 for SSL) SMTP_USERNo - SMTP username SMTP_PASSWORDNo - SMTP password SMTP_FROM_ADDRESSNo - Sender email address SMTP_USE_TLSNo trueUse TLS for SMTP DEFAULT_EMAIL_RECIPIENTSNo []Default recipients (JSON array)
Webhooks Variable Required Default Description DEFAULT_WEBHOOK_URLNo - Default webhook URL for alerts WEBHOOK_TIMEOUT_SECONDSNo 30Webhook request timeout
General Variable Required Default Description NOTIFICATION_ENABLEDNo trueEnable notification delivery
Queue Settings Variable Required Default Range Description QUEUE_MAX_SIZENo 10000100-100000 Maximum Redis queue size QUEUE_OVERFLOW_POLICYNo dlq- dlq, reject, or drop_oldest QUEUE_BACKPRESSURE_THRESHOLDNo 0.80.5-1.0 Start warnings at this fill ratio
Queue Overflow Policy Options When the queue reaches QUEUE_MAX_SIZE, the system applies the configured overflow policy:
Policy Behavior Use Case dlqDefault. Move overflow items to dead-letter queue for later retry/inspectionProduction - preserves all data for recovery rejectReject new items with an error; existing items preserved Strict mode - alerts immediately on capacity drop_oldestDiscard oldest items to make room for new ones High-throughput - prioritizes recent detections
Consequences by policy:
dlq (default):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:Queue overflow: item rejected. Useful for alerting on capacity issues but causes immediate data loss.
drop_oldest:
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) Variable Required Default Range Description MAX_REQUEUE_ITERATIONSNo 100001-100000 Max iterations for requeue-all DLQ_CIRCUIT_BREAKER_FAILURE_THRESHOLDNo 51-50 Failures before opening circuit DLQ_CIRCUIT_BREAKER_RECOVERY_TIMEOUTNo 60.010-600s Wait before retry DLQ_CIRCUIT_BREAKER_HALF_OPEN_MAX_CALLSNo 31-10 Test calls in half-open state DLQ_CIRCUIT_BREAKER_SUCCESS_THRESHOLDNo 21-10 Successes to close circuit
Video Processing Variable Required Default Range Description VIDEO_FRAME_INTERVAL_SECONDSNo 2.00.1-60s Interval between extracted frames VIDEO_THUMBNAILS_DIRNo data/thumbnails- Directory for video thumbnails VIDEO_MAX_FRAMESNo 301-300 Max frames to extract per video
Clip Generation Variable Required Default Range Description CLIPS_DIRECTORYNo data/clips- Directory for event clips CLIP_PRE_ROLL_SECONDSNo 50-60s Seconds before event to include CLIP_POST_ROLL_SECONDSNo 50-60s Seconds after event to include CLIP_GENERATION_ENABLEDNo true- Enable automatic clip generation
Service Health Variable Required Default Description AI_RESTART_ENABLEDNo trueAuto-restart AI services on failure
Note: Set to false in containerized deployments where restart scripts aren't available.
Admin Endpoints Variable Required Default Description ADMIN_ENABLEDNo falseEnable admin endpoints (requires DEBUG=true) ADMIN_API_KEYNo - API key for admin endpoints
Security: Admin endpoints require BOTH DEBUG=true AND ADMIN_ENABLED=true.
Cache TTL Settings Variable Required Default Range Description CACHE_TTL_EVENTSNo 6030-3600s TTL for event list cache CACHE_TTL_CAMERASNo 30060-3600s TTL for camera list cache CACHE_TTL_DETECTIONSNo 12030-3600s TTL for detection cache CACHE_TTL_SYSTEM_STATSNo 3010-300s TTL for system statistics cache CACHE_TTL_AI_HEALTHNo 6030-600s TTL for AI health status cache
Internal Service Timeouts Variable Required Default Range Description INTERNAL_TIMEOUT_DATABASENo 30.05-120s Database query timeout INTERNAL_TIMEOUT_REDISNo 10.01-60s Redis operation timeout INTERNAL_TIMEOUT_HEALTHCHECKNo 5.01-30s Health check operation timeout
Worker Supervisor Variable Required Default Range Description WORKER_SUPERVISOR_ENABLEDNo true- Enable background worker supervisor WORKER_SUPERVISOR_MAX_RESTARTSNo 51-20 Max restarts before giving up WORKER_SUPERVISOR_RESTART_DELAYNo 5.01-60s Seconds to wait between restarts
Orchestrator Settings Variable Required Default Range Description ORCHESTRATOR_POLL_INTERVALNo 1.00.1-5s Polling interval for work items ORCHESTRATOR_MAX_CONCURRENT_TASKSNo 41-32 Max concurrent orchestrator tasks ORCHESTRATOR_SHUTDOWN_TIMEOUTNo 30.05-120s Grace period for shutdown
Job Management Variable Required Default Range Description JOB_TIMEOUT_SECONDSNo 30060-3600s Default timeout for background jobs JOB_MAX_RETRIESNo 31-10 Max retry attempts for failed jobs JOB_RETRY_DELAY_SECONDSNo 6010-600s Delay between job retries
Variable Required Default Range Description DEFAULT_PAGE_SIZENo 5010-500 Default items per page MAX_PAGE_SIZENo 10050-1000 Maximum allowed page size
Transcode Cache Variable Required Default Range Description TRANSCODE_CACHE_DIRNo data/cache- Directory for transcoded media cache TRANSCODE_CACHE_MAX_SIZENo 1073741824- Max cache size in bytes (1GB) TRANSCODE_CACHE_TTLNo 360060-86400 TTL for cache entries in seconds
Thumbnail Settings Variable Required Default Range Description THUMBNAIL_WIDTHNo 320100-800 Thumbnail width in pixels THUMBNAIL_HEIGHTNo 240100-600 Thumbnail height in pixels THUMBNAIL_QUALITYNo 8550-100 JPEG quality for thumbnails
Hardware Acceleration Variable Required Default Description HARDWARE_ACCEL_ENABLEDNo trueEnable hardware video acceleration HARDWARE_ACCEL_DEVICENo autoDevice: auto, vaapi, cuda, or videotoolbox
Variable Required Default Description PROFILING_ENABLEDNo falseEnable performance profiling PROFILING_SAMPLE_RATENo 0.1Fraction of requests to profile SLOW_REQUEST_THRESHOLD_MSNo 1000Log requests slower than this (ms)
Slow Query Logging Variable Required Default Range Description SLOW_QUERY_THRESHOLD_MSNo 10010-10000ms Log queries slower than this SLOW_QUERY_LOG_ENABLEDNo true- Enable slow query logging
Request Logging Variable Required Default Description REQUEST_LOGGING_ENABLEDNo trueLog incoming HTTP requests REQUEST_LOGGING_BODYNo falseInclude request body in logs REQUEST_LOGGING_HEADERSNo falseInclude request headers in logs
Request Recording Variable Required Default Description REQUEST_RECORDING_ENABLEDNo falseRecord requests for replay/debugging REQUEST_RECORDING_DIRNo - Directory to store recorded requests
HSTS Configuration Variable Required Default Description HSTS_ENABLEDNo falseEnable HTTP Strict Transport Security HSTS_MAX_AGENo 31536000HSTS max-age in seconds (1 year) HSTS_INCLUDE_SUBDOMAINSNo trueInclude subdomains in HSTS policy HSTS_PRELOADNo falseAllow HSTS preload list inclusion
Idempotency Variable Required Default Range Description IDEMPOTENCY_ENABLEDNo true- Enable idempotency key support IDEMPOTENCY_TTL_SECONDSNo 864003600-604800 TTL for idempotency keys (1 day)
Background Evaluation Variable Required Default Range Description BACKGROUND_EVAL_ENABLEDNo true- Enable background model evaluation BACKGROUND_EVAL_INTERVALNo 3600300-86400 Evaluation interval in seconds
Orphan File Cleanup Configuration for periodic cleanup of orphaned files (files on disk without corresponding database records).
Variable Required Default Range Description ORPHAN_CLEANUP_ENABLEDNo true- Enable periodic cleanup of orphaned files ORPHAN_CLEANUP_SCAN_INTERVAL_HOURSNo 241-168 Hours between cleanup scans (default: daily) ORPHAN_CLEANUP_AGE_THRESHOLD_HOURSNo 241-720 Minimum age (hours) before an orphaned file can be deleted
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.
Variable Required Default Description MODEL_ZOO_PATHNo /models/model-zooBase directory path for Model Zoo model files
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) These are embedded at frontend build time:
Variable Required Default Description VITE_API_BASE_URLNo http://localhost:8000Backend API URL VITE_WS_BASE_URLNo ws://localhost:8000WebSocket URL FRONTEND_PORTNo 5173Host port for frontend container
Next Steps See Also Back to Operator Hub | Developer Hub
