some file

pfSense 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.

This installation is intended for early adopters while the pfSense package is under review and not yet available in the pfSense package manager.

Prerequisites

  • Shell/SSH access to pfSense (via Web UI shell or remote SSH)
  • A setup key to authenticate and register the pfSense device
  • The latest NetBird .pkg binary from the GitHub Releases

Installation

  1. SSH into your pfSense system

    ssh admin@<pfsense-ip>

    If remote SSH is enabled or use the built-in shell via the pfSense Web UI (Diagnostics > Command Prompt).

  2. Download the NetBird client(agent)

    From a shell on your pfSense system, run:

    fetch https://github.com/netbirdio/pfsense-netbird/releases/download/v0.1.0/netbird-0.49.0.pkg

  3. Download the NetBird pfSense package

    From a shell on your pfSense system, run:

    fetch https://github.com/netbirdio/pfsense-netbird/releases/download/v0.1.0/pfSense-pkg-NetBird-0.1.0.pkg

  4. Install the packages

    pkg add -f netbird-0.49.0.pkg
pkg add -f pfSense-pkg-NetBird-0.1.0.pkg

  5. Verify the installation

    The NetBird GUI should now appear under VPN > NetBird in the pfSense menu.

Configuration

Authenticate the machine

Fill out the authentication form with the following values and click Save:

  • Management URL: Default is https://app.netbird.io:443. If self-hosting, enter your custom management server URL.
  • Setup Key: Paste the setup key from your NetBird account. .

authentication

Verify Connection Status

The Status page shows detailed information about connected peers and control services, helping you monitor your deployment. Access it via Status > NetBird in the pfSense menu.

Use this section for diagnostics and troubleshooting common connection or setup issues.

connection status

Uninstallation

From a shell on your pfSense system, run:

pkg delete netbird-0.49.0 pfSense-pkg-NetBird-0.1.0

Get started