Roll Out NetBird Across Your Organization with MDM

Updated October 8, 2026

Installing NetBird on your own laptop takes a minute. Installing it on 500 company laptops, making sure every one of them connects to the right server as the right user, and keeping their settings the way your security team signed off on, is a different job.

This guide shows how to do that with the MDM you already use, and walks through a complete rollout with Microsoft Intune.

One device, by hand

On a single machine:

1. Download the installer: EXE or MSI on Windows, PKG on macOS.
2. Run it with administrator rights.
3. Open NetBird and choose the management server: NetBird Cloud, or self-hosted.
4. Click Connect and sign in through the browser with your identity provider (IdP). The device joins as a peer under your user.

That is enough for one person. Afterward the device's owner still controls the server URL, profiles, SSH, and every setting your security posture depends on. On one machine, nobody minds. On a fleet, each of those is a support ticket or a gap nobody notices.

Why it does not scale

Repeat those four steps across an organization and each one turns into its own problem:

• Installing needs administrator rights most users do not have (and should not).
• Users get the server wrong and land in an account that is not yours.
• Setup keys break identity. A peer enrolled with a setup key has no user behind it, so user-based policies, login expiration, and offboarding do not apply. Setup keys are for servers, not laptops: see Bootstrap peers via config file.
• Settings and versions drift with no owner to pin them.
• Unmanaged devices look the same as managed ones once someone signs in with valid credentials.

The rollout model

Two properties make this split work:

• The installer carries no configuration; the policy carries all of it. Same MSI or PKG everywhere. Change the policy anytime and the client applies it within a minute, with no reinstall.
• The policy removes the hard step for users. When it pins the management server, the app skips the server question. The user opens NetBird, clicks Connect, and signs in with the account they already use.

Optional jobs on the same tools:

• Gate access on compliance with your MDM's NetBird integration. See Step 7.
• Enroll devices with no user (kiosks, meeting-room PCs, servers) with a setup key. Keep them in their own group with their own policy.

Supported MDMs

NetBird uses three MDM capabilities and adds no agent of its own: app deployment, a managed-configuration channel (HKLM\Software\Policies on Windows, managed preferences on macOS), and an optional compliance signal.

Any MDM that can install a package and write to those channels works. These have dedicated guides:

This guide covers Windows and macOS. Linux has no MDM channel in NetBird today: install with your configuration management tool and set the same options with service-install flags or a config file.

Example: roll out with Microsoft Intune

This example rolls NetBird out to Windows and macOS laptops at a company that uses Microsoft Entra ID for identity and Intune for device management. Users sign in with their Entra ID accounts. Laptops get the user device policy recommended for end-user machines.

The examples use a self-hosted management server at https://netbird.example.com:443. On NetBird Cloud, use https://api.netbird.io:443 instead.

Before you start

• NetBird SSO with Microsoft Entra ID. On NetBird Cloud, Microsoft sign-in works with no extra setup; for self-hosted, see Microsoft Entra ID.
• Recommended: Entra ID group sync, so each new peer lands in its user's groups and your access policies apply from the first connection.
• An Intune admin with at least the Policy and Profile Manager role, and Windows and macOS devices enrolled in Intune.
• Two Entra ID device groups: NetBird Pilot (a handful of IT-owned laptops) and NetBird Laptops (every end-user laptop). Keep routing peers and servers out of both: the policy below stops a device from routing other peers' traffic.
• The installers: the Windows MSI, and the macOS PKG for Apple Silicon and Intel.
• The policy templates: netbird.admx and netbird.adml for Windows, and netbird-macos.mobileconfig for macOS.

Step 1: Define the policy

