@trillboards/edge-sdk 0.2.3 → 0.2.6

package/README.md

@@ -184,7 +184,7 @@ docker run -d \
   -e DEVICE_TOKEN=your-token \
   -p 9090:9090 \
   --device /dev/video0:/dev/video0 \
-  trillboards/edge-sdk:latest
+  ghcr.io/trillboards/edge-sdk:latest
 
 # NVIDIA GPU
 docker run -d \
@@ -193,7 +193,7 @@ docker run -d \
   -e DEVICE_TOKEN=your-token \
   -p 9090:9090 \
   --device /dev/video0:/dev/video0 \
-  trillboards/edge-sdk:cuda
+  ghcr.io/trillboards/edge-sdk:cuda
 ```
 
 **docker-compose:**
@@ -201,7 +201,7 @@ docker run -d \
 ```yaml
 services:
   edge-agent:
-    image: trillboards/edge-sdk:latest
+    image: ghcr.io/trillboards/edge-sdk:latest
     restart: unless-stopped
     environment:
       - DEVICE_TOKEN=${DEVICE_TOKEN}
@@ -249,6 +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/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

@@ -0,0 +1,117 @@
+# Trillboards Edge AI SDK — BYO-CCTV connector container
+#
+# 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
+# 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.
+#
+# 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.
+#
+# 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 \
+#                   -v trillboards:/app/data \
+#                   ghcr.io/trillboards/edge-sdk:auto-sense
+
+FROM node:20-slim AS builder
+
+WORKDIR /build
+
+# Workspace package files first (layer caching).
+COPY package.json package-lock.json* ./
+COPY packages/edge-core/package.json packages/edge-core/
+COPY packages/edge-sensing/package.json packages/edge-sensing/
+COPY packages/edge-federated/package.json packages/edge-federated/
+COPY packages/edge-ads/package.json packages/edge-ads/
+COPY packages/edge-cloud/package.json packages/edge-cloud/
+COPY packages/edge-sdk/package.json packages/edge-sdk/
+COPY packages/edge-platform-linux/package.json packages/edge-platform-linux/
+COPY packages/edge-platform-rtsp/package.json packages/edge-platform-rtsp/
+
+RUN npm ci --legacy-peer-deps 2>/dev/null || npm install --legacy-peer-deps
+
+COPY . .
+RUN npm run build --workspaces --if-present
+
+# ─── Production image ─────────────────────────────────────────────────────
+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)"
+
+# ffmpeg = RTSP frame capture; ca-certificates/curl = TLS + healthcheck.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    ca-certificates \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+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).
+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
+COPY --from=builder /build/packages/edge-sensing/package.json packages/edge-sensing/
+COPY --from=builder /build/packages/edge-federated/dist packages/edge-federated/dist
+COPY --from=builder /build/packages/edge-federated/package.json packages/edge-federated/
+COPY --from=builder /build/packages/edge-ads/dist packages/edge-ads/dist
+COPY --from=builder /build/packages/edge-ads/package.json packages/edge-ads/
+COPY --from=builder /build/packages/edge-cloud/dist packages/edge-cloud/dist
+COPY --from=builder /build/packages/edge-cloud/package.json packages/edge-cloud/
+COPY --from=builder /build/packages/edge-sdk/dist packages/edge-sdk/dist
+COPY --from=builder /build/packages/edge-sdk/package.json packages/edge-sdk/
+COPY --from=builder /build/packages/edge-platform-linux/dist packages/edge-platform-linux/dist
+COPY --from=builder /build/packages/edge-platform-linux/package.json packages/edge-platform-linux/
+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).
+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
+
+# Pairing writes the config here; mount /app/data on a volume so the paired
+# config (device token + feeds) survives container restarts.
+RUN mkdir -p /app/data
+
+# First-run pair → sense (claim code in, token never baked).
+COPY packages/edge-sdk/deploy/docker/connector-entrypoint.sh /usr/local/bin/connector-entrypoint.sh
+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.
+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.
+
+ENTRYPOINT ["/usr/local/bin/connector-entrypoint.sh"]

