About this article

• Audience: Operators running the Phantom stack, readiness gates, and fleet remediation playbooks
• Goal: After reading, you can start Cost Sentinel, run the 5-minute readiness wizard, and interpret Phantom agent results through the proxy
• Type: How-to

Summary

Phantom Vision ties together MQTT telemetry, the vms-proxy at PHANTOM_PROXY, and YAML playbooks that provision shadows, heal stalls, and grade fleet readiness. Cost Sentinel is the npm workspace that starts that stack. Run the readiness agent after stack:up to confirm broker, SSH, shadow provisioning, and proxy health before soaks or video-understanding modules.

Prerequisites

• Node.js 22+ and repo at [repo-root]
• Phantom proxy: export PHANTOM_PROXY=https://<phantom-proxy>:8788
• SSH to shadows with YOUR_DEVICE_PASSWORD
• API quick reference for fleet probes

1. Start the Phantom stack

From the Cost Sentinel workspace, bring up MQTT (port 1883), vms-proxy (port 8788), and related services:

cd [repo-root]/cost-sentinel
npm run stack:up

Confirm the proxy answers:

curl -s "$PHANTOM_PROXY/health" | jq .
curl -s "$PHANTOM_PROXY/fleet/registry" | jq .

The registry lists each shadow with role labels (site-role-a, site-role-b), bus membership, and LAN addresses. MQTT ingest should show recent telemetry on /fleet/mqtt/latest.

2. Run the 5-minute readiness wizard

The readiness agent walks fleet prerequisites and can execute safe remediations (stack restart, shadow provision, broker checks):

cd [repo-root]/oak-vms-firmware
python3 tools/phantom_vms_readiness_agent.py \
  --proxy-url "$PHANTOM_PROXY" \
  --hermes-validate \
  --execute-safe

Or trigger the same checks through the proxy:

curl -s "$PHANTOM_PROXY/fleet/readiness" | jq .

What it checks: MQTT stack, SSH reachability, shadow provisioning, broker on 1883, vms-proxy on 8788, phantom vision endpoint config, and COTA identity. With --hermes-validate, it also grades Hermes mesh and A2A federation across registered shadows.

Transient failures right after stack:up are normal—wait for MQTT ingest, then re-run. Critical failures (SSH down, broker absent, shadows unprovisioned) block soak and video modules until resolved.

3. Phantom playbooks and remediation

Playbooks under cost-sentinel/phantom-agents/playbooks/ describe fleet operations as YAML sections. Common sections:

Playbook	Responsibility
fleet-onboarding	Provision shadow manifests and camera label registry
fleet-health	Hermes integration and health probes
h265_stall	Encoder stall detection and restart
disk_critical	Storage CRITICAL self-heal (prune + verify)
setup-wizard	End-to-end readiness sequence

The proxy resolves and executes approved playbooks via /fleet/readiness/remediate. Hermes controller playbooks (h265_stall, disk_critical) support daemon execute-safe self-heal across the fleet when storage or encoder gates fail.

Example provision flow through the proxy:

curl -s -X POST "$PHANTOM_PROXY/fleet/provision-shadow" \
  -H "Content-Type: application/json" \
  -d '{"restart": true}' | jq .

curl -s -X POST "$PHANTOM_PROXY/fleet/validate" | jq .

4. Wire readiness into soaks

Interleave Phantom modules with orchestrator soaks for a single 5-minute gate. Typical module set:

python3 tools/phantom_vms_readiness_agent.py \
  --proxy-url "$PHANTOM_PROXY" \
  --hermes-validate \
  --modules device_identity_fp,peer_sidecar,hermes_mesh,mcp_health,cross_a2a_federation,depth_fusion \
  --tap --report [operator-artifacts]/phantom-readiness.md

Add gemini_video_understanding and video_intelligence_annotate when exercising cloud video on justified clips—see Video understanding.

The orchestrator can call run_phantom_unit_gate before and after layer probes. Layer3 post-soak reports list the playbook DAG and any transient readiness FAILs; harness evidence lands under test-results/v3-runs/.

5. Key surfaces and evidence

Surface	What to look for
/fleet/mqtt/latest	~10 Hz telemetry, track_id in detections, die_temp, stale_sec
/tools/call → get_recording_status	storage_health, chunk inventory, justified latest
/fleet/readiness	Module grades and remediation hints
Readiness TAP report	Per-module PASS/FAIL with recommended CLI fixes

Phantom Vision contract: H.265 60-second chunks, MQTT near 10 Hz, thermal policy enforcement, and track_id in detection payloads. USB extended storage and prune policy integrate through disk_critical and fleet-health playbooks—see USB extended storage.

Next steps

• API quick reference — curl catalog for fleet, MQTT, and tools
• Monitoring — TAP logs, debug ring, and checkpoint artifacts
• Soaks & automation — orchestrator batch matrix with --hermes
• Layer3 depth & fusion — depth_fusion module in readiness gates

Operator depth

Live fleet state and harness evidence live in private operator handoff (not published) (private).