Phantom Vision VMS / Ghost Protocol

Appearance

About this article ​

  • Audience: Operators who run the Phantom Vision stack on the host workstation
  • Goal: After reading, you can start and stop the proxy stack, run readiness checks, and tie host services to on-demand VMS work
  • Type: How-to

Summary ​

The Phantom stack (cost-sentinel) runs the proxy, MQTT broker, and optional UI. Keep it down by default for cost control; bring it up only when you need fleet visibility, soak automation, or Phantom readiness gates. The proxy at PHANTOM_PROXY is the central surface for registry, MQTT cache, MCP forwards, and playbook execution.

For COTA POC desk BOM, ports table, and Mac Studio install checklist, see Host materials — Mac Studio and COTA VMS host.

Prerequisites ​

  • Repo checkout at [repo-root] with cost-sentinel installed
  • export PHANTOM_PROXY=https://<phantom-proxy>:8788
  • At least one shadow registered (site-role-a / site-role-b)
  • API quick reference for curl templates

1. Default: stack down (idle) ​

Stop proxy and MQTT when you are not doing VMS work:

bash
cd [repo-root]/cost-sentinel
npm run stack:down
# or: bash scripts/phantom-vision-stack.sh down

Verify idle ports:

bash
lsof -i :8788 -i :1883 2>/dev/null || echo "stack idle"

The UI may still run (npm run dev); it shows stack down and blocks fleet actions until you start the stack again.

2. Activate: stack up ​

Start proxy and MQTT before any fleet or soak work:

bash
cd [repo-root]/cost-sentinel
npm run stack:up
npm run stack:status   # expect proxy + MQTT healthy

Or use the UI Setup Wizard → Start stack.

With the stack up:

  • MQTT devices/+/events/incident can trigger automatic H.265 pulls
  • The UI merges playback state via GET /fleet/playback-ready
  • The proxy owns registry, /fleet/mqtt/latest, /tools/call, /a2a/query, and readiness routes

3. Probe fleet through the proxy ​

Confirm shadows are visible before readiness or soak runs:

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

Healthy signals: telemetry near 10 Hz, track_id in detections when people are present, and storage_health not CRITICAL. Full route catalog: API quick reference.

4. Phantom readiness gate ​

Run the interleaved readiness agent after stack up and before long automation:

bash
cd [repo-root]
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]/readiness-report.md

For layer3 depth work, add gemini_video_understanding and video_intelligence_annotate to --modules. Transient FAILs right after a layer apply are common—re-probe after the container stabilizes.

Proxy equivalents:

bash
curl -s "$PHANTOM_PROXY/fleet/readiness" | jq .
curl -s -X POST "$PHANTOM_PROXY/fleet/readiness/remediate" \
  -H "Content-Type: application/json" \
  -d '{"playbook":"h265_stall"}'

Approved playbooks include h265_stall, disk_critical, and fleet onboarding flows under cost-sentinel/phantom-agents/playbooks/.

5. Provision and registry ​

Register or refresh shadows through the proxy:

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

Validate cross-shadow bus visibility in /fleet/registry before soak batches.

6. Storage guard and prune ​

Before long soaks, confirm recording headroom. If storage_health is CRITICAL, prune first:

bash
DRY_RUN=1 KEEP_CHUNKS=30 bash cost-sentinel/scripts/shadow-prune-recordings.sh
KEEP_CHUNKS=30 bash cost-sentinel/scripts/shadow-prune-recordings.sh

See Updates, prune & storage for full prune and soak-gate sequence.

7. On-demand VMS pattern ​

Run the stack only when doing VMS work—tests, soak visuals, or Phantom 5-minute gates. Default down between sessions. After a firmware or layer deploy, re-run readiness and a short soak before batch automation.

Typical sequence: stack up → readiness → optional prune → soak or batch → stack down. See Soaks & automation.

Troubleshooting ​

Stack up twice: Idempotent—no duplicate MQTT listeners.

Proxy unreachable: Re-run npm run stack:up, then probe /health via API quick reference.

Readiness critical: Start MQTT stack, verify SSH to shadows, provision registry entries.

Full device recovery: See Recovery and VMS on demand.

Next steps ​

Operator depth ​

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