package/deploy/docker/Dockerfile.cpu

@@ -1,6 +1,6 @@
 # Trillboards Edge AI SDK — CPU-only container
 # Usage: docker build -f Dockerfile.cpu -t trillboards/edge-sdk:latest ../../
-# Run:   docker run -e DEVICE_TOKEN=xxx trillboards/edge-sdk:latest
+# Run:   docker run -e DEVICE_TOKEN=xxx ghcr.io/trillboards/edge-sdk:latest
 
 FROM node:20-slim AS builder
 
@@ -65,26 +65,35 @@ RUN npm ci --legacy-peer-deps --omit=dev 2>/dev/null || npm install --legacy-pee
 # Create models directory
 RUN mkdir -p /app/models /app/data
 
-# Download default models at build time
-RUN node -e " \
-  const https = require('https'); \
-  const fs = require('fs'); \
-  const models = { \
-    'blazeface.onnx': 'https://models.trillboards.com/blazeface_128x128.onnx', \
-    'yamnet.onnx': 'https://models.trillboards.com/yamnet_classification.onnx', \
-  }; \
-  Object.entries(models).forEach(([name, url]) => { \
-    console.log('Downloading ' + name + '...'); \
-    const file = fs.createWriteStream('/app/models/' + name); \
-    https.get(url, (res) => { \
-      if (res.statusCode === 301 || res.statusCode === 302) { \
-        https.get(res.headers.location, (r) => r.pipe(file)); \
-      } else { \
-        res.pipe(file); \
-      } \
-    }); \
-  }); \
-" 2>/dev/null || echo "Model download skipped (build-time network may be unavailable)"
+# NO build-time model download. `models.trillboards.com` was never provisioned:
+# the trillboards.com zone has no `models` record, so the name is caught by the
+# `*.trillboards.com` wildcard A-alias and answered by the application ALB, which
+# returns the marketing SPA's index.html for every path. (An invented subdomain
+# resolves to the identical IPs — it is the wildcard, not a host.) No CloudFront
+# alias, no S3 bucket, no terraform for it has ever existed; the hostname was
+# invented in the same commit as the downloader (#996, 2026-03-09).
+#
+# The download this replaces verified only `if (size < 1000)`, and the SPA response
+# is 2490 bytes — so it PASSED, printed "All models downloaded successfully", and
+# baked two copies of a web page into the image as blazeface.onnx and yamnet.onnx.
+# Reproduced verbatim on 2026-08-13: both files `HTML document text`, build exit 0.
+#
+# That was invisible only because this image had never been built: `runs-on` named
+# a label no runner carries, so cpu/cuda/openvino queued until GitHub's 24h
+# auto-cancel and ECR holds zero `latest`/`cuda`/`openvino` tags, ever. Fixing the
+# runner label without this change would have published corrupt models under
+# `:latest` — the default tag customers pull — on the very first successful build.
+#
+# Shipping model-free is the documented and verified-supported state: ONNX loads
+# are wrapped, a missing file marks the camera/microphone subsystem ERROR and the
+# agent continues (deploy/docker/README.md). It is also strictly better than the
+# HTML it replaces — for audio, EdgeAgent only wires the classifier when the file
+# EXISTS, so an absent file cleanly skips it while a 2490-byte HTML file loads,
+# throws `Protobuf parsing failed`, and reports ERROR.
+#
+# To add models back, provision a real origin first, then restore a download that
+# validates the ONNX magic bytes — never a size floor, which cannot tell a model
+# from a web page. `trillboards-edge download-models` now refuses non-ONNX bytes.
 
 # Environment variables with defaults
 ENV NODE_ENV=production

package/deploy/docker/Dockerfile.cuda