Decide what to pin before you deploy anything. For end-user laptops, start from four keys with your server URL (for example https://netbird.example.com:443) as the management URL:

Leave every other key out. A key in the policy is pinned even when its value is false; a key you leave out stays the user's to change. To adapt the policy, see What you can achieve.

Step 2: Deliver the policy

Create the policy first and assign it together with, or before, the app. The desktop app decides whether to ask for a server when it opens for the first time; if the policy has not arrived by then, the user sees the question you meant to remove.

Windows: an Imported Administrative templates profile.

1. Import netbird.admx and netbird.adml once per tenant: Devices → Manage devices → Configuration → Import ADMX → Import.
2. Create the profile: Devices → Manage devices → Configuration → Create → New policy, platform Windows 10 and later, profile type Templates → Imported Administrative templates (Preview). Name it NetBird: user laptops.
3. Under NetBird, set Management URL to Enabled with your URL, and Disable update settings, Disable profiles, and Disable server routes to Enabled. Leave everything else Not configured: Disabled pins the setting to false.
4. Assign the profile to the NetBird Pilot device group.

Enforce NetBird Settings on Windows has every step in detail, plus an OMA-URI alternative for tenants that cannot import templates.

macOS: a custom configuration profile.

1. Edit netbird-macos.mobileconfig. Inside the mcx_preference_settings dictionary, keep only the four keys, and replace each PayloadUUID with a fresh value from uuidgen:

   <key>managementURL</key>
   <string>https://netbird.example.com:443</string>
   <key>disableUpdateSettings</key>
   <true/>
   <key>disableProfiles</key>
   <true/>
   <key>disableServerRoutes</key>
   <true/>
   

   CopyCopied!

   Write booleans as <true/> or <false/>, never as <integer>: macOS locks an integer boolean but never applies it.

2. Create the profile: Devices → Manage devices → Configuration → Create → New policy, platform macOS, profile type Templates → Custom. Upload the file and name it NetBird: user laptops.

3. Assign it to the NetBird Pilot device group.

See Enforce NetBird Settings on macOS for the template details and how to check the profile arrived.

Step 3: Deploy the client

Windows: the MSI as a line-of-business app.

1. Apps → Windows → Create, app type Line-of-business app, and upload the MSI.
2. Set App install context to Device, and leave Command-line arguments empty: the policy carries the configuration.
3. Set Ignore app version according to who owns updates, in Step 5.
4. Assign it as Required to the NetBird Pilot device group.

macOS: the PKG as a macOS app.

1. Apps → macOS → Create, app type macOS app (PKG), and upload the PKG. Apple Silicon and Intel Macs need different packages: add each as its own app, and assign each to a group that holds only Macs of that type.
2. The bundle ID is io.netbird.client. Set Ignore app version as shown in Step 5.
3. Assign it as Required to the NetBird Pilot device group.

For a Win32 package with custom detection rules and supersedence, see Deploy with Intune.

Step 4: First sign-in

Intune installs NetBird and starts its service. The device does not join your network until its user signs in, so tell users what to expect before the pilot starts:

• On macOS, the installer opens the NetBird app for the user who is logged in.
• On Windows, a silent install does not open the app. The user opens NetBird from the Start menu once; from then on it opens at every login.

Because the policy pins the server, the app skips the server question. The user clicks Connect, signs in with their Entra ID account in the browser, and is connected. The new peer appears in the NetBird dashboard under that user's name and, with group sync, in that user's groups.

A short message is enough:

NetBird is now installed on your laptop. Open NetBird, click Connect, and sign in with your work account. You only need to do this once.

Step 5: Pick one owner for updates

The client can be updated by NetBird or by Intune. Choose one: when both try, they work against each other.

Letting NetBird update is less work and keeps clients close to your management server's version. Letting Intune do it gives you change windows and staged rings. To hold the fleet on a specific version with NetBird, set Automatic Updates to a Custom Version.

Step 6: Verify the pilot, then widen

Check each layer, from Intune down to the device:

1. In Intune, the app's Device install status and the profile's Device status show success for every pilot device.

2. On a Windows device, from an elevated prompt:

   reg query HKLM\Software\Policies\NetBird
   netbird debug config
   netbird status
   

   CopyCopied!

   reg query shows what Intune wrote. In netbird debug config, the mDMManagedFields array lists every key the client reads from the policy:

   "mDMManagedFields": [
     "disableProfiles",
     "disableServerRoutes",
     "disableUpdateSettings",
     "managementURL"
   ]
   

   CopyCopied!

3. On a macOS device, run netbird debug config and netbird status the same way. The macOS page shows how to check the profile itself.

4. In the NetBird dashboard, each pilot device appears under Peers with its user's name and groups.

5. As a user, open the app: the Network, Security, SSH, Advanced, and Profiles settings tabs are gone, and Connect still works.

When the pilot looks right, add the NetBird Laptops group to the assignments of both apps and both profiles. Devices pick them up at their next Intune check-in. If something is off, see Verifying enforcement and Troubleshooting.

Step 7 (optional): Only let compliant devices in

With the client on every company laptop, you can make sure nothing else gets in. NetBird's Intune integration checks each peer in the groups you select against Intune: a device that is not managed by Intune, or not compliant with your compliance policies, waits for approval and cannot reach anything. A personal laptop signed in with a valid account stays locked out.

Connect Intune under Integrations → EDR in the NetBird dashboard and select the groups the check applies to, such as the groups synced from Entra ID for your employees. The integration covers Windows and macOS, and is available on the NetBird Cloud Business plan and with a self-hosted Enterprise license.

A device that fails the check shows Approval required in the peers list until Intune reports it as managed and compliant:

Rollout checklist

• SSO works with your IdP, and groups sync into NetBird
• Access policies use the synced groups
• Laptops with a user-installed NetBird EXE are cleaned up, or you deploy the EXE
• The policy holds only the keys you mean to pin
• The policy is assigned together with, or before, the app
• One owner for updates, with Ignore app version set to match
• Users know to open NetBird, click Connect, and sign in once
• The pilot group checks out in Intune, on the device, and in the dashboard
• Routing peers and servers are outside the laptop groups
• Optional: the Intune integration gates access on compliance