About this article

• Audience: New operators joining a Ghost Protocol VMS fleet
• Goal: After reading, you understand the proxy + shadows + MQTT stack, meet prerequisites, and know where to deploy
• Type: How-to

Summary

Ghost Protocol runs a central Phantom Vision proxy on your operator host and Shadow edge cameras in the field. Shadows publish MQTT telemetry; the proxy aggregates fleet state, tooling, and cloud escalation. Learn the topology here, then follow the Quickstart to deploy.

COTA POC 2026: HIGHLY RECOMMENDED host is a Mac Studio — see Host materials and the COTA POC overview. Gemma stays host-only.

Stack overview

Component	Role	Port
MQTT broker	Shadow telemetry and health bus	1883
vms-proxy	Registry, MQTT tap, MCP forwarding	8788
shadow-canary	Primary canary (shadow1, site-role-a)	—
shadow-secondary	Secondary device (shadow2, site-role-b)	—

Shadows publish to devices/{device_id}/… on <phantom-proxy>:1883. The proxy exposes HTTP at PHANTOM_PROXY=https://<phantom-proxy>:8788.

Prerequisites

• Operator workstation on the shadow LAN (or VPN)
• Node.js and Docker (or native Mosquitto) for the Phantom host stack
• SSH: root@<device-ip> with YOUR_DEVICE_PASSWORD
• [repo-root]/oak-vms-firmware/ with deploy scripts and orchestrator tools

1. Start the Phantom host stack

cd [repo-root]
./phantom-vision-stack.sh up

Verify

export PHANTOM_PROXY=https://<phantom-proxy>:8788
curl -s "$PHANTOM_PROXY/fleet/registry" | jq .

• HTTP 200 with mqtt_host and proxy_port fields
• Shadows list populates after device deploy

2. Understand shadow roles

Role	MQTT ID	Camera label
shadow-canary	shadow1	site-role-a
shadow-secondary	shadow2	site-role-b

Deploy provisions phantom_vision_endpoint.json and cota_identity.json in /app-storage/config (or /data/config).

3. Deploy firmware to a shadow

Use a durable edge app bake — not overlay hotpatches:

cd [repo-root]/oak-vms-firmware
./scripts/deploy_oakapp.sh <device-ip> YOUR_DEVICE_PASSWORD

See Firmware deploy for layers and model push.

Verify

curl -s http://nexus.ghostprotocol.us:8788/fleet/registry | jq '.shadows'
curl -s http://nexus.ghostprotocol.us:8788/fleet/mqtt/latest | jq '.devices | keys'

• Shadow appears in registry with correct device_id and role
• MQTT latest includes the device within one telemetry cycle

4. Check fleet health before soaks

curl -s -X POST "$PHANTOM_PROXY/tools/call?target=<device-ip>" \
  -H "Content-Type: application/json" \
  -d '{"tool":"get_recording_status"}' | jq .

Prune first if storage_health is CRITICAL. See Prune and soak.

Verify

• storage_health is WARNING or OK
• is_writing_data is true when the scene has motion

Next steps

• Quickstart — deploy shadow-canary and pass a short soak gate
• First operator tasks — contract checks and Phantom readiness
• Fleet status — gate history and promotion readiness

Operator depth

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