@@ -1,6 +1,6 @@
 # Trillboards Edge AI SDK — NVIDIA CUDA container
 # Usage: docker build -f Dockerfile.cuda -t trillboards/edge-sdk:cuda ../../
-# Run:   docker run --gpus all -e DEVICE_TOKEN=xxx trillboards/edge-sdk:cuda
+# Run:   docker run --gpus all -e DEVICE_TOKEN=xxx ghcr.io/trillboards/edge-sdk:cuda
 
 FROM nvidia/cuda:12.3.2-runtime-ubuntu22.04 AS base
 
@@ -67,26 +67,35 @@ RUN npm ci --legacy-peer-deps --omit=dev 2>/dev/null || npm install --legacy-pee
 
 RUN mkdir -p /app/models /app/data
 
-# Download default models
-RUN node -e " \
-  const https = require('https'); \
-  const fs = require('fs'); \
-  const models = { \
-    'blazeface.onnx': 'https://models.trillboards.com/blazeface_128x128.onnx', \
-    'yamnet.onnx': 'https://models.trillboards.com/yamnet_classification.onnx', \
-  }; \
-  Object.entries(models).forEach(([name, url]) => { \
-    console.log('Downloading ' + name + '...'); \
-    const file = fs.createWriteStream('/app/models/' + name); \
-    https.get(url, (res) => { \
-      if (res.statusCode === 301 || res.statusCode === 302) { \
-        https.get(res.headers.location, (r) => r.pipe(file)); \
-      } else { \
-        res.pipe(file); \
-      } \
-    }); \
-  }); \
-" 2>/dev/null || echo "Model download skipped"
+# NO build-time model download. `models.trillboards.com` was never provisioned:
+# the trillboards.com zone has no `models` record, so the name is caught by the
+# `*.trillboards.com` wildcard A-alias and answered by the application ALB, which
+# returns the marketing SPA's index.html for every path. (An invented subdomain
+# resolves to the identical IPs — it is the wildcard, not a host.) No CloudFront
+# alias, no S3 bucket, no terraform for it has ever existed; the hostname was
+# invented in the same commit as the downloader (#996, 2026-03-09).
+#
+# The download this replaces verified only `if (size < 1000)`, and the SPA response
+# is 2490 bytes — so it PASSED, printed "All models downloaded successfully", and
+# baked two copies of a web page into the image as blazeface.onnx and yamnet.onnx.
+# Reproduced verbatim on 2026-08-13: both files `HTML document text`, build exit 0.
+#
+# That was invisible only because this image had never been built: `runs-on` named
+# a label no runner carries, so cpu/cuda/openvino queued until GitHub's 24h
+# auto-cancel and ECR holds zero `latest`/`cuda`/`openvino` tags, ever. Fixing the
+# runner label without this change would have published corrupt models under
+# `:latest` — the default tag customers pull — on the very first successful build.
+#
+# Shipping model-free is the documented and verified-supported state: ONNX loads
+# are wrapped, a missing file marks the camera/microphone subsystem ERROR and the
+# agent continues (deploy/docker/README.md). It is also strictly better than the
+# HTML it replaces — for audio, EdgeAgent only wires the classifier when the file
+# EXISTS, so an absent file cleanly skips it while a 2490-byte HTML file loads,
+# throws `Protobuf parsing failed`, and reports ERROR.
+#
+# To add models back, provision a real origin first, then restore a download that
+# validates the ONNX magic bytes — never a size floor, which cannot tell a model
+# from a web page. `trillboards-edge download-models` now refuses non-ONNX bytes.
 
 ENV NODE_ENV=production
 ENV DEVICE_TOKEN=""

package/deploy/docker/Dockerfile.openvino

@@ -1,6 +1,6 @@
 # Trillboards Edge AI SDK — Intel OpenVINO container
 # Usage: docker build -f Dockerfile.openvino -t trillboards/edge-sdk:openvino ../../
