About this article

• Audience: Contributors and integrators who name shadows, MQTT topics, hostnames, or API surfaces
• Goal: After reading, you can pick canonical Ghost Protocol names and avoid drift across firmware, proxy, and docs
• Type: Reference

Summary

Ghost Protocol uses Shadow as the single product name for edge agents, MQTT namespaces, public UI hostnames, and proxy workers. Fleet members are identified by logical site roles and stable MQTT device_id values—not physical location labels or personal nicknames.

Prerequisites

• Architecture overview for tier context
• MQTT reference for topic schemas
• Glossary for first-use jargon

Shadow-only naming

Edge agents, MQTT mirror namespaces, public hostnames, and Cloudflare Worker names all use Shadow. Do not introduce alternate product names for the Shadow fleet or edge agent role.

Concept	Canonical name
Shadow 1 edge agent	Shadow Device
MQTT mirror namespace	shadow/{device_id}/… (alongside devices/{device_id}/…)
Public UI hostname	shadow.ghostprotocol.us
Cloudflare Worker	shadow-proxy
Legacy cloud upload API	/api/shadow/*

Fleet identifiers

Use role labels in docs, scripts, and proxy queries. Reserve physical placement names for private operator handoff.

Role label	MQTT device_id	Typical use
site-role-a	shadow1	Canary shadow, first soak gate
site-role-b	shadow2	Secondary shadow, cross-site mesh tests

Device reachability uses <device-ip> on the lab LAN. The central proxy aggregates registry and MQTT at https://<phantom-proxy>:8788.

Interfaces and ports

Layer	Port / path	Notes
Shadow MCP (on device)	:8765	A2A tool surface; health and recording probes
Phantom VMS proxy (host)	:8788	Fleet registry, MQTT ingest, MCP forward
MQTT broker (lab)	:1883	Telemetry and status; WSS bridge optional
Hermes peer mesh	:11555	UDP discovery with HMAC
Peer sidecar	:8777	mTLS peer queries

Replace PHANTOM_PROXY with https://<phantom-proxy>:8788 in curl examples. SSH fallbacks prompt for YOUR_DEVICE_PASSWORD.

Topic and API conventions

• MQTT: Publish under devices/{device_id}/…; mirror read-only views under shadow/{device_id}/….
• Proxy: Target shadows with ?target=<device-ip> or ?shadow=site-role-a on playback routes.
• Containers: Sovereign oakapp images use ghost_core, ghost_agent_v2, and entrypoint service names—do not rename in public docs.

Anti-patterns

Avoid	Use instead
Physical site labels (door or cabin names)	site-role-a, site-role-b
Alternate agent names (Casper, Phantom Device)	Shadow Device
Hard-coded LAN IPs in docs	<device-ip>
Live UUIDs or soak percentages in prose	[operator-artifacts] or handoff

Next steps

• Wire names into deploy flow: Quickstart
• Confirm registry entries: API quick reference
• Full MQTT map: MQTT reference

Operator depth

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