Enrol devices

Every device joins the mesh in one of three ways. All three end in the same place: a peer you can see, approve, and revoke.

1. Pre-approved installer

For machines you provision yourself: servers, containers, a fleet you image. Create a setup key with Pre-approved installer on (Settings → Setup Keys → Create). The console shows the install command for Linux, macOS, Windows and Docker with the key already in it; paste it into your provisioning script or run it by hand. The device is admitted on first contact and the activity log records peer auto-approved by setup key.

curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --management-url https://mesh.example.com --setup-key <pre-approved key>

2. Request to join

For everything you did not set up yourself: a colleague's laptop, a contractor's machine, a device someone bought last week. Create a setup key with Pre-approved installer off, name it after the team or site (sales-request, riyadh-office) and hand it out with the install command. Devices installed with it register, then wait in Warden with their hostname, operating system and the key they used. Nothing reaches the mesh until you admit it, so the key can circulate freely inside the organisation.

The person enrolling can say who they are and why, so the request is not just a hostname in the inbox:

sudo netbird up --management-url https://mesh.example.com --setup-key <request key> \
  --enrol-note "Ahmed, contractor, needs the ERP subnet until Friday"

The note (or NB_ENROL_NOTE) is stored once at registration, capped at 200 characters, shown in Warden and in the notification e-mail and webhook, and never changed by later logins. It needs the TZX Mesh client; upstream clients simply register without one.

While a device waits, its client shows it connected to the control plane with no peers. Once you approve it, it joins within a sync cycle without any action on the device.

Keep stale-device expiry on for request keys, so forgotten requests do not pile up.

3. A person signs in

Someone with an account opens the client, chooses Log in, and signs in through your identity provider or the built-in one. Their device follows the account's approval rule: with Peer Approval on it waits in Warden like any other device, with it off it joins at once. The peer is tied to the person, so revoking the user's access disconnects all their devices.

Which one to use

Automation

Keys are created over the API with auto_approve set for a pre-approved key and unset for a request key; devices are approved with PUT /api/peers/<id> or in bulk with POST /api/peers/approvals. See Setup keys and Device approvals.