-# Run:   docker run -e DEVICE_TOKEN=xxx trillboards/edge-sdk:openvino
+# Run:   docker run -e DEVICE_TOKEN=xxx ghcr.io/trillboards/edge-sdk:openvino
 # Optimized for Intel HD 620+ GPUs (Backpackster, NUC, mini-PCs)
 
 FROM openvino/ubuntu22_runtime:2024.0.0 AS base
@@ -68,25 +68,35 @@ RUN npm ci --legacy-peer-deps --omit=dev 2>/dev/null || npm install --legacy-pee
 
 RUN mkdir -p /app/models /app/data
 
-RUN node -e " \
-  const https = require('https'); \
-  const fs = require('fs'); \
-  const models = { \
-    'blazeface.onnx': 'https://models.trillboards.com/blazeface_128x128.onnx', \
-    'yamnet.onnx': 'https://models.trillboards.com/yamnet_classification.onnx', \
-  }; \
-  Object.entries(models).forEach(([name, url]) => { \
-    console.log('Downloading ' + name + '...'); \
-    const file = fs.createWriteStream('/app/models/' + name); \
-    https.get(url, (res) => { \
-      if (res.statusCode === 301 || res.statusCode === 302) { \
-        https.get(res.headers.location, (r) => r.pipe(file)); \
-      } else { \
-        res.pipe(file); \
-      } \
-    }); \
-  }); \
-" 2>/dev/null || echo "Model download skipped"
+# NO build-time model download. `models.trillboards.com` was never provisioned:
+# the trillboards.com zone has no `models` record, so the name is caught by the
+# `*.trillboards.com` wildcard A-alias and answered by the application ALB, which
+# returns the marketing SPA's index.html for every path. (An invented subdomain
+# resolves to the identical IPs — it is the wildcard, not a host.) No CloudFront
+# alias, no S3 bucket, no terraform for it has ever existed; the hostname was
+# invented in the same commit as the downloader (#996, 2026-03-09).
+#
+# The download this replaces verified only `if (size < 1000)`, and the SPA response
+# is 2490 bytes — so it PASSED, printed "All models downloaded successfully", and
+# baked two copies of a web page into the image as blazeface.onnx and yamnet.onnx.
+# Reproduced verbatim on 2026-08-13: both files `HTML document text`, build exit 0.
+#
+# That was invisible only because this image had never been built: `runs-on` named
+# a label no runner carries, so cpu/cuda/openvino queued until GitHub's 24h
+# auto-cancel and ECR holds zero `latest`/`cuda`/`openvino` tags, ever. Fixing the
+# runner label without this change would have published corrupt models under
+# `:latest` — the default tag customers pull — on the very first successful build.
+#
+# Shipping model-free is the documented and verified-supported state: ONNX loads
+# are wrapped, a missing file marks the camera/microphone subsystem ERROR and the
+# agent continues (deploy/docker/README.md). It is also strictly better than the
+# HTML it replaces — for audio, EdgeAgent only wires the classifier when the file
+# EXISTS, so an absent file cleanly skips it while a 2490-byte HTML file loads,
+# throws `Protobuf parsing failed`, and reports ERROR.
+#
+# To add models back, provision a real origin first, then restore a download that
+# validates the ONNX magic bytes — never a size floor, which cannot tell a model
+# from a web page. `trillboards-edge download-models` now refuses non-ONNX bytes.
 
 ENV NODE_ENV=production
 ENV DEVICE_TOKEN=""

package/deploy/docker/README.md

@@ -179,14 +179,19 @@ Two directories should be persisted across container restarts:
 | `/app/models` | ONNX model files | `blazeface.onnx`, `yamnet.onnx`, and any OTA-updated models |
 | `/app/data` | Agent persistent state | `signal_buffer.db` (SQLite signal buffer), device identity fingerprint, federated learning gradients |
 
