@trillboards/edge-sdk 0.2.40 → 0.2.41

package/README.md

@@ -249,7 +249,7 @@ Or register via the [Trillboards API](https://api.trillboards.com/developer).
 | [docs/CLI.md](../../docs/CLI.md) | Full CLI reference with all commands, flags, and configuration |
 | [docs/MCP.md](../../docs/MCP.md) | MCP server reference for AI agent integration |
 | [docs/STATUS_API.md](../../docs/STATUS_API.md) | Status endpoint API reference |
-| [deploy/macos/README.md](deploy/macos/README.md) | macOS one-click `.pkg` installer (cloud-sense CCTV connector) |
+| [deploy/macos/README.md](deploy/macos/README.md) | macOS one-click `.pkg` installer (local-inference CCTV connector) |
 | [deploy/docker/README.md](../../deploy/docker/README.md) | Docker deployment guide |
 | [deploy/helm/README.md](../../deploy/helm/README.md) | Helm chart deployment guide |
 | [create-trillboards-edge](../../../create-trillboards-edge/README.md) | Project scaffolding tool |

package/deploy/docker/{Dockerfile.cloud-sense → Dockerfile.connector}

@@ -1,37 +1,46 @@
-# Trillboards Edge AI SDK — BYO-CCTV connector container
+# Trillboards Edge AI SDK — BYO-CCTV connector container (LOCAL INFERENCE ONLY)
 #
-# No local ONNX models bundled, so this image never downloads models and is much
-# lighter than the cpu/cuda/openvino variants. It pairs with a short-lived claim
-# code (the device token is delivered at pair, NEVER baked into the image) then
+# No models bundled, so this image never downloads models and is much lighter
+# than the cpu/cuda/openvino variants. It pairs with a short-lived claim code
+# (the device token is delivered at pair, NEVER baked into the image) then
 # senses. Same connector + same CLI as the macOS/Windows installers — ONE image,
 # not a parallel one.
 #
-# TWO TAGS, ONE IMAGE. `SENSE_MODE` bakes the default the entrypoint runs:
-#   :auto-sense  (SENSE_MODE=auto-sense, the default and the recommended tag)
-#                probes localSensing.litertLmBaseUrl at startup and commits to
-#                on-device inference if a healthy litert-lm is hosting the model.
-#                Because this image bundles NO model, the entrypoint also asserts
-#                localSensing.allowCloudFallback=true — auto-sense otherwise
-#                treats cloud as opt-in and would WAIT forever for a runtime that
-#                is never going to appear here. With that assert, a plain
-#                `docker run` behaves exactly like :cloud-sense (frames to the
-#                cloud VLM) and additionally AUTO-UPGRADES to on-device with no
-#                restart the moment a litert-lm becomes reachable.
-#   :cloud-sense (SENSE_MODE=cloud-sense) forces the cloud VLM. Kept because the
-#                portal one-liner and existing installs reference it.
-# TRILLBOARDS_SENSE_MODE overrides either at run time.
+# ── This image no longer has a cloud path ──────────────────────────────────
 #
-# WHAT CLOUD MODE COSTS. Measured 2026-08-12 over 255,812 image-bearing cloud VLM
-# calls: $0.007008 per analyzed frame, so one camera at the 300s default cadence
-# is $60.55/month and a 16-camera store is $969/month. On-device inference has no
-# per-frame cost. That gap is the entire reason this image defaults to probing.
+# It was `Dockerfile.cloud-sense` and it published TWO tags, `:auto-sense` and
+# `:cloud-sense`, and the entrypoint asserted `localSensing.allowCloudFallback:
+# true` into the config on every start — so BOTH tags sent every analyzed frame
+# to the cloud VLM until a litert-lm happened to appear.
 #
-# Build: docker build -f packages/edge-sdk/deploy/docker/Dockerfile.cloud-sense \
-#                     --build-arg SENSE_MODE=auto-sense \
-#                     -t trillboards/edge-sdk:auto-sense .    # context = trillboards-edge-sdk
-# Run:   docker run -e TRILLBOARDS_CLAIM_CODE=XXXX-XXXX \
+# WHAT THAT COST. Measured 2026-08-12 over 255,812 image-bearing cloud VLM calls:
+# $0.007008 per analyzed frame. At the 30s cadence that is ~$605/camera/month, so
+# a 16-camera store was ~$9,688/month against a $99-500 subscription — roughly
+# 10x underwater. On-device inference has no per-frame cost. The cloud path is
+# gone from the connector entirely; there is no flag that brings it back.
+#
+# ── Therefore: this image REQUIRES a litert-lm you run ─────────────────────
+#
+# It bundles no model (the 2.4 GB Gemma weights have their own OTA channel; see
+# cctv-connector-macos-readiness.md §7a for why baking them into a shipping
+# artifact is waste). Point the connector at a serve on the host:
+#
+#   docker run --network host ...                       # serve on localhost:9379
+#   # or set localSensing.litertLmBaseUrl in the config:
+#   #   http://host.docker.internal:9379
+#
+# Without one, `auto-sense` WAITS: it analyzes nothing and uploads no FRAMES.
+# It is not dark, though — it runs the same manager in health-only mode, so the
+# cameras still open, video is still proven by a decode-only probe, and camera
+# health still reports on the heartbeat with sensingState='unavailable'. The
+# portal shows "connector alive, sensing unavailable" rather than something
+# indistinguishable from a dead machine.
+#
+# Build: docker build -f packages/edge-sdk/deploy/docker/Dockerfile.connector \
+#                     -t trillboards/edge-sdk:connector .   # context = trillboards-edge-sdk
+# Run:   docker run --network host -e TRILLBOARDS_CLAIM_CODE=XXXX-XXXX \
 #                   -v trillboards:/app/data \
-#                   ghcr.io/trillboards/edge-sdk:auto-sense
+#                   ghcr.io/trillboards/edge-sdk:connector
 
 FROM node:20-slim AS builder
 
@@ -58,7 +67,7 @@ FROM node:20-slim
 
 LABEL maintainer="Trillboards <engineering@trillboards.com>"
 ARG SENSE_MODE=auto-sense
-LABEL description="Trillboards Edge AI SDK — BYO-CCTV connector (no bundled models)"
+LABEL description="Trillboards Edge AI SDK — BYO-CCTV connector (local inference only, no bundled models)"
 
 # ffmpeg = RTSP frame capture; ca-certificates/curl = TLS + healthcheck.
 RUN apt-get update && apt-get install -y --no-install-recommends \
@@ -69,8 +78,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 
 WORKDIR /app
 
-# Built packages (the cloud path lazy-requires the local ONNX stack, so it is
-# never loaded at runtime — but the workspace deps must resolve).
+# Built packages. The workspace deps must resolve even for the paths this image
+# does not take.
 COPY --from=builder /build/packages/edge-core/dist packages/edge-core/dist
 COPY --from=builder /build/packages/edge-core/package.json packages/edge-core/
 COPY --from=builder /build/packages/edge-sensing/dist packages/edge-sensing/dist
@@ -88,8 +97,8 @@ COPY --from=builder /build/packages/edge-platform-linux/package.json packages/ed
 COPY --from=builder /build/packages/edge-platform-rtsp/dist packages/edge-platform-rtsp/dist
 COPY --from=builder /build/packages/edge-platform-rtsp/package.json packages/edge-platform-rtsp/
 
-# Production deps only (NO model download — inference is cloud-side, or on a
-# litert-lm the operator runs themselves and points this at).
+# Production deps only (NO model download — inference runs on a litert-lm the
+# operator runs and points this at).
 COPY --from=builder /build/package.json /build/package-lock.json* ./
 RUN npm ci --legacy-peer-deps --omit=dev 2>/dev/null || npm install --legacy-peer-deps --omit=dev
 
@@ -104,14 +113,18 @@ RUN chmod +x /usr/local/bin/connector-entrypoint.sh
 ENV NODE_ENV=production
 ENV TRILLBOARDS_API_BASE="https://api.trillboards.com"
 ENV TRILLBOARDS_CONFIG="/app/data/trillboards.config.json"
-# Baked per tag by the publish matrix; overridable per run.
+# Baked by the publish matrix; overridable per run with auto-sense|local-sense.
+# There is no cloud-sense value any more — the entrypoint rejects it by name so
+# an existing `-e TRILLBOARDS_SENSE_MODE=cloud-sense` fails loudly at start
+# instead of silently meaning something else.
 ENV TRILLBOARDS_SENSE_MODE=${SENSE_MODE}
 
-# No HEALTHCHECK / status-server port: the sensing CLI paths build
-# CloudSensingManager directly and never start the StatusServer (that wiring is
-# only in EdgeAgent.start), so a /health:9090 probe would never respond and Docker
-# would mark a perfectly-streaming container unhealthy (Codex P2 on #7730).
-# Liveness for this streaming worker is observed server-side via the cloud ingest,
-# not a local HTTP probe.
+# No HEALTHCHECK / status-server port: the sensing CLI paths build the sensing
+# manager directly and never start the StatusServer (that wiring is only in
+# EdgeAgent.start), so a /health:9090 probe would never respond and Docker would
+# mark a perfectly-streaming container unhealthy (Codex P2 on #7730). Liveness
+# for this streaming worker is observed server-side via the connector beacon —
+# which now also fires while `auto-sense` is WAITING for its model, so a stalled
+# container is distinguishable from a dead one without a local probe.
 
 ENTRYPOINT ["/usr/local/bin/connector-entrypoint.sh"]

package/deploy/docker/README.md

@@ -4,13 +4,72 @@ This guide covers deploying the Trillboards Edge AI agent as a Docker container
 
 ## Image Variants
 
-Three pre-built images target different hardware profiles:
+Four pre-built images. The first three are the **DOOH screen agent** (on-device ONNX,
+bundled models) and target different hardware profiles. The fourth is the **BYO-CCTV
+connector**, which is a different product on different hardware — see below.
 
 | Tag | Base Image | Execution Provider | Architecture | Use Case |
 |-----|-----------|-------------------|--------------|----------|
 | `latest` | `node:20-slim` | CPU (WASM) | `linux/amd64`, `linux/arm64` | Generic Linux devices, ARM SBCs, Raspberry Pi 4+ |
 | `cuda` | `nvidia/cuda:12.3.2-runtime-ubuntu22.04` | NVIDIA CUDA | `linux/amd64` | NVIDIA Jetson, GPU-equipped signage players |
 | `openvino` | `openvino/ubuntu22_runtime:2024.0.0` | Intel OpenVINO | `linux/amd64` | Backpackster, Intel NUC, mini-PCs with Intel HD 620+ |
+| `auto-sense` | `node:20-slim` | **LiteRT-LM you run** (see below) | `linux/amd64`, `linux/arm64` | **BYO-CCTV connector** — pull frames from an existing NVR/DVR over RTSP |
+
+## The BYO-CCTV connector image (`:auto-sense`)
+
+Built from `Dockerfile.connector`. It pairs with a short-lived claim code from the
+portal (the device token is delivered at pair, **never baked into the image**), then
+senses. Same connector and same CLI as the macOS/Windows installers — one image, not
+a parallel product.
+
+### It is LOCAL-INFERENCE ONLY, and it bundles no model
+
+The connector runs Gemma **on the machine** via LiteRT-LM. There is no cloud VLM path
+in it, no `allowCloudFallback`, and no `cloud-sense` mode. This image ships no model,
+so you must give it a `litert-lm serve` it can reach:
+
+```bash
+# serve on the host's localhost:9379
+docker run --network host \
+  -e TRILLBOARDS_CLAIM_CODE=XXXX-XXXX \
+  -v trillboards:/app/data \
+  ghcr.io/trillboards/edge-sdk:auto-sense
+
+# …or point it at one explicitly, via localSensing.litertLmBaseUrl in the config:
+#   "litertLmBaseUrl": "http://host.docker.internal:9379"
+```
+
+Without a reachable serve the connector **waits**: it analyzes nothing and uploads no
+frames, but it still opens the cameras and reports their health (`sensingState:
+'unavailable'`), so the portal shows a live connector that cannot sense yet rather
+than something indistinguishable from a dead machine. It starts sensing automatically
+— no restart — the moment a serve appears.
+
+Mount `/app/data` on a volume so the paired config survives restarts; re-pairing needs
+a fresh code from the portal.
+
+### `TRILLBOARDS_SENSE_MODE`
+
+| Value | Behaviour |
+|---|---|
+| `auto-sense` (default) | Probe for a local runtime; run on-device if healthy, otherwise wait and report health. |
+| `local-sense` | Require the local runtime; no probe loop. |
+| `cloud-sense` | **Removed.** Rejected by name at start with a message, rather than ignored — existing units and container args pin this verb, and a silent behaviour change would be worse than a hard stop. |
+
+### Why there is no cloud tag any more
+
+There used to be a second tag, `:cloud-sense`, and the entrypoint asserted
+`localSensing.allowCloudFallback: true` on every start — so **both** tags sent every
+analyzed frame to the cloud VLM. Measured 2026-08-12 over 255,812 image-bearing cloud
+VLM calls, that cost **$0.007008 per analyzed frame**: ~$605/camera/month at a 30s
+cadence, so a 16-camera store ran ~$9,688/month against a $99-500 subscription. The
+path was removed rather than rate-limited. On-device inference has no per-frame cost.
+
+The tag NAME `:auto-sense` is deliberately unchanged, so existing `docker pull`
+one-liners in the portal and runbooks keep resolving.
+
+> **Note:** this says nothing about the DOOH **screen** fleet, whose cloud vision is
+> untouched — different product, different hardware, and it runs server-side.
 
 ## Registry Locations
 
@@ -22,6 +81,7 @@ Images are published to two registries. Use whichever is reachable from your dep
 docker pull ghcr.io/trillboards/edge-sdk:latest
 docker pull ghcr.io/trillboards/edge-sdk:cuda
 docker pull ghcr.io/trillboards/edge-sdk:openvino
+docker pull ghcr.io/trillboards/edge-sdk:auto-sense   # BYO-CCTV connector
 ```
 
 **AWS ECR (private, for production fleet):**
@@ -253,6 +313,18 @@ docker build -f packages/edge-sdk/deploy/docker/Dockerfile.openvino \
   -t trillboards/edge-sdk:openvino .
 ```
 
+**BYO-CCTV connector image:**
+
+```bash
+cd trillboards-edge-sdk
+docker build -f packages/edge-sdk/deploy/docker/Dockerfile.connector \
+  --build-arg SENSE_MODE=auto-sense \
+  -t trillboards/edge-sdk:auto-sense .
+```
+
+(The file was `Dockerfile.cloud-sense` until edge-sdk 0.2.41. It was renamed because a
+file named after a mode the connector no longer has is a trap for the next reader.)
+
 ### Build Arguments
 
 The Dockerfiles do not expose build arguments by default. To customize the build (for example, to pin a specific Node.js version or add additional system packages), edit the relevant Dockerfile directly.

package/deploy/docker/connector-entrypoint.sh

@@ -5,50 +5,60 @@
 # thereafter it senses. Mount /app/data on a volume so the paired config survives
 # restarts — re-pairing needs a fresh code from the portal.
 #
-# ── The mode is a build arg, and the DEFAULT is auto-sense ──────────────────
+# ── LOCAL INFERENCE ONLY ───────────────────────────────────────────────────
 #
-# This entrypoint used to `exec cloud-sense` unconditionally, so the Docker path
-# forced the expensive mode while §A5 of cctv-rushi-activation.md recommended
-# auto-sense and §0 told the reader "the connector runs auto-sense". It did not.
+# This entrypoint used to assert `localSensing.allowCloudFallback: true` into the
+# paired config on EVERY start, so a plain `docker run` sent every analyzed frame
+# to the cloud VLM. It was one of three places that forced the cloud path (the
+# systemd unit hardcoded `cloud-sense`; `TRILLBOARDS_SENSE_MODE` overrode at run
+# time). All three are gone.
 #
-# auto-sense probes `localSensing.litertLmBaseUrl` at startup and commits to
-# local if a healthy litert-lm is hosting the model. An operator who runs
-# `litert-lm serve` on the host and points the connector at it (--network host,
-# or litertLmBaseUrl: http://host.docker.internal:9379 in the config) gets the
-# on-device path from this SAME image, at no per-frame cloud cost.
+# WHY. Measured 2026-08-12 over 255,812 image-bearing cloud VLM calls: $0.007008
+# per analyzed frame — ~$605/camera/month at a 30s cadence, ~$9,688/month for a
+# 16-camera store against a $99-500 subscription. The product was ~10x underwater
+# at scale. On-device inference has no per-frame cost.
 #
-# ── Why this image must also enable cloud FALLBACK ─────────────────────────
+# This SUPERSEDES the escalation architecture from #11971 ("local Gemma decides
+# *when* to look, the cloud decides *what* it saw") and the frequency-based cost
+# control in plans/cctv-byo-sensing-plan.md:26. Cost is no longer managed by
+# looking less often; the metered path is removed.
 #
-# `auto-sense` treats cloud inference as opt-in: with `allowCloudFallback`
-# unset it probes, fails, and WAITS — uploading nothing — because on a laptop or
-# a mini-PC that is downloading a 2.4 GB model, idling briefly is better than
-# silently starting a meter. That is right for the macOS/Windows installers,
-# which provision a local model.
+# ── What this image needs from you ────────────────────────────────────────
 #
-# It is wrong here. This image bundles NO model and never downloads one, so a
-# plain `docker run` has nothing to wait FOR: without the fallback the connector
-# would sit idle forever and the operator would see cameras that never report.
-# So the entrypoint asserts `localSensing.allowCloudFallback: true` into the
-# paired config for auto-sense. Net behaviour for a plain run is identical to
-# the old `:cloud-sense` — frames go to the cloud VLM — except the connector now
-# AUTO-UPGRADES to on-device with no restart the moment a litert-lm becomes
-# reachable.
+# It bundles no model, so it needs a litert-lm serve it can reach:
+#   docker run --network host ...              # serve on localhost:9379
+#   # or set localSensing.litertLmBaseUrl to http://host.docker.internal:9379
 #
-# TRILLBOARDS_SENSE_MODE overrides at run time: cloud-sense forces the cloud VLM,
-# local-sense refuses to fall back.
+# Without one, `auto-sense` probes and WAITS: it analyzes nothing and uploads no
+# FRAMES. It is not dark, though — it runs the same manager in health-only mode,
+# so the cameras open, video is proven, and camera health reports on the
+# heartbeat with sensingState='unavailable'. The portal sees a live connector
+# that cannot sense yet, rather than one indistinguishable from a dead machine.
+#
+# TRILLBOARDS_SENSE_MODE selects auto-sense (probe, then local-or-wait) or
+# local-sense (require local, no probe loop). `cloud-sense` is rejected BY NAME
+# rather than ignored, so an existing deployment pinning it stops with a message
+# instead of silently getting different behaviour.
 set -eu
 
 CONFIG="${TRILLBOARDS_CONFIG:-/app/data/trillboards.config.json}"
 API_BASE="${TRILLBOARDS_API_BASE:-https://api.trillboards.com}"
 CLI="node packages/edge-sdk/dist/cli.js"
-# Baked per image variant (:auto-sense -> auto-sense, :cloud-sense -> cloud-sense),
-# overridable per run.
 MODE="${TRILLBOARDS_SENSE_MODE:-auto-sense}"
 
 case "$MODE" in
-  auto-sense|cloud-sense|local-sense) ;;
+  auto-sense|local-sense) ;;
+  cloud-sense)
+    echo "[connector] TRILLBOARDS_SENSE_MODE=cloud-sense is no longer supported." >&2
+    echo "[connector] The connector is local-inference only: cloud VLM inference cost" >&2
+    echo "[connector] \$0.007008/frame (~\$9,688/month for a 16-camera store), so the path" >&2
+    echo "[connector] was removed rather than rate-limited." >&2
+    echo "[connector] Use auto-sense (the default) and give the container a litert-lm:" >&2
+    echo "[connector]   docker run --network host ...   # serve on localhost:9379" >&2
+    exit 1
+    ;;
   *)
