Mesh networking has revolutionized how devices communicate, offering decentralized, secure, and efficient connectivity. One such powerful tool is NetBird — a simple and open-source mesh VPN solution that allows you to connect your devices across different networks, just like a secure LAN.
In this post, I’ll walk you through the steps to connect a Linux machine (GUI-based) to your NetBird network using the command line, and also how to connect a headless Linux machine (no GUI, remote servers, etc.) using a setup key.
Connect a Linux (GUI) Machine to NetBird
NetBird offers a convenient script to install its components on your system. All you need is a terminal and an internet connection.
Step 1: Install NetBird
Open your terminal and run:
curl -fsSL https://pkgs.netbird.io/install.sh | sh
This script will detect your Linux distribution and install the necessary binaries and services.
Step 2: Start NetBird and Log In via Browser
Once installed, run:
netbird up --management-url https://netbird.yourdomain.com --admin-url https://netbird.yourdomain.com
This will launch NetBird and open a browser window asking you to log in with your NetBird account (or the identity provider configured for your network). After logging in, your device will automatically join the mesh network.
Connect a Headless Linux Machine (No GUI)
When working with servers or remote devices that don’t have a graphical interface, you can skip the login process using a setup key. This is particularly useful for provisioning servers or devices programmatically.
Step 1: Install NetBird
Same as before:
curl -fsSL https://pkgs.netbird.io/install.sh | sh
Step 2: Connect Using Setup Key
Run the following command, replacing the --setup-key with the one provided in your NetBird dashboard:
sudo netbird up \
--management-url https://netbird.yourdomain.com \
--admin-url https://netbird.yourdomain.com \
--setup-key 6CDF7B29-F410-4B08-B2F3-523347B2984F
Your device will silently authenticate and join the network — no browser or manual login required.
