homesec 1.2.3

Pluggable async home security camera pipeline with detection, VLM analysis, and alerts.

HomeSec

HomeSec is a self-hosted, extensible video pipeline for home security cameras. You can connect cameras directly via RTSP, receive clips over FTP, or implement your own ClipSource. From there, the pipeline filters events with AI and sends smart notifications. Your footage stays private and off third-party clouds.

Design Principles

• Local-Only Data Processing: Video footage remains on the local network by default. Cloud usage (Storage, VLM/OpenAI) is strictly opt-in.
• Modular Architecture: All major components (sources, filters, analyzers, notifiers) are decoupled plugins defined by strict interfaces. If you want to use a different AI model or storage backend, you can swap it out with a few lines of Python.
• Resilience: The primary resilience feature is backing up clips to storage. The pipeline handles intermittent stream failures and network instability without crashing or stalling.

Pipeline at a glance

graph TD
    %% Layout Wrapper for horizontal alignment
    subgraph Wrapper [" "]
        direction LR
        style Wrapper fill:none,stroke:none
        
        S[Clip Source]
        
        subgraph Pipeline [Media Processing Pipeline]
            direction TB
            C(Clip File) --> U([Upload to Storage])
            C --> F([Detect objects: YOLO])
            F -->|Detected objects| AI{Trigger classes filter}
            AI -->|Yes| V([VLM Analysis])
            AI -->|No| D([Discard])
            V -->|Risk level, detected objects| P{Alert Policy filter}
            P -->|No| D
            P -->|YES| N[Notifiers]
        end
        
        S -->|New Clip File| Pipeline
        
        PG[(Postgres)]
        Pipeline -.->|State & Events| PG
    end

• Parallel Processing: Upload and filter run in parallel.
• Resilience: Upload failures do not block alerts; filter failures stop expensive VLM calls.
• State: Metadata is stored in Postgres (clip_states + clip_events) for full observability.

Table of Contents

• Highlights
• Pipeline at a glance
• Quickstart
  • 30-Second Start (Docker)
  • Manual Setup
• Configuration
  • Commands
• Plugins
  • Built-in plugins
  • Plugin interfaces
  • Writing a custom plugin
• Observability
• Development
• Contributing
• License

Highlights

• Multiple pluggable video clip sources: RTSP motion detection, FTP uploads, or a watched folder
• Parallel upload + filter (YOLO) with frame sampling and early exit
• OpenAI-compatible VLM analysis with structured output
• Policy-driven alerts with per-camera overrides
• Fan-out notifiers (MQTT for Home Assistant, SendGrid email)
• Postgres-backed state + events with graceful degradation
• Health endpoint plus optional Postgres telemetry logging

Quickstart

Docker

Use the included docker-compose.yml (HomeSec + Postgres, pulls leva/homesec:latest).

Configure your own config.yaml and .env files as described in Manual Setup.

Manual Setup

For standard production usage without Docker Compose:

1. Prerequisites:

   • Python 3.10+
   • ffmpeg
   • PostgreSQL (running and accessible)

2. Install

   pip install homesec
   

3. Configure

   # Download example config & env
   curl -O https://raw.githubusercontent.com/lan17/homesec/main/config/example.yaml
   mv example.yaml config.yaml
   
   curl -O https://raw.githubusercontent.com/lan17/homesec/main/.env.example
   mv .env.example .env
   
   # Setup environment (DB_DSN is required)
   # Edit .env to set your secrets!
   export DB_DSN="postgresql://user:pass@localhost/homesec"
   

4. Run

   homesec run --config config.yaml
   

Developer Setup

If you are contributing or running from source:

1. Install dependencies

   uv sync
   

2. Start Infrastructure

   make db  # Starts just Postgres in Docker
   

3. Run

   uv run python -m homesec.cli run --config config/config.yaml
   

Configuration

Configuration is YAML-based and strictly validated. Secrets (API keys, passwords) should always be loaded from environment variables (_env suffix).

Configuration Examples

1. The "Power User" (Robust RTSP)

Best for real-world setups with flaky cameras.

