About this article

• Audience: Operators and integrators who need the cross-cutting policies behind soak gates, durable recording, extensions, and fleet security
• Goal: Understand how thermal limits, storage tiers, the plugin model, and zero-trust boundaries work together on sovereign edge shadows
• Type: Concept

Summary

Ghost Protocol edge shadows protect the camera pipeline under heat, keep justified recording durable across internal and external storage, load optional plugins through the edge app bundle, and enforce zero-trust authentication between devices, peers, and the central proxy. These policies sit beneath the tiered model in architecture overview and explain why soak gates fail or pass.

Prerequisites

• Architecture overview — edge, proxy, and cloud tiers
• Justified recording contract — chunk and sidecar expectations
• Phantom proxy reachable at https://<phantom-proxy>:8788
• SSH access to a shadow: root@<device-ip> with YOUR_DEVICE_PASSWORD

Thermal policy

The firmware treats sustained high die temperature as a threat to encoder stability and soak reliability.

• Suspend threshold: When die temperature reaches 85°C, ghost_core and entrypoint call suspend_ai() — AI inference pauses while the camera and H.265 encoder keep running. The agent publishes a THERMAL_CRITICAL MQTT event.
• Safe operating band: Soak gates expect skin temperature below 55°C and die temperature below 78°C during sustained recording. Mitigations include process priority tuning, background recovery schedulers, and SELinux label fixes for FIFO paths when policy denials appear in dmesg.
• Verification: Read SoC thermal zones over SSH, run soak_gate.sh for gate scripts, and check /fleet/mqtt/latest on the proxy for live die_temp telemetry.

Thermal soak criteria and mitigation runbooks are detailed in operator guides — not duplicated here.

Storage durability

Internal overlay storage on high-churn shadows often enters CRITICAL health (very low free space, high used percentage) while chunks continue to grow. That state blocks soak automation until space is reclaimed.

State	Typical signal	Operator response
CRITICAL	Few hundred MB free, soak blocked	Prune oldest chunks, then restart the app
WARNING	Several GB free after prune	Monitor; plan external storage if churn resumes
OK	Stable free space, is_writing_data true	Proceed with soak gates

Storage roots: Recordings land under /app-storage/recordings (overlay-backed) or /data/ext-recordings when external USB is mounted. entrypoint can symlink the active path so ghost_agent_v2 writes to the durable volume. Overlay views can lag after prune — confirm with SSH df and runc inspection, not proxy alone.

Prune and soak: The orchestrator supports --prune-first so disk relief runs before long soaks. Prune scripts delete oldest chunk_*.h265 files and sidecars while keeping a configurable retention window. See prune and soak gates.

External USB: For shadows that outgrow internal capacity, mount a USB SSD on the host, apply udev rules, and redirect recordings. See USB extended storage.

Plugin system

Optional capabilities ship as plugins loaded through edge app bundle layers or baked images. Common families include CAN bus controllers, Wi-Fi managers, VAPIX integrations, and NIST-style face recognition modules.

• Load path: Plugins register at agent extension points. Neural network and object-tracker hooks fall back to host-side execution when an NPU path is unavailable.
• Testing: The plugin test harness runs inside the sovereign container via runc exec.
• Examples: Reference implementations live under oak-examples/ (streaming, neural networks, integrations, custom frontends).
• Authoring: See plugins and examples for structure and env conventions.

Plugins extend behavior without breaking the sovereign rule: cloud API keys stay on the proxy, not in the edge image.

Zero-trust security

Fleet communication assumes no implicit trust between processes, devices, or sites.

Hermes peer mesh

Shadows discover peers over UDP broadcast with HMAC-authenticated announcements. A dedicated mTLS sidecar supports direct peer queries on each device. Cross-site visibility aggregates at the proxy through /fleet/registry. The mesh is internal to the fleet — it is not exposed to the public internet.

A2A and MCP on the edge

Port 8765 serves signed A2A queries and MCP tool calls. Requests require HMAC-SHA256 signatures using a device-configured secret (never a baked default in production). Rate limits and input sanitization apply. When the on-device LLM is offline, responses still return authoritative precomp RF-DETR counts with explicit freshness notes.

Proxy central

The Phantom proxy at https://<phantom-proxy>:8788 is the back end for fleet visibility. It ingests MQTT, forwards MCP calls, pulls recordings over SSH when needed, and executes allowlisted playbooks. Devices do not hold cloud API keys — the proxy remains sovereign for escalation.

Container isolation and compliance

Production firmware runs inside edge app bundle containers, not on bare metal. Peer certificates are provisioned per device with restrictive file permissions. Security posture aligns with OWASP, NIST AI RMF, and internal zero-trust checklists verified through the test harness.

Next steps

• Architecture diagrams — ports, protocols, and component relationships
• Prune and soak gates — recover from CRITICAL storage
• USB extended storage — mount durable recording volumes
• Plugins and examples — author and test extensions
• API reference — proxy and MCP endpoint lookup

Operator depth

Live fleet state, thermal soak percentages, harness evidence, and session chronology live in private operator handoff (not published).