Reference Hub¶

Authoritative reference documentation for the Home Security Intelligence system. Lookup-style information for APIs, configuration, and troubleshooting.

Target Audiences: Developers, Operators, Support, All Users

Section	What You'll Find
Environment Variables	All configuration options with defaults
Service Ports	Port assignments for all services
Glossary	Definitions of key terms
Troubleshooting	Symptom-based problem solving
API Reference	REST and WebSocket API documentation
Risk Levels	Risk score ranges and severity definitions

Service Ports¶

Service	Port	Protocol	Description
Frontend HTTP	8080	HTTP	nginx in the `frontend` container, host port `FRONTEND_HTTP_PORT`
Frontend HTTPS	8444	HTTPS	nginx in the `frontend` container, host port `FRONTEND_HTTPS_PORT`
Backend API	8000	HTTP/WS	FastAPI REST + WebSocket (`API_PORT`)
AI Gateway	8090	HTTP	Triton gateway serving YOLO26, Florence-2, CLIP and enrichment models
Nemotron	8091	HTTP	LLM risk analysis (llama.cpp, compose service `ai-llm`)
PostgreSQL	5432	TCP	Database (`POSTGRES_PORT`)
Redis	6379	TCP	Cache, queues, pub/sub (`REDIS_PORT`)
Grafana	3002	HTTP	Dashboards at the `/grafana/` sub-path (`GRAFANA_PORT`)
Prometheus	9090	HTTP	Metrics (`PROMETHEUS_PORT`)
Tempo	3200	HTTP	Distributed tracing query API (`TEMPO_PORT`; OTLP gRPC on 4317)

Frontend Port Details:

Production containers: nginx serves the built React app on container ports 8080 (HTTP) and 8443 (HTTPS), mapped to host ports FRONTEND_HTTP_PORT (default 8080) and FRONTEND_HTTPS_PORT (default 8444) in docker-compose.prod.yml

Local development: npm run dev in frontend/ runs the Vite dev server on https://localhost:8444 (set in frontend/vite.config.ts); FRONTEND_PORT=5173 is left over from the Vite dev default and is not referenced by docker-compose.prod.yml

SSL: Enabled by default in production with auto-generated self-signed certificates. See SSL/HTTPS Configuration

Compose maps AI, database and monitoring ports to 127.0.0.1 only — they are reachable from the host, not from your LAN.

Environment Variables¶

Complete reference: Environment Variable Reference

Quick Reference - Essential Variables¶

Variable	Required	Default	Description
`DATABASE_URL`	Yes	-	PostgreSQL connection URL
`REDIS_URL`	No	`redis://localhost:6379/0`	Redis connection URL
`YOLO26_URL`	No	see note below	YOLO26 service URL
`NEMOTRON_URL`	No	`http://localhost:8091`	Nemotron LLM service URL

YOLO26_URL has two sources of truth: the backend default (backend/core/config.py) is http://ai-gateway:8090/yolo26 for containerized deployments, while .env.example ships http://localhost:8090/yolo26 for host-run development. Set it explicitly to match where your gateway runs.

Database Configuration¶

# Format
DATABASE_URL=postgresql+asyncpg://user:password@host:port/database  # pragma: allowlist secret

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

# Docker container (use service name)
DATABASE_URL=postgresql+asyncpg://security:password@postgres:5432/security  # pragma: allowlist secret

Important: There is no default DATABASE_URL. Run python setup.py to generate a .env file with secure credentials.

Redis Configuration¶

# Format
REDIS_URL=redis://[password@]host:port[/database]

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

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

AI Service URLs¶

.env.example routes every model except Nemotron through the AI gateway (Triton) using per-service path prefixes; set AI_GATEWAY_URL/USE_AI_GATEWAY accordingly. The "standalone" column is the backend fallback default and the port a host-run server in ai/<service>/model.py binds to.

Variable	Default (`.env.example`, via gateway)	Fallback / standalone	Description
`YOLO26_URL`	`http://localhost:8090/yolo26`	`ai-gateway:8090`	YOLO26 object detection
`NEMOTRON_URL`	`http://localhost:8091`	`ai-llm:8091`	Nemotron LLM (only AI service not in gateway)
`FLORENCE_URL`	`http://localhost:8090/florence`	`:8092`	Florence-2 vision-language (optional)
`CLIP_URL`	`http://localhost:8090/clip`	`:8093`	CLIP embeddings (optional)
`ENRICHMENT_URL`	`http://localhost:8090/enrichment`	`:8094`	Heavy enrichment models (optional)
`ENRICHMENT_LIGHT_URL`	`http://localhost:8090/enrich-lt`	`:8096`	Light enrichment models (optional)