cameras:
  - name: driveway
    source:
      backend: rtsp
      config:
        rtsp_url_env: DRIVEWAY_RTSP_URL
        output_dir: "./recordings"
        stream:
          # Critical for camera compatibility:
          ffmpeg_flags: ["-rtsp_transport", "tcp", "-vsync", "0"]
        reconnect:
          backoff_s: 5

filter:
  backend: yolo
  config:
    classes: ["person", "car"]
    min_confidence: 0.6

In your .env:

DRIVEWAY_RTSP_URL="rtsp://user:pass@192.168.1.100:554/stream"

2. The "Cloud Storage" (Dropbox)

Uploads to Cloud but keeps analysis local.

storage:
  backend: dropbox
  config:
    token_env: DROPBOX_TOKEN
    root: "/SecurityCam"

notifiers:
    - backend: sendgrid_email
      config:
        api_key_env: SENDGRID_API_KEY
        to_emails: ["[e-mail]"]

In your .env:

DROPBOX_TOKEN="sl.Al..."
SENDGRID_API_KEY="SG.xyz..."

See config/example.yaml for a complete reference of all options.

Tips

• Secrets: Never put secrets in YAML. Use env vars (*_env) and set them in your shell or .env.
• Notifiers: At least one notifier (mqtt/email) must be enabled unless alert_policy.enabled is false.
• YOLO Classes: Built-in classes include person, car, truck, motorcycle, bicycle, dog, cat, bird, backpack, handbag, suitcase.

After installation, the homesec command is available:

homesec --help

Commands

Run the pipeline:

homesec run --config config.yaml

Validate config:

homesec validate --config config.yaml

Cleanup old clips (reanalyze and optionally delete empty clips):

homesec cleanup --config config.yaml --older_than_days 7 --dry_run=False

Use homesec <command> --help for detailed options on each command.

Plugins

Extensible by design

We designed HomeSec to be modular. Each major capability is an interface (ClipSource, StorageBackend, ObjectFilter, VLMAnalyzer, AlertPolicy, Notifier) defined in src/homesec/interfaces.py. This means you can swap out components (like replacing YOLO with a different detector) without changing the core pipeline.

HomeSec uses a plugin architecture where every component is discovered at runtime via entry points.

Built-in plugins

Type	Plugins
Sources	rtsp, ftp, local_folder
Filters	yolo
Storage	dropbox, local
VLM analyzers	openai
Notifiers	mqtt, sendgrid_email
Alert policies	default, noop

Plugin interfaces

All interfaces are defined in src/homesec/interfaces.py.

Type	Interface	Decorator
Sources	ClipSource	@source_plugin
Filters	ObjectFilter	@filter_plugin
Storage	StorageBackend	@storage_plugin
VLM analyzers	VLMAnalyzer	@vlm_plugin
Notifiers	Notifier	@notifier_plugin
Alert policies	AlertPolicy	@alert_policy_plugin

Writing a custom plugin

Extending HomeSec is designed to be easy. You can write custom sources, filters, storage backends, and more.

👉 See PLUGIN_DEVELOPMENT.md for a complete guide.

Observability

• Health endpoint: GET /health (configurable via health.host/health.port in config)
• Telemetry logs to Postgres when DB_DSN is set

Development

Setup

1. Clone the repository
2. Install uv for dependency management
3. uv sync to install dependencies
4. make db to start Postgres locally

Commands

• Run tests: make test
• Run type checking (strict): make typecheck
• Run both: make check
• Run the pipeline: make run

Notes

• Tests must include Given/When/Then comments
• Architecture notes: DESIGN.md

Contributing

Contributions are welcome! Here's how to get started:

1. Fork and clone the repository
2. Create a branch for your feature or fix: git checkout -b my-feature
3. Install dependencies: uv sync
4. Make your changes and ensure tests pass: make check
5. Submit a pull request with a clear description of your changes

Guidelines

• All code must pass CI checks: make check
• Tests should include Given/When/Then comments explaining the test scenario
• New plugins should follow the existing patterns in src/homesec/plugins/
• Keep PRs focused on a single change for easier review

Reporting Issues

Found a bug or have a feature request? Please open an issue with:

• A clear description of the problem or suggestion
• Steps to reproduce (for bugs)
• Your environment (OS, Python version, HomeSec version)

License

Apache 2.0. See LICENSE.