SecuraCV

Witnessing without watching.

SecuraCV is a calm, local-first witness layer for homes, studios, labs, and small sites. It helps you understand what happened without turning your cameras and sensors into an identity archive.

Clips stay on your hardware. Events become privacy-preserving claims. The durable record is a signed, hash-chained log you can verify offline.

The promise

Principle	What it means in practice
Local by default	No subscription, remote indexing, or telemetry. Your cameras, your logs, your disk.
Minimal by design	The kernel accepts semantic events such as motion in zone A, not face embeddings, plates, demographics, or person re-identification.
Verifiable after the fact	Events are Ed25519-signed and hash-chained, so edits show up during verification.
Comfortable to live with	Home Assistant integration, a verified timeline, gentle Canary devices, and display surfaces designed to be readable instead of alarming.
Honest about limits	Specs, threat model, docs linting, and supply-chain provenance are part of the product, not fine print.

Start with the short essay: Witnessing is not watching. For the precise rules, read the privacy invariants.

---

Choose your path

If you are...	Start here	Outcome
Completely new — you just found this	Why this matters → the FAQ	The idea in plain words, then the questions everyone asks — answered honestly. Nothing to install, nothing to buy.
Running Home Assistant with cameras	Home Assistant setup → Frigate integration	Frigate keeps recording; SecuraCV adds sealed, signed witness events per camera, a chain-status header, a daily digest, notifications with proof, and a one-tap evidence export.
Running Docker beside an existing Frigate	Docker quickstart	One sidecar container wraps the witness API, bridge, and doctor checks; Home Assistant pairs with one 6-digit code.
Building hardware	Getting started with Canaries → hardware guides	Small independent witnesses for radar, camera-module presence, WiFi sensing, and displays.
Evaluating trust and safety	Why exports work this way → threat model	A clear view of what is enforced, what is audited, and what remains out of scope.
Developing	Operator guide → documentation map	Specs, commands, testing expectations, and day-2 operations in one map.
Just trying to understand a word	The glossary	Every proper noun defined once — SecuraCV vs the Canary vs the kernel, Opera/Chirp/Beacon, break-glass, the device line.
Asking a common question	The FAQ	"Does it do face recognition?", "how do I get footage after a break-in?", "is this production-ready?" — answered plainly.
An AI coding assistant	AGENTS.md	The canonical brief: invariants, naming rules, repo map, CI gates. Every tool's own entrypoint file is generated from it.

Prefer to explore first? The SecuraCV Lab turns the same paths into an interactive guide with browser demos and one-tap commands.

---

Install

Install on Home Assistant

Requires Home Assistant 2026.5.0 or newer, an MQTT broker Home Assistant and Frigate share, and Frigate 0.14 or newer with MQTT enabled. Three ways in, one product at the end — a SecuraCV device with the chain's state, one witness event entity per camera, a daily digest, notifications with proof attached, and a one-tap signed evidence export:

