About this article

• Audience: Contributors setting up a local Ghost Protocol firmware and docs workspace
• Goal: After reading, you can install dependencies, build the docs hub, deploy to a shadow, and start the Phantom stack for integration work
• Type: How-to

Summary

Ghost Protocol development spans edge firmware (oak-vms-firmware), the Phantom Vision host stack (cost-sentinel), and a VitePress docs hub. Pin Node 20–22 for docs builds, use placeholder credentials in all examples, and keep the Phantom stack down unless you are actively testing fleet or soak flows.

Prerequisites

• macOS or Linux workstation with Git, Python 3, and Node.js 22 (see .nvmrc in docs/)
• SSH access to a Shadow 1 device at <device-ip> with YOUR_DEVICE_PASSWORD
• Repo clone at [repo-root]
• Requirements and DEV_ENVIRONMENT.md for hardware standards

1. Repository layout

Path	Role
oak-vms-firmware/src/	Edge firmware (ghost_core, agent, MCP server, entrypoint)
oak-vms-firmware/scripts/	Deploy, soak, verify, and automation helpers
oak-vms-firmware/tools/	Orchestrator, readiness agent, Hermes controller
oak-vms-firmware/docs/	VitePress public docs hub (this site)
cost-sentinel/	Phantom proxy, MQTT broker, playbooks, e2e tests
oak-examples/	Edge AI authoring catalog

Firmware targets Shadow 1 with A/B OTA updates, MQTT telemetry, and strict thermal management during soak gates.

2. Build the docs hub

VitePress requires Node 20–22. Newer Node versions break ESM interop with the pinned VitePress release.

cd [repo-root]/oak-vms-firmware/docs
nvm use 22          # or: n 22
npm ci
bash build.sh       # checks Node major, then npm run docs:build

Local preview:

npm run docs:dev

The build wrapper aborts with a clear message if Node is outside the supported range. Static output lands in docs/.vitepress/dist/ for deployment behind a /docs/ base path.

3. Deploy firmware to a shadow

Use the deploy script with SSH placeholders—never commit real passwords:

cd [repo-root]/oak-vms-firmware
./scripts/deploy_oakapp.sh

See DEPLOYMENT.md for bake vs overlay workflows. Prefer runc and on-device paths documented there; avoid post-deploy oakctl steps that drift a sovereign bake.

SSH sanity check:

sshpass -p 'YOUR_DEVICE_PASSWORD' ssh root@<device-ip> 'oakctl device status'

4. Start the Phantom stack for integration

Fleet probes, soak automation, and Playwright e2e expect the host stack up:

export PHANTOM_PROXY=https://<phantom-proxy>:8788
cd [repo-root]/cost-sentinel
npm run stack:up
npm run stack:status

Stop the stack when finished to avoid background MQTT and proxy work:

npm run stack:down

Full operator flow: Host and Phantom stack.

5. AI-assisted workflow (optional)

Many contributors use an IDE agent with separate plan and act modes: a reasoning model for architecture and hardware debugging, and a fast execution model for edits and terminal commands. Point the agent at REQUIREMENTS.md and DEV_ENVIRONMENT.md in its system context. Reserve plan mode for ambiguous, high-impact changes; use act mode for routine fixes that follow existing patterns.

Use library documentation tools when integrating third-party APIs. Prefer local repo search and grep over remote repo browsing when source is already checked out.

6. Verify before you commit

• Docs: bash build.sh from oak-vms-firmware/docs
• Quick fleet probe (stack up): curl -s "$PHANTOM_PROXY/fleet/health" | jq .
• Short soak smoke: see Testing

Next steps

• Run verification layers: Testing
• Docs and release hygiene: Release and docs maintenance
• First operator tasks: First tasks

Operator depth

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