some file

MacOS Installation

The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and self-hosted options available.

Install with one command

curl -fsSL https://pkgs.netbird.io/install.sh | sh

This installs the full NetBird application, including the desktop UI and the daemon service.

Package install

  1. Download the latest MacOS release installer for your processor:
  2. Proceed with the installation steps
  3. This will install the NetBird app into /Applications and add the daemon service
  4. After installing, you can follow the steps from Running NetBird with SSO Login steps.

To uninstall the client remove the app from /Applications

Homebrew install

  1. Download and install homebrew at https://brew.sh/
  2. If netbird was previously installed with homebrew, you will need to run:
# Stop and uninstall daemon service:
sudo netbird service stop
sudo netbird service uninstall
# unlink the app
brew unlink netbird

netbird will copy any existing configuration from the netbird's default configuration paths to the new NetBird's default location

  1. Install the client
  # for CLI only
  brew install netbirdio/tap/netbird
  # for GUI package
  brew install --cask netbirdio/tap/netbird-ui
  1. If you installed CLI only, you need to install and start the client daemon service:
 sudo netbird service install
 sudo netbird service start

CLI-only install (binary)

If you need only the CLI client without the desktop UI — for example, on headless servers or for MDM/fleet deployments — you can install the standalone binary directly.

One-command binary install

The macOS binary tarballs from GitHub releases are not Apple code-signed or notarized. Only the official .pkg installer from pkgs.netbird.io contains signed binaries. The unsigned binary will trigger Gatekeeper warnings and may be blocked by MDM policies. For managed fleet deployments, see Building a CLI-Only .pkg for MDM Deployment which includes steps for signing the binary with your own Developer ID.

The install script supports a binary-only mode that downloads the tarball, extracts the netbird binary to /usr/local/bin/, and registers the launchd daemon:

curl -fsSL https://pkgs.netbird.io/install.sh | USE_BIN_INSTALL=true SKIP_UI_APP=true sh

To update an existing binary install, add the UPDATE_NETBIRD flag:

curl -fsSL https://pkgs.netbird.io/install.sh | USE_BIN_INSTALL=true SKIP_UI_APP=true UPDATE_NETBIRD=true sh

Manual binary install

  1. Checkout NetBird releases
  2. Download the latest release for macOS:
  # For Apple Silicon (M1, M2, M3, M4):
  curl -L -o ./netbird.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_darwin_arm64.tar.gz

  # For Intel:
  curl -L -o ./netbird.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_darwin_amd64.tar.gz

  # Universal binary (works on both architectures):
  curl -L -o ./netbird.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_darwin_all.tar.gz

Replace VERSION with the latest released version (e.g., 0.36.5). You can find version numbers on the releases page.

  1. Extract and install the binary:
  tar xzf ./netbird.tar.gz
  sudo mv netbird /usr/local/bin/netbird
  sudo chown root:wheel /usr/local/bin/netbird
  sudo chmod +x /usr/local/bin/netbird
  1. Install and start the daemon service:
  sudo netbird service install
  sudo netbird service start

This creates a launchd daemon at /Library/LaunchDaemons/netbird.plist that runs as root (required for managing the WireGuard network interface).

Automatic updates via the NetBird dashboard do not work for binary-only installs. The auto-updater requires the official .pkg installer (it checks for the io.netbird.client package receipt). For binary installs, you must update manually or push updates through your MDM solution. See Building a CLI-Only .pkg for MDM Deployment for a managed approach.

Running NetBird with SSO Login

Desktop UI Application

If you installed the Desktop UI client, you can launch it and click on Connect.

It will open your browser, and you will be prompt for email and password. Follow the instructions.

high-level-dia

CLI

Alternatively, you could use command line. Simply run

netbird up

It will open your browser, and you will be prompt for email and password. Follow the instructions.

high-level-dia

Check connection status:

  netbird status

Running NetBird with a Setup Key

In case you are activating a server peer, you can use a setup key as described in the steps below.

This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.

  1. Login to the Management Service. You need to have a setup key in hand (see setup keys).
  netbird up --setup-key <SETUP KEY>

Alternatively, if you are hosting your own Management Service provide --management-url property pointing to your Management Service:

  netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073

You could also omit the --setup-key property. In this case, the tool will prompt for the key.

  1. Check connection status:
  netbird status
  1. Check your IP:
  sudo ifconfig utun100