plexd

module

v0.7.0 Latest Latest Go to latest Published: Aug 4, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/plexsphere/plexd

Links

Open Source Insights

README ¶

plexd

plexd runs on every node in a Plexsphere-managed environment. It connects to the control plane, registers the node, establishes encrypted WireGuard mesh tunnels to peers, enforces network policies, and continuously reconciles local state against the desired state.

MVP / Work in Progress – This project is under active development. APIs, configuration formats, protocols, and internal interfaces are subject to change without prior notice. Do not rely on current behavior or interfaces for production use.

Key Capabilities

Self-Registration with one-time bootstrap tokens (Cloud-Init, K8s Secret, or manual enrollment)
Mesh Connectivity via direct encrypted WireGuard tunnels between authorized peers
NAT Traversal with STUN endpoint discovery and bridge-node relay fallback
Policy Enforcement through peer visibility filtering and local firewall rules
Configuration Reconciliation against the control plane's source of truth
Bridge Mode for user access, public ingress, site-to-site VPN, and NAT relay
Observability with metrics collection, log forwarding, and audit data forwarding
Remote Actions & Hooks with SHA-256 integrity verification
Local Node API exposing node state via Unix socket (bare-metal/VM) or CRD (Kubernetes)
Secure Access for platform-mediated SSH and Kubernetes API tunneling through the mesh

Runs on bare-metal servers, VMs, Kubernetes clusters, OpenWRT routers, and as bridge/gateway. Linux (amd64, arm64, mipsle).

Quick Start

# Install
curl -fsSL https://get.plexsphere.com/plexd | sh

# Enroll the node (interactive token prompt)
plexd join

# Run as a service
sudo plexd install
sudo systemctl enable --now plexd

See Installation & Quick Start for container, Kubernetes, OpenWRT, and bridge-mode deployments.

Documentation

The full documentation lives at https://plexsphere.github.io/plexd/:

Installation & Quick Start
Architecture, Agent Lifecycle, and Security & Trust Model
How-to guides for bare-metal, VM, and Kubernetes deployments
Reference for the CLI, configuration, environment variables, and control plane API
Troubleshooting

The documentation source is in docs/; preview locally with npm install && npm run docs:dev.

Development

Requires Go 1.26+, WireGuard tools, and nftables.

make build   # Build the plexd binary
make test    # Run unit tests
make lint    # Run golangci-lint

See Development: Getting Started for the project structure, e2e tests, and CI workflows.

License

Apache License 2.0 - see LICENSE for details.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
plexd command Package main is the entry point for the plexd binary.	Package main is the entry point for the plexd binary.
plexd/cmd Package cmd implements the plexd CLI commands.	Package cmd implements the plexd CLI commands.
internal
actions Package actions provides remote action execution and hook management for plexd mesh nodes.	Package actions provides remote action execution and hook management for plexd mesh nodes.
agent Package agent implements agent-level runtime services.	Package agent implements agent-level runtime services.
api
auditfwd Package auditfwd provides audit data collection and forwarding from plexd mesh nodes to the control plane.	Package auditfwd provides audit data collection and forwarding from plexd mesh nodes to the control plane.
bridge Package bridge provides bridge mode functionality including user access integration.	Package bridge provides bridge mode functionality including user access integration.
fsutil
health
integrity Package integrity verifies the plexd binary and hook scripts by SHA-256 checksum, and the SSH host key by its OpenSSH fingerprint.	Package integrity verifies the plexd binary and hook scripts by SHA-256 checksum, and the SSH host key by its OpenSSH fingerprint.
kubernetes Package kubernetes provides Kubernetes environment detection and integration.	Package kubernetes provides Kubernetes environment detection and integration.
logfwd Package logfwd provides log forwarding from plexd mesh nodes to the control plane.	Package logfwd provides log forwarding from plexd mesh nodes to the control plane.
metrics Package metrics provides metrics collection and reporting for plexd mesh nodes.	Package metrics provides metrics collection and reporting for plexd mesh nodes.
nat Package nat provides NAT traversal via STUN for plexd mesh nodes.	Package nat provides NAT traversal via STUN for plexd mesh nodes.
nodeapi
packaging Package packaging implements systemd service packaging for bare-metal Linux servers.	Package packaging implements systemd service packaging for bare-metal Linux servers.
peerexchange Package peerexchange orchestrates peer endpoint exchange for plexd mesh nodes.	Package peerexchange orchestrates peer endpoint exchange for plexd mesh nodes.
policy Package policy implements network policy enforcement for plexd mesh nodes.	Package policy implements network policy enforcement for plexd mesh nodes.
reconcile
registration Package registration implements node self-registration.	Package registration implements node self-registration.
tunnel Package tunnel implements secure access tunneling for plexd mesh nodes.	Package tunnel implements secure access tunneling for plexd mesh nodes.
upgrade Package upgrade downloads plexd release binaries from the GitHub release channel and verifies their Sigstore bundles before they are trusted.	Package upgrade downloads plexd release binaries from the GitHub release channel and verifies their Sigstore bundles before they are trusted.
wireguard
test
e2e/mockapi Package mockapi provides a mock Central API server for end-to-end testing.	Package mockapi provides a mock Central API server for end-to-end testing.
e2e/mockapi/cmd/mockapi command Command mockapi runs a mock Central API server for end-to-end testing.	Command mockapi runs a mock Central API server for end-to-end testing.