Warning: Use HTTPS in production to prevent MITM attacks.

AI Service Timeouts¶

Variable	Default	Range	Description
`AI_CONNECT_TIMEOUT`	`10.0`	1-60s	Connection timeout
`AI_HEALTH_TIMEOUT`	`5.0`	1-30s	Health check timeout
`YOLO26_READ_TIMEOUT`	`30.0`	5-120s	Detection response timeout
`NEMOTRON_READ_TIMEOUT`	`120.0`	30-600s	LLM response timeout

Batch Processing¶

Variable	Default	Description
`BATCH_WINDOW_SECONDS`	`90`	Max time window for grouping detections
`BATCH_IDLE_TIMEOUT_SECONDS`	`30`	Close batch after inactivity

Retention¶

Variable	Default	Description
`RETENTION_DAYS`	`30`	Days to keep events and detections
`LOG_RETENTION_DAYS`	`7`	Days to keep log entries

Camera Integration¶

Variable	Default	Description
`FOSCAM_BASE_PATH`	`/export/foscam`	Base directory for camera uploads

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

Frontend¶

Variable	Default	Description
`VITE_API_BASE_URL`	`http://localhost:8000`	Backend API URL
`VITE_WS_BASE_URL`	`ws://localhost:8000`	WebSocket URL
`FRONTEND_HTTP_PORT`	`8080`	Host port for frontend container HTTP
`FRONTEND_HTTPS_PORT`	`8444`	Host port for frontend container HTTPS

For complete environment variable documentation, see Environment Variable Reference.

AI Service Deployment Modes¶

Development Mode (Host-run AI)¶

AI services run directly on the host while the backend runs in a container:

# macOS with Docker Desktop (default)
YOLO26_URL=http://host.docker.internal:8090/yolo26
NEMOTRON_URL=http://host.docker.internal:8091

# macOS with Podman
export AI_HOST=host.containers.internal
podman-compose up -d

# Linux
# Use host IP or add --add-host=host.docker.internal:host-gateway

Production Mode (Fully Containerized)¶

All services including AI run in containers — one Triton gateway (ai-gateway) plus the standalone LLM (ai-llm):

# Set by docker-compose.prod.yml for the backend
YOLO26_URL=http://ai-gateway:8090/yolo26
NEMOTRON_URL=http://ai-llm:8091
FLORENCE_URL=http://ai-gateway:8090/florence
CLIP_URL=http://ai-gateway:8090/clip
ENRICHMENT_URL=http://ai-gateway:8090/enrichment
ENRICHMENT_LIGHT_URL=http://ai-gateway:8090/enrich-lt

Quick Reference: AI_HOST by Platform¶

Platform	Runtime	Development (host AI)	Production (container AI)
macOS	Docker	`host.docker.internal` (default)	N/A (use Linux for GPU)
macOS	Podman	`host.containers.internal`	N/A (use Linux for GPU)
Linux	Docker	Host IP or `host-gateway`	`ai-gateway`, `ai-llm`
Linux	Podman	Host IP or `host-gateway`	`ai-gateway`, `ai-llm`
Windows	Docker	`host.docker.internal`	N/A (use Linux for GPU)

Glossary¶

Key terms used throughout the documentation. Full glossary: Glossary

Core Concepts¶

Term	Definition
Detection	A single object instance identified by YOLO26 in an image. Contains object type, confidence score, bounding box, and timestamp.
Event	A security incident containing one or more detections, analyzed by Nemotron for risk assessment.
Batch	A collection of detections from a single camera grouped within a time window for analysis.
Risk Score	A numeric value from 0-100 assigned by Nemotron indicating the threat level of an event.
Risk Level	Categorical classification: Low (0-29), Medium (30-59), High (60-84), Critical (85-100).

AI Components¶

