Platform Communication & Mesh Networking
plexd communicates with the Plexsphere control plane through four outbound-only HTTPS channels: registration, SSE event streaming, heartbeat, and reconciliation. No inbound ports or public IPs are required on the node side.
Between nodes, plexd forms an encrypted WireGuard mesh for direct peer-to-peer traffic. The control plane coordinates key exchange and peer discovery but never sits in the data path — all mesh traffic flows directly between nodes.
How plexd Communicates with Plexsphere
All communication is initiated by the node. The control plane never connects inbound to a node.
Channel Summary
| Channel | Direction | Protocol | Frequency | Purpose |
|---|---|---|---|---|
| Registration | Node → CP | HTTPS POST | Once | Bootstrap identity, receive keys and peers |
| SSE Stream | Node ← CP | HTTPS SSE | Persistent | Real-time peer, policy, action, and key events |
| Heartbeat | Node → CP | HTTPS POST | Every 30s | Liveness, status reporting, reconcile/rotate hints |
| Reconciliation | Node → CP | HTTPS GET | Every 60s | State consistency fallback; pulls the desired-state snapshot and the queued action dispatches |
| Observability | Node → CP | HTTPS POST | Periodic | Metrics, logs, and audit event uploads |
The SSE stream is the primary real-time channel. Reconciliation acts as a consistency fallback — if an SSE event is missed, the next reconciliation cycle detects and corrects the drift. Action dispatches are the one payload that never rides the event stream at all: they are delivered in the executions block of the reconciliation pull, and the matching action_request event merely pulls the next cycle forward. See Heartbeat Service and Reconciliation for protocol details.
Node Lifecycle
A node progresses through four phases from first boot to shutdown.
See Agent Lifecycle for the full startup sequence and shutdown details.
The Encrypted Mesh Network
Nodes form a full-mesh WireGuard network in the 10.100.0.0/16 address space. Each node gets a unique /32 mesh IP at registration. The control plane distributes public keys and pre-shared keys but never handles mesh traffic.
Key properties of the mesh:
- Outbound-only — nodes initiate all connections. No inbound ports required.
- NAT traversal — nodes behind NAT use STUN to discover their public endpoint and exchange it via the control plane. See NAT Traversal.
- Relay fallback — when direct P2P is not possible, traffic is relayed through a bridge node. See NAT Relay.
- Per-peer PSKs — each peer pair has a unique pre-shared key for post-quantum forward secrecy.
- Network policy — the control plane pushes visibility rules that control which peers can communicate. See Network Policy.
What the Mesh Enables
Core Capabilities (all nodes)
| Capability | Description | Reference |
|---|---|---|
| P2P Communication | Direct encrypted WireGuard tunnels between all peers | WireGuard Tunnels |
| NAT Traversal | STUN-based public endpoint discovery and exchange | NAT Traversal |
| Network Policy | Peer visibility rules enforced via the host firewall (nftables, pf or WFP) | Network Policy |
| Secure Tunnels | SSH-based access to services through the mesh | Secure Access Tunneling |
| Remote Actions | Execute built-in and hook-based actions dispatched in the state pull | Remote Actions & Hooks |
| Observability | Metrics, logs, and audit event forwarding | Metrics, Logs, Audit |
Bridge-Only Capabilities
| Capability | Description | Reference |
|---|---|---|
| NAT Relay | UDP relay for peers that cannot establish direct P2P | NAT Relay |
| Public Ingress | ACME certificate management and SNI-based routing | Public Ingress, ACME & SNI |
| User Access | Integration with Tailscale, Netbird, or standalone WireGuard | User Access |
| Site-to-Site VPN | Connect partner or customer networks to the mesh | Site-to-Site VPN |
See Also
- Architecture — detailed ASCII diagrams, platform support, mesh topology
- Agent Lifecycle — full startup sequence, operational behavior, deregistration
- Security & Trust Model — key exchange, trust chain, threat model, network requirements
- Agent Internals — subsystem overview, goroutine map, shutdown sequence
- Control Plane Client — HTTP client implementation details
- Registration — bootstrap authentication and identity persistence