plexd

Appearance

Plexsphere Node Agent Documentation ​

DeepWiki

Capabilities ​

The Plexsphere node agent (plexd) is a lightweight daemon that runs on every managed node. It handles:

  • Registration — self-registers with the control plane using a bootstrap token
  • WireGuard Mesh — creates and manages WireGuard interfaces and encrypted peer tunnels
  • NAT Traversal — discovers public endpoints via STUN and exchanges them with peers
  • Network Policy — enforces peer visibility rules and firewall policies via nftables
  • Secure Tunneling — provides SSH-based secure access tunnels through the mesh
  • State Reconciliation — periodically fetches desired state and applies drift corrections
  • Remote Actions — executes built-in and hook-based actions requested via SSE events
  • Observability — collects and forwards metrics, logs, and audit events to the control plane
  • Local Node API — exposes node state (metadata, data, secrets) to local workloads via Unix socket API or PlexdNodeState CRD
  • Integrity — verifies checksums of the plexd binary and hook scripts
  • Bridge Mode — optional gateway mode with NAT relay, public ingress, user access, and site-to-site VPN

Operating Modes ​

ModeStatusDescription
nodeActiveDefault mode. Runs all core subsystems.
bridgeActiveExtends node mode with bridge-specific subsystems (relay, ingress, user access, site-to-site). Enabled when mode: bridge and bridge.enabled: true.

High-Level Overview ​

The diagram below shows the three layers of a plexd deployment: the central control plane, the managed nodes, and the external access provided by bridge nodes.

                              ┌───────────────────────┐
                              │  Plexsphere           │
                              │  Control Plane        │
                              └───────────┬───────────┘
                                          │
                            HTTPS + SSE (outbound only)
                                          │
       ┌──────────────┬───────────────────┼──────────────────┬──────────────┐
       ▼              ▼                   ▼                  ▼              ▼
┌────────────┐ ┌────────────┐      ┌────────────┐    ┌────────────┐ ┌────────────┐
│ Bare-Metal │ │     VM     │      │     VM     │    │    K8s     │ │  Bridge /  │
│            │ │            │      │            │    │  Cluster   │ │  Gateway   │
└─────┬──────┘ └─────┬──────┘      └─────┬──────┘    └─────┬──────┘ └──┬──────┬──┘
      │              │                   │                 │           │      │
      │◄════ Encrypted Mesh (direct P2P + NAT Traversal) ═════════════►│      │
      │              │                   │                 │           │      │
      └──────────────┴───────────────────┴─────────────────┘      ┌────┘      └────┐
                                                                  │                │
                                                                  ▼                ▼
                                                           ┌──────────┐     ┌────────────┐
                                                           │  User    │     │  External  │
                                                           │  Access  │     │  Traffic   │
                                                           │          │     │            │
                                                           │ Tailscale│     │ Public IPs │
                                                           │ Netbird  │     │ Site-to-   │
                                                           │ WireGuard│     │ Site VPN   │
                                                           └────┬─────┘     └──────┬─────┘
                                                                │                  │
                                                                ▼                  ▼
                                                          ┌───────────┐   ┌──────────────┐
                                                          │ Developers│   │ Public       │
                                                          │ Admins    │   │ Internet     │
                                                          │ On-Call   │   │ Partner Nets │
                                                          └───────────┘   └──────────────┘

All communication between nodes and the control plane is outbound-only — nodes initiate HTTPS and SSE connections; no inbound ports or public IPs are required on the node side.

Between nodes, plexd forms an encrypted WireGuard mesh. Every node establishes direct peer-to-peer tunnels with all authorized peers. NAT traversal is handled automatically via STUN. The control plane coordinates key exchange and peer discovery but never sits in the data path.

Bridge nodes serve a dual role: they participate in the mesh like any other node, but additionally provide external connectivity — user access (Tailscale, Netbird, WireGuard), public ingress, and site-to-site VPN — making internal services reachable from outside the mesh.

For a detailed view of the control plane components, mesh topology, and bridge internals, see Architecture.

Guide ​

How-To Guides ​

Step-by-step guides for common operational tasks.

Reference ​

Operator and admin reference for configuring and deploying plexd.

Actions ​

Deployment ​

Internals ​

Developer and contributor reference for plexd subsystem internals.

  • Agent Internals — Core concepts, subsystem architecture, and agent lifecycle

Core ​

Networking ​

Bridge ​

Observability ​

Integrity ​

Development ​