WireGuard mesh and agents

Loopback implements private host-to-host connectivity using WireGuard. The control plane computes who should peer with whom; the agent on each Linux host materializes host-level WireGuard configuration and manages the service lifecycle.

This page explains behavior customers and operators care about during diligence.

End state: every host in the network sees every other

For a given Loopback network, automation builds a full mesh:

Each host receives a stable overlay address inside the allocated CIDR.
Each host’s config lists every other host in that network as a peer with public key, endpoint address, and AllowedIPs scoped to the peer overlay address.
Bridged networks contribute extra peers pulled from other meshes (see Bridges).

The agent merges per-network configuration fragments into one operational WireGuard interface, enforcing a single private key across merged material for consistency.

Configuration delivery path

Control plane stages configuration documents per network and host (keys, addresses, peer lists).
Agent-driven apply rewrites live configuration, validates key consistency, and applies conservative tunnel defaults (MTU/keepalive tuned for nested encapsulation in typical deployments).
Service restart applies changes; failures roll back to the last known good config where implemented.

Treat mesh apply like any other in-place network change: brief session impact is possible while interfaces bounce.

Keys and rotation

Key generation and assignment occur during network bring-up in the worker tier. The agent assumes one logical private key for the combined mesh bundle on a host. Rotation today is effectively re-run network workflows after operational key changes; confirm your operator’s runbook for compliance-driven rotation frequency.

Debugging checklist (human-oriented)

Agent offline: Peers stay unreachable; reconciliation may flag hosts and monitoring sources.
Asymmetric routes: Rare, but security groups or provider firewalls outside Loopback can block the WireGuard UDP port; the mesh never converges.
MTU issues: Defaults favor tunnel compatibility; adjust upstream PMTUD education for your team if you encapsulate further.
Stuck after membership change: Use the host network re-apply API to schedule mesh refresh for all relevant networks.

Relationship to Kubernetes networking