Skip to main content
The NetBird client for macOS provides a native menu bar application with full mesh networking capabilities.

​
Installation

​
Initial Setup

After installation, you can connect to NetBird using either the menu bar app or the command line.

​
Using the Menu Bar App

1

Launch NetBird UI

  • Open NetBird UI from your Applications folder
  • The NetBird icon will appear in your menu bar
2

Connect to your network

  • Click the NetBird icon in the menu bar
  • Click Connect
  • Sign in with your SSO provider or use a setup key
3

Verify connection

The menu bar icon will show a connected state, and you can view:
  • Your NetBird IP address
  • Connected peers
  • Network statistics

​
Using the Command Line

1

Start the NetBird service

netbird service install
netbird service start
2

Connect to NetBird

Using SSO (Interactive Login):
netbird up
Using a Setup Key:
netbird up --setup-key <YOUR_SETUP_KEY>
For self-hosted installations:
netbird up --management-url https://your-management-url.com --setup-key <YOUR_SETUP_KEY>
3

Check status

netbird status
Expected output:
Daemon status: Connected
Management: Connected
Signal: Connected
NetBird IP: 100.x.x.x/16

​
Service Management

Manage the NetBird daemon service: 
# Check service status
netbird service status

# Start the service
netbird service start

# Stop the service
netbird service stop

# Restart the service
netbird service restart

# Uninstall the service
netbird service uninstall

​
Configuration

​
Config File Location

The NetBird configuration is stored at: 
/etc/netbird/config.json

​
Log Files

Logs are written to: 
/var/log/netbird/client.log
View logs in real-time: 
tail -f /var/log/netbird/client.log

​
Environment Variables

Configure NetBird using environment variables with the NB_ prefix:
VariableDescriptionExample
NB_MANAGEMENT_URLManagement server URLhttps://api.netbird.io
NB_LOG_LEVELLogging levelinfo, debug, error
NB_LOG_FILELog file path/var/log/netbird/client.log
NB_INTERFACE_NAMEWireGuard interface nameutun100
NB_WIREGUARD_PORTWireGuard listening port51820
NB_CONFIGConfig file path/etc/netbird/config.json
Set service environment variables: 
netbird service install --service-env="NB_LOG_LEVEL=debug,NB_WIREGUARD_PORT=51820"

​
Command-Line Options

Key CLI flags for netbird up: 
# Set custom WireGuard interface name (must use utun prefix)
netbird up --interface-name utun100

# Set custom WireGuard port
netbird up --wireguard-port 51820

# Set custom MTU
netbird up --mtu 1280

# Set custom hostname
netbird up --hostname my-macbook

# Disable auto-connect on service start
netbird up --disable-auto-connect

# Set custom DNS resolver address
netbird up --dns-resolver-address 127.0.0.1:5053

# Add extra DNS labels
netbird up --extra-dns-labels vpc1,prod
On macOS, the WireGuard interface name must start with the utun prefix (e.g., utun100, utun199). The default is determined by macOS automatically.

​
macOS-Specific Features

​
Network Monitor

NetBird on macOS has network monitoring enabled by default to handle network changes (Wi-Fi switching, VPN connections, etc.). To disable: 
netbird up --network-monitor=false

​
System Preferences Integration

After installation, you may need to grant permissions:
  1. System Preferences → Privacy & Security
  2. Allow NetBird to create network connections
  3. Grant Full Disk Access if requested (for logging)
The NetBird UI is installed to: 
/Applications/NetBird UI.app

​
Advanced Configuration

​
Running in Foreground Mode

For debugging or testing: 
netbird up --foreground-mode

​
Custom External IP Mapping

For complex network setups: 
# Map external IP to local IP
netbird up --external-ip-map 203.0.113.5/192.168.1.10

# Map external IP to interface
netbird up --external-ip-map 203.0.113.5/en0

# Multiple mappings
netbird up --external-ip-map 203.0.113.5,203.0.113.6/192.168.1.10

​
Disable Auto-Connect

Prevent NetBird from connecting automatically when the service starts: 
netbird up --disable-auto-connect
You’ll need to manually run netbird up each time.

​
Troubleshooting

​
Check Connection Status

# Basic status
netbird status

# Detailed status with peer information
netbird status --detail

# JSON output for parsing
netbird status --json

# Get only your NetBird IP
netbird status --ipv4

​
Common Issues

On macOS, interface names must use the utun prefix:
# ✅ Correct
netbird up --interface-name utun100

# ❌ Incorrect
netbird up --interface-name wg0
Grant necessary permissions in System Preferences:
  1. Go to System Preferences → Privacy & Security
  2. Allow NetBird in Full Disk Access (if needed)
  3. Allow NetBird to create network connections
Check your firewall settings:
# Check if NetBird is allowed
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps
Enable debug logging:
netbird service stop
netbird service install --service-env="NB_LOG_LEVEL=debug"
netbird service start

tail -f /var/log/netbird/client.log
If you see “NetBird is already installed,” first uninstall:
netbird service stop
netbird service uninstall
sudo rm -rf /Library/Receipts/netbird.pkg
sudo rm -rf "/Applications/NetBird UI.app"

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

​
Updating NetBird

​
Using the Install Script

curl -fsSL https://pkgs.netbird.io/install.sh | sh
The script will detect the existing installation and update it.

​
Using Homebrew

If installed via Homebrew: 
brew upgrade netbird netbird-ui

​
Uninstalling

1

Stop and uninstall the service

netbird service stop
netbird service uninstall
2

Remove the applications

# Remove the menu bar app
sudo rm -rf "/Applications/NetBird UI.app"

# Remove the CLI binary
sudo rm -f /usr/local/bin/netbird

# Remove configuration and logs
sudo rm -rf /etc/netbird /var/log/netbird
3

Remove package receipt

sudo rm -rf /Library/Receipts/netbird.pkg
For Homebrew installations: 
brew uninstall netbird netbird-ui

Build docs developers (and LLMs) love

Get started for freeTalk to us