1. Home Assistant OS — the SecuraCV app. Add the SecuraCV app repository (https://github.com/kmay89/securaCV), install SecuraCV from the App Store and open its Web UI: the wizard finds Mosquitto and Frigate (anything missing is a link into your own App Store — the Frigate app's repository is https://github.com/blakeblackshear/frigate-hass-addons), reads Frigate's cameras from its config, and has nothing for you to type. Its done screen's one button, Install the integration and restart Home Assistant, installs the integration the app carries; after the restart, press Configure on the SecuraCV discovered card. Nothing to type.
2. HACS first. SecuraCV is a HACS custom repository (not in the default store yet): add the integration via HACS, then Add Integration → SecuraCV → Automatic, which finds the app or a sidecar by itself.
3. Home Assistant Container + the Docker sidecar. Run the sidecar beside Frigate (docker compose up -d, two lines to edit), then pair it from the discovered SecuraCV sidecar card with the 6-digit code docker exec securacv pair prints beside the kernel's key fingerprint.

Prefer a terminal? On Home Assistant OS, from the Terminal & SSH app:

curl -fsSL https://raw.githubusercontent.com/kmay89/securaCV/main/scripts/install.sh | bash

One idempotent, narrated command installs and wires the whole stack — Mosquitto with a canary broker login, Home Assistant's MQTT connection, Frigate with a curated config, the SecuraCV app, the integration and its config entry, blueprints, and the dashboard — and it is safe to re-run. The broker listens plain on 1883 by default, so the canary password crosses your LAN in the clear until you ask for more: re-run the installer as curl -fsSL https://raw.githubusercontent.com/kmay89/securaCV/main/scripts/install.sh | SECURACV_WITH=broker_tls bash (or the hub plan with --with broker_tls) to add the broker's TLS listener from a certificate you supply, then provision each Canary for it yourself (Step 3 of the setup guide).

Then Settings → Dashboards → Add dashboard → SecuraCV. Walk past a camera: the first event reads Sealed ✓ within a minute, and Verified ✓ once the integration has walked the chain against the key it pinned — the word is earned by Home Assistant's own check, never by the kernel's say-so. The full walkthrough with the exact screens, what stays yours either way (pointing Frigate at your cameras, pointing Canaries at the broker), every entity, and troubleshooting: Home Assistant setup.

Without Home Assistant

The Docker sidecar runs the same witness stack beside an existing Frigate: one compose file (quickstart.compose.yml, or quickstart-with-broker.compose.yml to bundle Mosquitto) plus a narrated docker exec securacv doctor check — and if you add Home Assistant later, it discovers the sidecar over MQTT and pairs with one code. Port 8799 is published from the first start so that pairing can happen; every data route needs a token, and the compose file says exactly what the open port gives. See the Docker quickstart.

From source

On a supported Linux host:

# Ubuntu/Debian prerequisites
sudo apt-get install build-essential libseccomp-dev pkg-config

# Run a local demo, then verify the generated witness log
cargo run --bin demo
cargo run --bin log_verify -- --db demo_witness.db

Real camera ingest, break-glass exports, service operation, and day-2 commands live in the Operator Guide.

---

How it works

Camera / sensor
      ↓
Frigate, RTSP, file, V4L2, ESP32, or sensor adapter
      ↓
Privacy Witness Kernel
      ↓
Event contract + metadata minimization
      ↓
Ed25519-signed hash-chain log + optional sealed vault envelope
      ↓
Home Assistant, CLI verification, or export workflow

SecuraCV separates private media from verifiable claims:

1. Cameras and sensors observe locally.
2. Detection output is reduced to an allowed event vocabulary.
3. Precise timestamps are coarsened, zones stay local, and identity selectors are forbidden.
4. Each accepted event is appended to a signed hash chain.
5. Verification proves whether the chain still matches what was written.
6. Raw media access, when enabled, goes through the break-glass vault flow instead of casual browsing.

The important promise is not that tampering is impossible. It is that tampering becomes visible.

---

What is ready to explore

• The verified witness log in Home Assistant. A dashboard strategy and a Lovelace card show Frigate's events as sealed claims under a chain-status header; Verified ✓ appears only after the integration's own walk of the chain checked every signature against the key it pinned, and a one-tap export hands out a signed evidence pack anyone can verify offline. See the dashboard and the card and the product design.
• Frigate bridge with CI coverage. The Frigate → MQTT → sealed-log path is exercised by fixture replays of the 0.13–0.17 schema with a sentinel in every identity field, a real-binary run against an in-test broker, the sidecar's end-to-end check and a live-broker CI smoke path. See Frigate integration.
• Real ingest paths. File, RTSP, V4L2, ESP32 HTTP, and sensor-adapter paths are documented. Every live frame source for witnessd is an opt-in cargo feature (ingest-v4l2, ingest-esp32, ingest-file-ffmpeg, and the two RTSP decoders); a plain cargo build gives witnessd only the stub:// synthetic source. The event-side binaries (frigate_bridge over MQTT, grove_vision2_ingest over serial) build by default and take live events, not video. The RTSP decoders sit behind the non-default rtsp-ffmpeg and rtsp-gstreamer cargo features, so a plain cargo build refuses an rtsp:// URL (the Docker image and the Home Assistant app build with rtsp-gstreamer); the ffmpeg RTSP path has an end-to-end CI roundtrip. See RTSP setup and the v1 roadmap.
• Detection backends. The default build, including detect.backend = "auto", runs a frame-difference motion detector: events report motion presence, not classified objects. Tract/ONNX object detection is feature-gated (backend-tract), needs a model, and is never picked by auto. See inference backends.
• Canary hardware family. Vision, WAP, Sense, Display, and OTA projects share a growing firmware platform under firmware/.
• Canary Cards. Radar and witness state can render as standardized, privacy-classed cards across Lab, display, and Home Assistant surfaces. See Canary Cards.
• SecuraCV Lab. Browser demos model real firmware behavior, display surfaces, onboarding, power/bench behavior, and the MR60BHA2 radar placement pipeline. Try the Lab.
• USB onboarding design. Experimental USB-OTG builds provide a read-only drive with START-HERE.html, consented one-tap help launch, and recovery/unseal flows. It is off in stock profiles. See USB onboarding.
• Supply-chain transparency. Published firmware artifacts and browser-flasher factory images carry SLSA provenance attestations recorded in Rekor, complementing checksums and device-side OTA verification. The firmware bill of materials is derived from the build inputs and committed (sbom/sbom-firmware.cdx.json), byte-gated and CycloneDX 1.5 schema-validated on every PR; the Rust, Node and firmware SBOMs are attached to every release cut from October 2026 on — firmware, Flasher, Lab and kernel releases each call sbom.yml once published; earlier releases mostly carry none (only app-v0.1.0, flasher-v0.1.4 and app-v0.2.2 did). See supply-chain transparency and sbom/README.md.

---

Canary devices

Canaries are small, local witnesses that corroborate the kernel instead of trusting one central box.

Device	What it does	Where
Canary Vision	Presence from a Grove Vision AI module; no pixels leave the device.	firmware/projects/canary-vision/
Canary WAP	WiFi-sensing presence, mesh experiments, beacon/chirp work, local dashboard.	firmware/projects/canary-wap/
Canary Sense	MR60BHA2 60 GHz mmWave radar witness for presence, coarse occupancy, range bands, and wellbeing builds.	firmware/projects/canary-sense/
Canary Display	Watch and wall display surfaces with calm status, QR onboarding concepts, Lab parity, and living-canary health cues.	firmware/projects/canary-display/
Canary OTA	The signed-update engine every active firmware consumes — Ed25519 release signature, SHA-256, A/B rollback, HA update entity — lives in firmware/common/ota/ (docs/firmware_ota.md); canary-ota/ is the historical ESP-IDF harness it was promoted from.	firmware/common/ota/

Build plans, BOMs, enclosure notes, and bench procedures are collected in hardware docs. Firmware capability status: firmware/build_matrix.json is the generated truth per build; firmware features is the narrative audit matrix, which can lag it.

---

Trust, safety, and limits

SecuraCV should feel useful, not stressful. It is intentionally conservative about its claims:

• The invariants define what the kernel must not collect or expose.
• The event contract defines which claims are allowed.
• The threat model separates enforceable security boundaries from audited trust boundaries.
• The root paradox explains what host compromise can and cannot preserve.
• The Beacon and Chirp specs keep life-safety advisories distinct from emergency-broadcast impersonation and forbid PII on the wire.

A few bright lines keep the system calm:

• No face recognition, plate OCR, demographic estimates, or bulk identity search.
• No cloud dependency for verification.
• No life-safety shortcut that auto-originates Beacon alerts from sensors alone.
• No claim that outruns the implementation: if a feature is marked design, RFC, pending bench validation, or post-v1, treat it as exactly that.

The project values honest edges more than glossy overclaiming.

---

The monorepo at a glance

Everything ships from this one repository. The short version of the map — the full one, with a "where do I look for X" index, is in AGENTS.md:

Directory	What it is
src/	The witness kernel — the Rust daemon witnessd and its binaries
spec/	The normative contracts: invariants, the event contract, wire specs — each marked stable, draft, or spec-only
firmware/	The Canaries' ESP32 firmware: the canonical canary/ tree plus per-product trees under projects/, on one shared common/ core
canary-local/	The Lab — real firmware compiled to WebAssembly, running in your browser
custom_components/securacv/	The Home Assistant integration (distributed to HACS through its mirror)
privacy_witness_kernel/	The Home Assistant app (add-on) that wraps the kernel
desktop/ + desktop-lab/	The desktop Flasher / hub app, and the Lab desktop app — two different apps
ios/ + tvos/	The iPhone/iPad companion and the Witness Wall for Apple TV
docs/	Every guide and design doc, indexed by the CI-enforced map
devices/	One manifest per Canary, joining its board, builds, figure, CAD, and flasher facts
kernel/	Architecture docs — docs only, despite the name

If two directories sound alike, docs/CONSOLIDATION.md says which is the real one.

---

Documentation

The best entry point is the documentation map. It is checked in CI so new docs cannot become unreachable.

High-signal references:

• Home Assistant setup
• Frigate integration
• Operator guide
• Security docs
• Supply-chain transparency
• v1 roadmap
• Changelog

---

Status

SecuraCV is a v1 release candidate.

Current audited docs status:

• The root README now points at current setup paths, hardware families, Lab surfaces, and supply-chain verification.
• The docs map is CI-enforced, so Markdown under docs/ must remain reachable.
• The core Frigate/MQTT/witness-log path is verified end-to-end in CI.
• The RTSP ffmpeg path has a real roundtrip test.
• The v1 tag is still held for on-device hardware validation across the kernel/bridge path and representative ESP32 firmware.

Track the exact gate in v1 roadmap and recent work in CHANGELOG.

---

Contributing

SecuraCV is independent, open source, and Apache-2.0 licensed. Helpful contributions include:

• testing a real Home Assistant or Docker install,
• bench-validating Canary hardware,
• improving docs and examples,
• reviewing privacy/security boundaries,
• building small, calm, local-first user experiences.

Read CONTRIBUTING, the security policy, and the repo engineering guide in AGENTS.md before opening a PR.

---

License & usage

The software is Apache-2.0 (LICENSE) — free to run, anywhere, at any scale, forever. Two short, plain-language companions cover the rest:

• LICENSING.md — who pays, who doesn't, and why. Free for schools, universities, nonprofits, groups, businesses, and governments to self-host at any scale; the short list of things that cost money (bought hardware, court-grade attestation, support SLAs) each has a free path; and the survival promises (no phone-home, no kill switch, standalone verifier) that make it safe to standardize on.
• TRADEMARK.md — using the name, logo, and mascot: a free "Works with SecuraCV" badge for anyone, primary marks by public grant.
• TERMS.md — a plain-language template for paid-services terms (advisory-only, liability capped at fees, not a safety device). A scaffold for your attorney to finish — not legal advice, and it covers services only, never the Apache-2.0 software.

SecuraCV — calm local proof, without the surveillance archive.