Quickstart

Get NetBird up and running quickly with this step-by-step guide.

Install NetBird

Install the NetBird client for your platform:

Linux
macOS
Windows
Docker

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

brew install netbirdio/tap/netbird

docker run --rm --name netbird -d --network host \
  --cap-add=NET_ADMIN --cap-add=SYS_ADMIN \
  -v netbird-client:/etc/netbird \
  netbirdio/netbird:latest up

See the installation guide for more platform-specific options and details.

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

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

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:

Linux
macOS
Windows

# Install service
sudo netbird service install

# Start service
sudo netbird service start

# Enable auto-start
sudo systemctl enable netbird

sudo netbird service install
sudo netbird service start

# Run as Administrator
netbird service install
netbird service start

See the service command reference for more details.

Troubleshooting

Connection fails with 'failed to connect to management server'

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.

Peers can't reach each other

This usually means a direct peer-to-peer connection couldn’t be established. Check:

NAT type compatibility - run netbird status --detail and check “Connection type”
Relay server availability - should show “2/2 Available”
Network policies - ensure your peers are allowed to communicate

See troubleshooting for more details.

High CPU or battery usage on mobile

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.

Get Started

Architecture

Deployment

Client Setup

Network Management

Security

Operations

What’s next?

Architecture

Deploy self-hosted

Access control

CLI reference

Running as a service

Troubleshooting

​What’s next?

Architecture

Deploy self-hosted

Access control

CLI reference

​Running as a service

​Troubleshooting

What’s next?

Running as a service

Troubleshooting