-Default models (`blazeface.onnx` and `yamnet.onnx`) are downloaded at image build time from `https://models.trillboards.com/`. If you mount an empty volume, the agent will operate without models until they are downloaded or placed manually.
+**These images ship with NO bundled ONNX models.** `/app/models` is created empty.
 
-**Pre-populating models on the host:**
+They used to claim a build-time download from `https://models.trillboards.com/`, but that host was never provisioned: `trillboards.com` has no `models` DNS record, so the name is caught by the `*.trillboards.com` wildcard and answered by the application load balancer, which returns the marketing site's `index.html` — HTTP 200, `text/html`, 2490 bytes — for every path. The build's only integrity check was `if (size < 1000)`, which 2490 clears, so the download "succeeded" and wrote a web page into `blazeface.onnx`. That was never noticed because these three images had never been built at all (their `runs-on` named a label no runner carries, so every run queued until GitHub's 24h auto-cancel).
+
+Running without these models is a supported state: the ONNX load is wrapped, and a missing model marks the camera/microphone subsystem `ERROR` while the agent keeps running. Face detection and audio classification are unavailable until you supply the files.
+
+**Supplying models on the host:**
+
+Place `blazeface.onnx` (BlazeFace 128×128) and `yamnet.onnx` (YAMNet classification) in a directory and bind-mount it. `trillboards-edge download-models` and `scripts/download-models.sh` will fetch them once a real origin is configured; both now verify the ONNX magic bytes and refuse — loudly, deleting the file — anything that is not a model, so they can no longer write an HTML error page and report `[OK]`.
 
 ```bash
 mkdir -p /opt/trillboards/models
-curl -o /opt/trillboards/models/blazeface.onnx https://models.trillboards.com/blazeface_128x128.onnx
-curl -o /opt/trillboards/models/yamnet.onnx https://models.trillboards.com/yamnet_classification.onnx
+# Copy blazeface.onnx and yamnet.onnx into /opt/trillboards/models
 ```
 
 Then mount as a bind volume:

package/deploy/docker/connector-entrypoint.sh

@@ -0,0 +1,122 @@
+#!/bin/sh
+# connector-entrypoint.sh — Docker entrypoint for the BYO-CCTV connector. On first
+# run it pairs with a short-lived claim code (exchanging it for a per-feed device
+# token, which is NEVER baked into the image) and writes the paired config;
+# 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 ──────────────────
+#
+# 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.
+#
+# 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 this image must also enable cloud FALLBACK ─────────────────────────
+#
+# `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.
+#
+# 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.
+#
+# TRILLBOARDS_SENSE_MODE overrides at run time: cloud-sense forces the cloud VLM,
+# local-sense refuses to fall back.
+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) ;;
+  *)
+    echo "[connector] Unknown TRILLBOARDS_SENSE_MODE '$MODE' (want auto-sense|cloud-sense|local-sense)." >&2
+    exit 1
+    ;;
+esac
+
+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
+    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
+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
+else
+  echo "[connector] Starting explicitly selected $MODE (API $API_BASE)..." >&2
+fi
+# shellcheck disable=SC2086
+exec $CLI "$MODE" --config "$CONFIG"

package/deploy/helm/README.md

@@ -450,7 +450,7 @@ kubectl label node <node-name> trillboards.com/edge-device=true
 ### 4. Customizing the kubectl Manifest
 
 Edit `daemonset.yaml` directly to change:
-- Image tag (line: `image: trillboards/edge-sdk:latest`)
+- Image tag (line: `image: ghcr.io/trillboards/edge-sdk:latest`)
 - Environment variable values
 - Resource requests and limits
 - Node selector labels

package/deploy/k8s/daemonset.yaml

@@ -37,7 +37,7 @@ spec:
       terminationGracePeriodSeconds: 30
       containers:
         - name: edge-agent
-          image: trillboards/edge-sdk:latest
+          image: ghcr.io/trillboards/edge-sdk:latest
           imagePullPolicy: Always
           ports:
             - name: status