Skip to main content

NetBird agent (Maresa)

This page is about the NetBird peer running on the Maresa Synology host. The mesh itself, its routing model, and the cross-site ACL primitives live on Fabric → NetBird — that's the right entry point if you want the big picture. This page just covers the agent's role on Maresa.

Why the Synology joins the mesh​

The Synology hosts a few things the cluster needs to reach without leaking them onto the public internet:

Joining the home NetBird network makes those endpoints private-by-default — any administrator already in the home network can reach them; nothing else can.

Why a container, not the Synology package​

The Synology has a NetBird app in its package catalog, but the catalog version usually lags upstream by a release or two. Running the agent as a Docker container — Renovate-pinned, restarted on its own schedule — keeps it on the same upgrade cadence as everything else in the homelab.

The rootless image is used; the agent doesn't need extra privileges because the routing is done by the daemon's userspace WireGuard, not the host kernel.

Operational notes​

  • Setup key (NB_SETUP_KEY) is provided via the host environment, not committed to the compose file.
  • The peer registers under the hostname netbird-home in the home NetBird network; ACLs reference it by that name.
  • Token rotation is a peer-side concern; the agent re-registers with a fresh setup key when the old one expires.
  • If the agent stops, the Synology is unreachable from the mesh until it comes back. AdGuard / Syncthing on the LAN keep working — only mesh-side access drops.

Cluster Deployment​

NetBird agent — Maresa Docker host

Layout​

  • Image pinned by tag and digest (-rootless variant), bumped by Renovate.
  • Rootless variant — userspace WireGuard, no extra host privileges required.
  • Volume netbird-client for peer identity / known-hosts.
  • Hostname netbird-home so ACL rules in the netbird Tofu environment can reference it by name.
  • NB_SETUP_KEY injected via the host environment; never committed to the compose file.

Deviations from defaults​

  • Rootless image instead of the host-mode variant — Synology DSM doesn't expose enough of the kernel for kernel-mode WireGuard to work cleanly.
Compose Metadata
  • Image: netbirdio/netbird:0.81.2-rootless@sha256:0ff1cbfc435d0fe39ee8824fee9a6ec2f56eb472b5d45abafd53ecee90161d60