Skip to main content
Get NetBird up and running quickly with this step-by-step guide.
1

Install NetBird

Install the NetBird client for your platform:
curl -fsSL https://pkgs.netbird.io/install.sh | sh
See the installation guide for more platform-specific options and details.
2

Connect to NetBird

Start NetBird and authenticate:
netbird up
On first run, NetBird will open your browser to authenticate. You can:
  • Sign up for a free NetBird Cloud account
  • Connect to your self-hosted instance by specifying --management-url
# For self-hosted
netbird up --management-url https://your-management-server.com:443
3

Verify your connection

Check your connection status:
netbird status
You should see output like:
OS: linux/amd64
Daemon status: Connected
Management: Connected to https://api.netbird.io:443
Signal: Connected to https://signal.netbird.io:443
Relays: 2/2 Available
NetBird IP: 100.119.62.5/16
Interface: wt0
Peers count: 3/3 Connected
To see your connected peers:
netbird status --detail
4

Test connectivity

Ping another peer in your network:
# Find peer IPs
netbird status --detail

# Ping a peer
ping 100.119.62.10
NetBird assigns each peer a unique IP address from the 100.64.0.0/10 range (CGNAT space). This IP is stable and travels with the device across networks.

​
What’s next?

Architecture

Learn how NetBird creates secure peer-to-peer connections

Deploy self-hosted

Run NetBird on your own infrastructure

Access control

Configure granular network access policies

CLI reference

Explore all NetBird CLI commands

​
Running as a service

To run NetBird as a background service that starts automatically: 
# Install service
sudo netbird service install

# Start service
sudo netbird service start

# Enable auto-start
sudo systemctl enable netbird
See the service command reference for more details.

​
Troubleshooting

Check that you can reach the management server:
curl https://api.netbird.io/api/version
# or your self-hosted URL
curl https://your-management-server.com:443/api/version
Verify your firewall allows outbound HTTPS connections on port 443.
This usually means a direct peer-to-peer connection couldn’t be established. Check:
  1. NAT type compatibility - run netbird status --detail and check “Connection type”
  2. Relay server availability - should show “2/2 Available”
  3. Network policies - ensure your peers are allowed to communicate
See troubleshooting for more details.
On mobile devices with strict NAT or frequent network changes:
  • NetBird may fall back to relay servers more often
  • Frequent reconnections can impact battery life
This is normal for mobile carrier networks. The connection will stabilize once on WiFi.
For more help, see the troubleshooting guide or visit the NetBird community forum.

Build docs developers (and LLMs) love

Get started for freeTalk to us