About this article

• Audience: Operators deploying or updating a shadow after onboarding
• Goal: After reading, you can run a durable oakapp deploy, apply Edge AI layers, push models, and verify through the Phantom proxy
• Type: How-to

Summary

Deploy the sovereign VMS stack as an oakapp container: build on device, install the package, start the app, then layer configuration and models as needed. Always verify registry, MQTT, and recording status through PHANTOM_PROXY before longer soaks or promoting shadow-secondary.

Prerequisites

• SSH access: root@<device-ip> with YOUR_DEVICE_PASSWORD
• Phantom proxy: export PHANTOM_PROXY=https://<phantom-proxy>:8788
• Scripts in [repo-root]/oak-vms-firmware/: deploy_oakapp.sh, apply_depthai_v3_layer.sh, push_device_models.sh
• One shadow targeted (start with shadow-canary / site-role-a)

Why oakapp (not dev mode)

The C++ core and Python agent run inside a native oakapp container, isolated from the host Yocto image. The host exposes the camera through depthai-device-rvc4; the container talks to that proxy instead of bare metal.

Do not use oakctl app run . (dev mode) on fleet devices. It races with the host proxy and often produces Device in Use errors. Use the build → install → start lifecycle instead.

Model bundling:

• Small models (RF-DETR): place under oak-vms-firmware/models/ before build; oakctl bakes them into the image at /app/models/
• Large models and recordings: use runtime /app-storage and /data/models on the device (no extra mount tables on these devices)

1. Full sovereign deploy

From [repo-root]/oak-vms-firmware/:

./scripts/deploy_oakapp.sh <device-ip> YOUR_DEVICE_PASSWORD

The deploy script performs four phases:

1. Unlock camera — stop conflicting processes, clear orphaned containers and IPC sockets, restart oak-agent so the Edge AI device proxy is ready (process/IPC orphans — not the same as past-retention video chunk orphans; see Specter orphans purge for storage hygiene demos)
2. Sync source — rsync the firmware tree to the device develop path (current oakapp.toml and sources)
3. Build and install — oakctl app build on device, then oakctl app install with the new .oakapp package
4. Start — oakctl app start for the Ghost Protocol VMS app ID

After start, the entrypoint launches ghost_core, the A2A server (port 8765), and ghost_agent_v2 inside container isolation. Further device checks use SSH and the proxy—not repeated oakctl operations on a running fleet shadow.

Durable vs hot-patch

Overlay edits to a running container are ephemeral. For entrypoint, tracker env, or layer loader changes, prefer a full deploy and device-side build—not copying files into merged overlay paths.

2. Apply Edge AI layers

Layers stack cumulative capabilities from encode-only through full perception. Apply with restart so the entrypoint reloads env:

APPLY_RESTART=1 ./scripts/apply_depthai_v3_layer.sh layer2_tracker <device-ip> YOUR_DEVICE_PASSWORD
APPLY_RESTART=1 ./scripts/apply_depthai_v3_layer.sh layer3_depth <device-ip> YOUR_DEVICE_PASSWORD

Layer	Name	Adds
layer0	baseline	Encode-only
layer1	rfdetr	RF-DETR detection
layer2	tracker	Object tracker (default canary baseline)
layer3	depth	Monocular depth
layer4	thermal	Thermal governor
layer5 / full	full	All layers

The apply script merges layer0…N into depthai_v3_layer.env on the device (/app-storage/config/ and /data/config/). The entrypoint loads that file on start and enables tracker, RF-DETR, and mono depth when paths and flags are present.

See Layer3 depth and fusion for depth-specific env and promote gates.

3. Push device models

Large .dlc files that are not baked into the image ship separately:

./scripts/push_device_models.sh <device-ip> YOUR_DEVICE_PASSWORD

This creates /data/models/ on the shadow and copies RF-DETR and optional monocular depth weights. Push models before applying layer3_depth when env points at /data/models/.

4. Post-deploy verification

Re-probe live state through the proxy before soaks or promotion:

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

Verify:

• Registry lists your shadow role and bus membership
• MQTT latest includes the device with die_temp and detections
• Recording status reports acceptable storage_health and is_writing_data

Inside the container (SSH + runc exec or logs): confirm core and agent processes, then curl localhost:8765/a2a/query for live detections. Full proxy routes are in API quick reference.

Deploy flow

Troubleshooting

No available devices: A host process still holds the camera lock. Re-run deploy_oakapp.sh (it runs unlock first). Do not kill -9 the depthai-device-rvc4 proxy.

Storage CRITICAL after deploy: Prune oldest H.265 chunks before soak gates. See prune and storage.

Next steps

• First operator tasks — contract verification and short soak
• Soaks and automation — orchestrator with --layer layer3_depth
• Fleet status — promote shadow-secondary after canary passes
• USB extended storage — external recording relief

Operator depth

Live bake IDs, layer state, soak gates, and harness evidence live in private operator handoff (not published) (private).