-    echo "[connector] Unknown TRILLBOARDS_SENSE_MODE '$MODE' (want auto-sense|cloud-sense|local-sense)." >&2
+    echo "[connector] Unknown TRILLBOARDS_SENSE_MODE '$MODE' (want auto-sense|local-sense)." >&2
     exit 1
     ;;
 esac
@@ -57,64 +67,20 @@ if [ ! -f "$CONFIG" ]; then
   if [ -z "${TRILLBOARDS_CLAIM_CODE:-}" ]; then
     echo "[connector] No paired config and no TRILLBOARDS_CLAIM_CODE." >&2
     echo "[connector] Get a code from the Trillboards portal (Add a camera -> Install), then:" >&2
-    echo "[connector]   docker run -e TRILLBOARDS_CLAIM_CODE=XXXX-XXXX -v trillboards:/app/data ghcr.io/trillboards/edge-sdk:auto-sense" >&2
+    echo "[connector]   docker run --network host -e TRILLBOARDS_CLAIM_CODE=XXXX-XXXX -v trillboards:/app/data ghcr.io/trillboards/edge-sdk:connector" >&2
     exit 1
   fi
   echo "[connector] Pairing with claim code (token delivered at pair, never baked)..."
   # shellcheck disable=SC2086
-  $CLI pair --code "$TRILLBOARDS_CLAIM_CODE" --config "$CONFIG" --api-base "$API_BASE"
-fi
-
-if [ "$MODE" = "auto-sense" ]; then
-  # This image ships no local model, so auto-sense MUST be allowed to fall back
-  # or it waits forever for something that will never arrive. Idempotent, and it
-  # never touches a value the operator set themselves.
-  #
-  # The assert WRITES, and a config file is very often mounted read-only
-  #   (-v ./trillboards.config.json:/app/data/trillboards.config.json:ro)
-  # which is a perfectly reasonable way to run this image and skips pairing
-  # entirely. Under `set -e` an unguarded writeFileSync there killed the
-  # container on every single start, with a raw stack trace, because a DEFAULT
-  # could not be persisted. So a failed write degrades to exactly the behaviour
-  # the write was there to guarantee — cloud inference this run — and says so.
-  set +e
-  node -e '
-    const fs = require("fs");
-    const p = process.argv[1];
-    let c;
-    try { c = JSON.parse(fs.readFileSync(p, "utf-8")); } catch (e) {
-      console.error("[connector] cannot read config for fallback assert: " + e.message);
-      process.exit(0);
-    }
-    c.localSensing = c.localSensing || {};
-    if (c.localSensing.allowCloudFallback === true) process.exit(0);
-    if (c.localSensing.allowCloudFallback === false) {
-      console.error("[connector] localSensing.allowCloudFallback is explicitly false — honoring it; this connector will WAIT for a local runtime and upload nothing until one is reachable.");
-      process.exit(0);
-    }
-    c.localSensing.allowCloudFallback = true;
-    try {
-      fs.writeFileSync(p, JSON.stringify(c, null, 2));
-    } catch (e) {
-      console.error("[connector] cannot persist localSensing.allowCloudFallback to " + p + ": " + e.message);
-      process.exit(3);
-    }
-    console.error("[connector] enabled localSensing.allowCloudFallback (this image bundles no local model).");
-  ' "$CONFIG"
-  FALLBACK_ASSERT_RC=$?
-  set -e
-  if [ "$FALLBACK_ASSERT_RC" = "3" ]; then
-    echo "[connector] config is not writable, so auto-sense cannot record its cloud-fallback policy." >&2
-    echo "[connector] Running cloud-sense for this process instead — cameras still report. To get the" >&2
-    echo "[connector] on-device auto-upgrade, mount the config writable or set localSensing.allowCloudFallback." >&2
-    MODE=cloud-sense
-  fi
+  $CLI pair --code "$TRILLBOARDS_CLAIM_CODE" --config "$CONFIG"  --api-base "$API_BASE"
 fi
 
 if [ "$MODE" = "auto-sense" ]; then
