Phantom Vision VMS / Ghost Protocol

Appearance

About this article ​

  • Audience: Contributors building Ghost Protocol edge firmware and running first deploys from a laptop
  • Goal: After reading, you can set up the repo layout, connect to a shadow, and follow the dev → test → prod loop safely
  • Type: How-to

Summary ​

Ghost Protocol edge development centers on [repo-root]/oak-vms-firmware: Edge AI v3 pipelines, MQTT telemetry, justified recording, and strict thermal guardrails on Shadow 1 hardware. Use placeholder credentials everywhere, SSH key auth where possible, and never push unverified builds straight to fleet shadows.

Prerequisites ​

  • macOS or Linux workstation with Git, Python 3, and optional Node 22 for docs builds
  • Shadow 1 reachable at <device-ip> with YOUR_DEVICE_PASSWORD
  • Requirements for thermal, memory, and encoding standards
  • Repo clone at [repo-root]

1. Repository layout ​

PathRole
src/ghost_core, ghost_agent_v2, MCP server, MQTT client, recorder
config/oakapp.toml, layer env files, .env.example
scripts/Deploy, soak gate, verify, and unlock helpers
tools/Orchestrator, readiness agent, VMS CLI
tests/Unit tests, hardware baseline, HITL stress
docs/VitePress public docs hub

Models ship separately; never commit API keys. Copy config/.env.example to a local .env ignored by Git.

2. Connect to a shadow ​

Exchange SSH keys before first deploy. Avoid plaintext passwords in scripts or docs.

bash
ssh-copy-id -i ~/.ssh/id_rsa_oak.pub root@<device-ip>
ssh root@<device-ip> 'oakctl device status'

Factory reset (destructive) returns the Shadow device OS to a known baseline:

bash
oakctl clear-flash
oakctl flash --os-version 1.30.1

Run destructive steps only on lab hardware—not fleet canaries.

3. Dev → test → prod loop ​

DEV (laptop) ​

Write pipeline logic and unit tests locally. Mock hardware where possible.

bash
cd [repo-root]/oak-vms-firmware
python3 -m pytest tests/ -q --tb=short -k "not hitl"

TEST (hardware-in-the-loop) ​

Push to the device overlay and run native stress checks. See HITL testing.

Pass criteria: DSP die temp stays below 75°C; RAM usage stays below 6 GB during the soak window defined in Requirements.

PROD (fleet deploy) ​

Use the sovereign deploy script—immutable oakapp bake, no ad-hoc oakctl drift after promote:

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

Tag images yyyymmdd-xxxx. Dockerfile and layer env files define the oakapp bake; entrypoint.sh starts recorder, sidecars, and peer mesh.

Confirm via proxy:

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

4. Optional AI-assisted workflow ​

Pair plan and act agent modes for architecture vs. fast edits. Keep REQUIREMENTS.md in system context. Full workstation setup (docs hub, Phantom stack, e2e): Development environment and building.

Next steps ​

Operator depth ​

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