Setup keys

A setup key lets a machine join without anyone signing in. Create it in the console, use it once or many times, revoke it when done.

Create a key

Settings → Setup Keys → Create. Choose:

Option	Meaning
One-off	valid for a single device; the safest choice for one server
Reusable	many devices; set a usage limit and an expiry for fleets and CI
Expires in	the key stops working after this; devices already enrolled stay
Auto-assigned groups	devices enrolled with this key land in these groups, so policies apply immediately
Ephemeral	devices are removed automatically after they have been offline for a while; for containers that come and go

The key value is shown once. Store it where you keep secrets.

Use it

sudo netbird up --management-url https://mesh.example.com --setup-key <key>

In Docker:

docker run -d --name mesh-peer --cap-add NET_ADMIN --device /dev/net/tun \
  -e NB_SETUP_KEY=<key> -e NB_MANAGEMENT_URL=https://mesh.example.com \
  netbirdio/netbird:latest

Approvals still apply

A key proves the machine was enrolled by someone holding the key. With Peer Approval on, the device still waits in Warden until an administrator admits it. That is deliberate: a leaked key enrols nothing you did not look at.

Revoke

Revoking a key stops new enrolments with it. Devices already enrolled keep working; remove them from Peers if the key leaked.

← Device approvals (Warden)Exit nodes →