-  echo "[connector] Starting $MODE (API $API_BASE) — probing for on-device inference," >&2
-  echo "[connector] falling back to the cloud VLM if none is reachable, and" >&2
-  echo "[connector] auto-upgrading to on-device (no restart) if one appears." >&2
+  echo "[connector] Starting $MODE (API $API_BASE) — probing for on-device inference." >&2
+  echo "[connector] This image bundles no model. If no litert-lm is reachable the" >&2
+  echo "[connector] connector analyzes nothing and uploads no frames — but it still" >&2
+  echo "[connector] opens the cameras and reports their health, so the portal shows it" >&2
+  echo "[connector] alive. It starts sensing automatically once a litert-lm appears." >&2
 else
   echo "[connector] Starting explicitly selected $MODE (API $API_BASE)..." >&2
 fi

package/deploy/macos/README.md

@@ -97,7 +97,7 @@ bash packages/edge-sdk/deploy/macos/test-install-pair.sh
 ```
 
 No sudo. It builds the pkg, installs it home-domain, starts a local stub
-pair+analyze server, pairs headlessly, runs `cloud-sense` against a **synthetic
+pair+analyze server, pairs headlessly, runs `auto-sense` against a **synthetic
 ffmpeg source** (a generated clip via `file:` — no RTSP server needed), asserts a
 **real JPEG frame** is produced by the bundled ffmpeg and POSTed with the paired
 `X-Device-Token`, verifies the LaunchAgent bootstraps and senses autonomously,

package/deploy/macos/test-install-pair.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 #
 # test-install-pair.sh — local, no-sudo, self-cleaning end-to-end proof that the
-# Trillboards "cloud-sense" CCTV connector .pkg builds, installs home-domain,
+# Trillboards CCTV connector .pkg builds, installs home-domain,
 # pairs, and actually senses (real bundled-ffmpeg JPEG capture → POST) on THIS
 # Mac.
 #
@@ -16,7 +16,7 @@
 #      path runs without an RTSP-server rabbit-hole.
 #   4. Pair headlessly (trillboards-edge pair --code … --api-base …). Assert
 #      exit 0, config written 0600 with the camera + deviceToken.
-#   5. Start the connector from that config (cloud-sense) and assert it produces
+#   5. Start the connector from that config (auto-sense) and assert it produces
 #      a real JPEG frame via the BUNDLED ffmpeg and POSTs it to
 #      /v2/earner/audience-analyze carrying the paired X-Device-Token. Also
 #      assert the per-user LaunchAgent bootstraps + senses end-to-end.
@@ -50,7 +50,7 @@ SAMPLE_MP4="$SCRATCH/cctv_sample.mp4"
 STUB_JS="$SCRATCH/stub_server.js"
 STUB_OUT="$SCRATCH/stub.out"
 TEST_CONFIG="$SCRATCH/paired.config.json"
-CS_OUT="$SCRATCH/cloud-sense.out"
+CS_OUT="$SCRATCH/auto-sense.out"
 STUB_PID=""
 CS_PID=""
 
@@ -160,7 +160,7 @@ if printf '%s' "$NODE_VER" | grep -q '^v'; then ok "bundled node runs ($NODE_VER
 if "$EDGE_ROOT/bin/ffmpeg" -version >/dev/null 2>&1; then ok "bundled ffmpeg runs"; else nok "bundled ffmpeg did not run"; fi
 
 # the connector runs through the bundled launcher (this also proves the lazy
-# require keeps the cloud-sense entrypoint free of the ONNX stack — the bundle
+# require keeps the pair/sense entrypoint free of the ONNX stack — the bundle
 # ships NO onnxruntime-node).
 LAUNCH_VER="$("$EDGE_ROOT/bin/trillboards-edge" version 2>&1 || true)"
 if printf '%s' "$LAUNCH_VER" | grep -q 'edge-sdk v'; then ok "trillboards-edge version works via bundled node ($LAUNCH_VER)"; else nok "trillboards-edge version failed" "$LAUNCH_VER"; fi
@@ -277,9 +277,9 @@ else
 fi
 
 # ─── STEP 5a: connector starts from the config + senses (foreground, bounded) ─
-diag "STEP 5a — cloud-sense from config: real bundled-ffmpeg JPEG → POST"
+diag "STEP 5a — auto-sense from config: real bundled-ffmpeg JPEG → POST"
 if [ -f "$TEST_CONFIG" ]; then
-  "$EDGE_ROOT/bin/trillboards-edge" cloud-sense --config "$TEST_CONFIG" >"$CS_OUT" 2>&1 &
+  "$EDGE_ROOT/bin/trillboards-edge" auto-sense --config "$TEST_CONFIG" >"$CS_OUT" 2>&1 &
   CS_PID=$!
   # Wait until we see at least one analyze POST (cadence is 1.5s) — up to ~12s.
   SENSED=0
@@ -293,9 +293,9 @@ if [ -f "$TEST_CONFIG" ]; then
   CS_PID=""
 
   if [ "$SENSED" -eq 1 ]; then
-    ok "cloud-sense captured + POSTed a frame (HTTP 200 in connector log)"
+    ok "auto-sense captured + POSTed a frame (HTTP 200 in connector log)"
   else
-    nok "cloud-sense did not produce a successful POST" "$(tail -8 "$CS_OUT" 2>/dev/null)"
+    nok "auto-sense did not produce a successful POST" "$(tail -8 "$CS_OUT" 2>/dev/null)"
   fi
 
   # Inspect what the stub actually received.
@@ -310,7 +310,7 @@ if [ -f "$TEST_CONFIG" ]; then
     nok "stub stats file missing — cannot verify POST contents"
   fi
 else
-  nok "skipped cloud-sense (no config)"
+  nok "skipped auto-sense (no config)"
 fi
 
 # ─── STEP 5b: LaunchAgent bootstrap + autonomous sensing ─────────────────────

package/deploy/systemd/install.sh

@@ -39,7 +39,19 @@ cd /opt/trillboards
 sudo -u trillboards npm init -y --silent 2>/dev/null
 sudo -u trillboards npm install @trillboards/edge-sdk @trillboards/edge-platform-linux @trillboards/edge-platform-rtsp
 
-# cloud-sense uses the cloud VLM for inference — NO local ONNX models to download.
+# LOCAL INFERENCE ONLY. The unit runs `auto-sense`, which is local-or-wait — it
+# never uploads a frame to a cloud VLM. So the on-device runtime is not optional
+# on this platform any more: provision LiteRT-LM + Gemma before the service can
+# do anything. ~2.4 GB, public HF repo, home-domain (no sudo pip).
+echo "Provisioning the on-device AI runtime (LiteRT-LM + Gemma, ~2.4 GB)..."
+sudo cp node_modules/@trillboards/edge-sdk/deploy/systemd/trillboards-litertlm.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable trillboards-litertlm
+sudo -u trillboards HOME=/opt/trillboards bash \
+  node_modules/@trillboards/edge-sdk/deploy/systemd/setup-litertlm.sh \
+  || echo "  *** Local AI provisioning did not finish. The connector will run and report
+  *** itself as 'waiting for the on-device model' until it does — it will NOT
+  *** fall back to paid cloud inference. Re-run install.sh to retry."
 
 # Pair with a claim code from the portal (Add a camera -> Install). Pairing writes
 # /etc/trillboards/config.json (device token + feeds) — the token is delivered at
@@ -74,5 +86,8 @@ echo "Next steps:"
 echo "  1. (If not paired above) sudo -u trillboards npx trillboards-edge pair --code <CODE> --config /etc/trillboards/config.json"
 echo "  2. Start: sudo systemctl start trillboards-edge"
 echo "  3. Logs:  sudo journalctl -u trillboards-edge -f"
+echo "  4. Local AI: sudo systemctl status trillboards-litertlm"
+echo "     (the connector runs ON-DEVICE only; if the serve is down it waits and"
+echo "      reports 'waiting' in the portal rather than billing cloud inference)"
 echo "  4. Status: sudo systemctl status trillboards-edge"
 echo ""