Term	Definition
YOLO26	Real-time object detection model using transformer architecture for accurate detection.
Nemotron	NVIDIA's LLM family. Production uses Nemotron-3-Nano-30B-A3B; development uses Mini 4B.
Florence-2	Vision-language model for extracting visual attributes (optional enrichment).
CLIP	Model for generating image embeddings enabling re-identification across camera frames.
Inference	The process of running an AI model on input data to produce predictions.

System Components¶

Term	Definition
Pipeline	End-to-end processing flow: File Watcher -> Detection -> Batch Aggregator -> Analysis -> Event
File Watcher	Service that monitors camera directories for new image uploads.
Batch Aggregator	Service that groups detections into batches based on camera and time proximity.
Circuit Breaker	Fault tolerance pattern that temporarily disables calls to a failing service.
Dead Letter Queue	Queue where failed messages are stored for investigation and reprocessing.

Troubleshooting¶

Quick symptom reference. Full guide: Troubleshooting Hub

Quick Self-Check¶

# 1. System health
curl -s http://localhost:8000/api/system/health | jq .

# 2. Service status
docker compose -f docker-compose.prod.yml ps

# 3. GPU status
nvidia-smi

# 4. Recent logs
docker compose -f docker-compose.prod.yml logs --tail=50 backend

Common Issues Quick Reference¶

Symptom	Likely Cause	Quick Fix
Dashboard shows no events	File watcher or AI down	Restart backend
Risk gauge stuck at 0	Nemotron unavailable	Start the `ai-llm` container
Camera shows offline	FTP or folder path issue	Check FTP and folder config
AI not responding	Services not started	`docker compose -f docker-compose.prod.yml up -d ai-gateway ai-llm`
WebSocket disconnected	Backend down	Restart backend
"Connection refused" errors	Service not running	Start the service
CORS errors in browser	URL mismatch	Update `CORS_ORIGINS`

Detailed Troubleshooting Guides¶

Troubleshooting Index - Start here for any issue
AI Issues - YOLO26, Nemotron, pipeline problems
Connection Issues - Network, containers, WebSocket
Database Issues - PostgreSQL connection, schema
GPU Issues - CUDA, VRAM, thermal issues
Triton Rootless CUDA - Gateway CUDA init failure under rootless Podman

Configuration Files¶

File	Purpose
`.env`	Local environment overrides (not in git)
`.env.example`	Template with documented defaults
`data/runtime.env`	Runtime overrides (loaded after .env)
`docker-compose.prod.yml`	Production Docker configuration
`docker-compose.ci.yml`	CI pipeline configuration
`docker-compose.test.yml`	Test harness configuration

Loading Order¶

Default values from backend/core/config.py
.env file (if exists)
data/runtime.env file (if exists; path overridable via HSI_RUNTIME_ENV_PATH)
Environment variables override all

Validation¶

Test your configuration:

# Check backend config loads correctly (run from the repo root)
uv run python -c "from backend.core.config import get_settings; s = get_settings(); print(s.model_dump_json(indent=2))"

# Test service connectivity
curl http://localhost:8000/api/system/health     # Backend
curl http://localhost:8090/yolo26/health         # YOLO26 (AI gateway router)
curl http://localhost:8091/health                # Nemotron
redis-cli ping                                   # Redis

Subdirectories¶

API Documentation¶

REST and WebSocket API endpoint reference. Full API documentation is located in the Developer API Guide.

API Overview - API conventions and authentication
Core Resources - Cameras, events, detections, zones, entities, analytics
AI Pipeline - Enrichment, batches, AI audit, dead letter queue
System Operations - Health, config, alerts, logs, notifications
Real-time - WebSocket streams for events and system status
WebSocket Contracts - Detailed WebSocket message formats

config/¶

Configuration reference documentation.

Environment Variables - Complete variable reference
Risk Levels - Risk score ranges and severity

troubleshooting/¶

Symptom-based problem-solving guides.

Troubleshooting Index - Quick symptom lookup
AI Issues - AI service problems
Connection Issues - Network and connectivity
Database Issues - PostgreSQL problems
GPU Issues - GPU and CUDA issues
Triton Rootless CUDA - Gateway CUDA init failure under rootless Podman

Operator Hub - System administration guides
Developer Hub - Development guides
User Hub - End-user documentation
Architecture - Technical architecture decisions

Back to Documentation | Operator Hub | Developer Hub