Skip to main content
The NetBird client for Windows provides a native system tray application with full mesh networking capabilities.

​
Installation

​
Download the MSI Installer

Download the latest NetBird installer from netbird.io/install or GitHub Releases.
1

Run the installer

Double-click the downloaded .msi file to launch the installer.
2

Follow the installation wizard

  • Accept the license agreement
  • Choose the installation location (default: C:\Program Files\Netbird)
  • Click Install
3

Complete installation

The installer will:
  • Install the NetBird CLI and UI
  • Install the Windows service
  • Add NetBird to your system tray
  • Start the service automatically

​
Initial Setup

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

​
Using the System Tray App

1

Locate the NetBird icon

Look for the NetBird icon in your Windows system tray (bottom-right corner of the screen).
2

Connect to your network

  • Right-click the NetBird icon
  • Click Connect
  • Sign in with your SSO provider or use a setup key
3

Verify connection

The system tray icon will show a connected state. Click it to view:
  • Your NetBird IP address
  • Connected peers
  • Network statistics

​
Using the Command Line

Open PowerShell or Command Prompt as Administrator:
1

Start the NetBird service

netbird service install
netbird service start
The service is usually started automatically during installation.
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 Windows 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
Alternatively, use Windows Services Manager:
  1. Press Win + R
  2. Type services.msc and press Enter
  3. Find Netbird in the list
  4. Right-click to Start, Stop, or Restart

​
Configuration

​
Config File Location

The NetBird configuration is stored at: 
%PROGRAMDATA%\Netbird\config.json
Typically: C:\ProgramData\Netbird\config.json

​
Log Files

Logs are written to: 
%PROGRAMDATA%\Netbird\client.log
Typically: C:\ProgramData\Netbird\client.log View logs in PowerShell: 
Get-Content "$env:PROGRAMDATA\Netbird\client.log" -Tail 50 -Wait

​
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 pathC:\ProgramData\Netbird\client.log
NB_INTERFACE_NAMEWireGuard interface namewt0
NB_WIREGUARD_PORTWireGuard listening port51820
NB_CONFIGConfig file pathC:\ProgramData\Netbird\config.json
NB_DAEMON_ADDRDaemon socket addresstcp://127.0.0.1:41731
Set service environment variables: 
netbird service install --service-env="NB_LOG_LEVEL=debug,NB_WIREGUARD_PORT=51820"
On Windows, the daemon listens on TCP 127.0.0.1:41731 by default (not Unix socket).

​
Command-Line Options

Key CLI flags for netbird up: 
# Set custom WireGuard interface name
netbird up --interface-name wt0

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

# Set custom MTU
netbird up --mtu 1280

# Set custom hostname
netbird up --hostname my-windows-pc

# 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

​
Windows-Specific Features

​
Network Monitor

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

​
Windows Firewall

NetBird automatically configures Windows Firewall rules. If you experience connection issues, verify: 
# Check if NetBird is allowed through firewall
Get-NetFirewallRule -DisplayName "*NetBird*"

​
Run as Administrator

Some NetBird operations require administrator privileges. Always run PowerShell or Command Prompt as Administrator when:
  • Installing or uninstalling the service
  • Modifying network settings
  • Troubleshooting connectivity issues

​
Advanced Configuration

​
Running in Foreground Mode

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

​
Custom External IP Mapping

For machines behind NAT or with multiple interfaces: 
# 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/Ethernet

# 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

​
Service Reconfiguration

Update service settings without reinstalling: 
netbird service reconfigure --service-env="NB_LOG_LEVEL=debug,NB_WIREGUARD_PORT=51820"

​
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

Restart the service:
netbird service restart
If the problem persists:
netbird service stop
netbird service uninstall
netbird service install
netbird service start
Check if the service is installed:
Get-Service -Name "Netbird"
View detailed service status:
netbird service status
Check Windows Event Viewer:
  1. Press Win + X
  2. Select Event Viewer
  3. Navigate to Windows Logs → Application
  4. Look for NetBird-related errors
Ensure Windows Firewall allows NetBird:
# Check firewall rules
Get-NetFirewallRule -DisplayName "*NetBird*" | Format-Table Name,Enabled,Direction,Action
Enable debug logging:
netbird service stop
netbird service install --service-env="NB_LOG_LEVEL=debug"
netbird service start

Get-Content "$env:PROGRAMDATA\Netbird\client.log" -Tail 50 -Wait
Check if WireGuard driver is installed:
Get-NetAdapter | Where-Object {$_.InterfaceDescription -like "*WireGuard*"}
Reinstall NetBird if the driver is missing.
Always run PowerShell or Command Prompt as Administrator for NetBird operations.Right-click PowerShell → Run as administrator

​
Debug Bundle

Generate a debug bundle for troubleshooting: 
netbird debug bundle
This creates a ZIP file with:
  • Configuration files
  • Log files
  • System information
  • Network diagnostics

​
Updating NetBird

​
Automatic Updates

NetBird for Windows can check for updates automatically. You’ll be notified in the system tray when a new version is available.

​
Manual Update

  1. Download the latest MSI installer
  2. Run the installer (it will detect and upgrade the existing installation)
  3. Restart the service if needed: 
    netbird service restart

​
Uninstalling

1

Stop and uninstall the service

netbird service stop
netbird service uninstall
2

Uninstall via Control Panel

  1. Press Win + R
  2. Type appwiz.cpl and press Enter
  3. Find NetBird in the list
  4. Click Uninstall
3

Remove configuration files (optional)

Remove-Item -Recurse -Force "$env:PROGRAMDATA\Netbird"

​
Alternative: Uninstall via MSI

Run the MSI installer again and select Remove when prompted.

​
Clean Uninstall

For a complete removal: 
# Stop and uninstall service
netbird service stop
netbird service uninstall

# Uninstall via Windows Installer
msiexec /x {PRODUCT_CODE} /qn

# Remove all NetBird files
Remove-Item -Recurse -Force "$env:PROGRAMFILES\Netbird"
Remove-Item -Recurse -Force "$env:PROGRAMDATA\Netbird"

Build docs developers (and LLMs) love

Get started for freeTalk to us