NetBird
1. Overview
NetBird provides a management server and an encrypted private network for connected devices. Linux, macOS, Windows, and PicoKVM can connect to the same NetBird management server as peers; support for PLC devices is planned. Once the peers are online and the access policy allows communication, a remote computer can use the target peer's NetBird IP address to open its web management interface.
The peers do not need to be in the same physical LAN. In this guide, "the same private network" means that all peers are connected to the same NetBird management server and are permitted to communicate by the NetBird access policy.
Example values used in this guide:
| Item | Example |
|---|---|
| NetBird server domain | <NETBIRD_SERVER_DOMAIN> |
| NetBird setup key | <NETBIRD_SETUP_KEY> |
| Target peer name | <TARGET_PEER_NAME> |
| Target NetBird IP | <TARGET_NETBIRD_IP> |
A setup key can authorize a device to join the private network. Do not publish it in screenshots, logs, or shared documents. Revoke unused or exposed keys in the NetBird dashboard.
2. Deploy the NetBird Management Server
2.1 Prepare the Server and Domain
-
Prepare a server with a public IP address and a domain. Add an
Arecord that points<NETBIRD_SERVER_DOMAIN>to the server public IP address.
DNS record notes- An
Arecord resolves a domain name to an IPv4 address. - The host record
@represents the root domain. For example, if the domain ispicokvm.com,@representspicokvm.com; after the service is configured, it can be accessed athttps://picokvm.com. - Set the record value to the public IPv4 address of the server that hosts the NetBird management service.
- An
-
Allow the ports required by NetBird in the cloud security group and the server firewall.

2.2 Install the Self-Hosted Server
-
After the DNS record takes effect, run the following commands on the server:
sudo apt updatesudo apt install -y jqexport NETBIRD_DOMAIN=<NETBIRD_SERVER_DOMAIN>curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash
-
Wait until the installer reports that the NetBird services are running.

2.3 Initialize and Log In to the Dashboard
-
Open
https://<NETBIRD_SERVER_DOMAIN>and create the first administrator account.
-
Log in with the administrator account.
-
After the first login, NetBird opens the initialization wizard. Select the type of resource that needs to be accessed. This guide uses Domain as an example.

-
Enter the domain to access through NetBird and a resource name, then create the resource.

-
After the resource is created, the wizard generates a setup key for connecting the routing peer. Copy the key and keep it private.

-
Click Install Routing Peer to open the installation guide. The page provides NetBird installation and connection steps for Linux, macOS, Windows, Docker, and other available platforms. Select the relevant platform and save its instructions as needed.

-
If the initialization wizard was skipped, or another key is needed, open Setup Keys in the NetBird dashboard and create a setup key. Use that key as
<NETBIRD_SETUP_KEY>in the platform instructions below. -
After completing or skipping the initialization wizard, open Peers and confirm that the dashboard is available.

3. Connect Different Platforms
All platforms in this section must use the same https://<NETBIRD_SERVER_DOMAIN>. After each platform connects, check Peers in the NetBird dashboard and confirm that it is online.
3.1 Linux
-
Install NetBird:
curl -fsSL https://pkgs.netbird.io/install.sh | sh -
Connect the Linux device to the self-hosted management server:
sudo netbird up \--management-url https://<NETBIRD_SERVER_DOMAIN> \--setup-key <NETBIRD_SETUP_KEY>
-
Check the connection:
netbird status
3.2 macOS
-
Download and install the macOS client from the NetBird installation guide.

-
Connect the macOS device:
netbird up \--management-url https://<NETBIRD_SERVER_DOMAIN> \--setup-key <NETBIRD_SETUP_KEY> -
Run
netbird statusand confirm that the client is connected.
3.3 Windows
-
Download and install the Windows client from the NetBird installation guide.

-
To connect with a setup key, open PowerShell as an administrator and run:
netbird up --management-url https://<NETBIRD_SERVER_DOMAIN> --setup-key <NETBIRD_SETUP_KEY> -
To use interactive login, open Settings -> General, select the self-hosted management server, and enter
https://<NETBIRD_SERVER_DOMAIN>.
-
Click Connect, then complete the login in the browser.
3.4 PicoKVM
- Open the PicoKVM web interface and go to Settings -> Access -> NetBird.
- Enter
https://<NETBIRD_SERVER_DOMAIN>in Management URL and start the NetBird service. - Copy and open the generated Binding Link, then log in to the same NetBird management server to bind PicoKVM.
- Return to PicoKVM and confirm that the NetBird status is online.

3.5 Luckfox Lyra PLC
NetBird integration for Luckfox Lyra PLC is planned. The client procedure and screenshots will be added after the feature becomes available.
4. Verify Private Network Access
-
Open Peers in the NetBird dashboard and confirm that the remote computer and the target peer are online.
-
Copy the NetBird IP address of the target peer and use it as
<TARGET_NETBIRD_IP>. -
On the remote computer, check connectivity:
netbird statusping <TARGET_NETBIRD_IP> -
Open the target device web interface:
http://<TARGET_NETBIRD_IP>If the target device uses HTTPS or a non-default port, use its actual protocol and port.
5. Troubleshooting
- The peer does not appear in the dashboard: Check the management server URL, setup key validity, system time, and NetBird service status.
- The peer is online but cannot reach the target: Check whether the NetBird access policy allows communication between the remote computer and the target peer.
- Ping fails but the web interface opens: ICMP may be blocked. Test the web service directly.
- The web interface does not open: Confirm that the service is running on the target device and that its firewall allows traffic from the NetBird interface.
- A setup key was exposed or expired: Revoke it and create a new key in the dashboard.