About this article

• Audience: Operators SSHing into a Shadow RVC4 device to confirm host services, container runtime, and encoder health
• Goal: After reading, you can run a baseline diagnostic pass, interpret expected RVC4 service names, and fix the most common host-level failures
• Type: Troubleshooting / Reference

Summary

Shadow RVC4 devices run oak-agent on Yocto—not legacy depthai-server or luxonis-camera units. A healthy shadow shows oak-agent active, an oakapp container in runc, and encoder processes inside that container. Start with proxy health (PHANTOM_PROXY:8788), then SSH when the fleet view is inconclusive.

Prerequisites

• SSH: root@<device-ip> with YOUR_DEVICE_PASSWORD
• Proxy: export PHANTOM_PROXY=https://<phantom-proxy>:8788
• One shadow role label (site-role-a, site-role-b)

Baseline diagnostic pass

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

sshpass -p 'YOUR_DEVICE_PASSWORD' ssh root@<device-ip> \
  'systemctl status oak-agent; journalctl -u oak-agent -n 50 --no-pager; \
   runc --root /run/user/0/oak-agent/containers list; \
   ps aux | grep -E "ghost_core|ghost_agent|oak-agent" | grep -v grep'

Verify: oak-agent is active (running), runc list shows one container, and get_recording_status reports chunk growth or a justified stall reason.

Expected services on RVC4

Unit / process	RVC4 expectation
oak-agent.service	Host runtime; must be active
depthai-server.service	Not present — legacy name
luxonis-camera.service	Not present — superseded by oak-agent
ghost_core / ghost_agent_v2	Inside the oakapp container, not host systemd
runc root	/run/user/0/oak-agent/containers

sshpass -p 'YOUR_DEVICE_PASSWORD' ssh root@<device-ip> \
  'systemctl list-units --type=service --state=running; \
   ls /etc/systemd/system/*oak* /etc/systemd/system/*depthai* 2>/dev/null'

Symptom → cause → fix

Legacy service not found

Symptom: systemctl status depthai-server or luxonis-camera returns unit could not be found.

Cause: RVC4 images ship oak-agent and oakctl; older legacy unit names are not installed.

Fix: Inspect oak-agent and container state. Restart via proxy restart_app or oakctl app start — see Recovery.

oak-agent inactive (dead)

Symptom: oak-agent.service is inactive (dead); journal shows SIGINT/TERM; runc list is empty.

Cause: Manual stop, failed deploy, or reboot without the unit enabled. Stale unit files need daemon-reload.

Fix:

sshpass -p 'YOUR_DEVICE_PASSWORD' ssh root@<device-ip> \
  'systemctl daemon-reload; systemctl enable --now oak-agent; systemctl status oak-agent'

Start the oakapp or run unlock recovery if the camera proxy is wedged.

No encoder logs in host journal

Symptom: Host journal shows oak-agent MQTT/WebRTC lines only; no ghost_core or vision-pipeline kernel output.

Cause: Encoder and RF-DETR log inside the container; host journal captures oak-agent lifecycle only.

Fix:

sshpass -p 'YOUR_DEVICE_PASSWORD' ssh root@<device-ip> \
  'CID=$(runc --root /run/user/0/oak-agent/containers list -q | head -1); \
   runc --root /run/user/0/oak-agent/containers exec "$CID" \
     sh -c "ps aux | grep -E ghost_core|ghost_agent | grep -v grep"; \
   dmesg | tail -30; journalctl -k -n 50 --no-pager'

See Common issues if chunks stay flat.

Unit file changed on disk

Symptom: systemctl status warns the unit file or drop-ins changed on disk.

Cause: Deploy or edit updated /etc/systemd/system/oak-agent.service without reloading systemd.

Fix: systemctl daemon-reload && systemctl restart oak-agent. Re-probe fleet health before resuming soak.

Healthy signals (quick reference)

Check	Healthy signal
oak-agent	Active: active (running)
runc list	One container, state running
get_recording_status	recent_chunks ≥ 1 or justified stall
/fleet/mqtt/latest	~10 Hz telemetry; low stale_sec

Next steps

• Common issues — encoder stall, disk, thermal, MQTT stale
• Recovery — restart, power cycle, unlock, re-deploy
• Monitoring — proxy-first observability

Operator depth

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