Windows Client

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.

Run the installer

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

Follow the installation wizard

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

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

Locate the NetBird icon

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

Connect to your network

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

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:

Start the NetBird service

netbird service install
netbird service start

The service is usually started automatically during installation.

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>

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:

Press Win + R
Type services.msc and press Enter
Find Netbird in the list
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:

Variable	Description	Example
`NB_MANAGEMENT_URL`	Management server URL	`https://api.netbird.io`
`NB_LOG_LEVEL`	Logging level	`info`, `debug`, `error`
`NB_LOG_FILE`	Log file path	`C:\ProgramData\Netbird\client.log`
`NB_INTERFACE_NAME`	WireGuard interface name	`wt0`
`NB_WIREGUARD_PORT`	WireGuard listening port	`51820`
`NB_CONFIG`	Config file path	`C:\ProgramData\Netbird\config.json`
`NB_DAEMON_ADDR`	Daemon socket address	`tcp://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

System tray app not responding

Restart the service:

netbird service restart

If the problem persists:

netbird service stop
netbird service uninstall
netbird service install
netbird service start

Service won't start

Check if the service is installed:

Get-Service -Name "Netbird"

View detailed service status:

netbird service status

Check Windows Event Viewer:

Press Win + X
Select Event Viewer
Navigate to Windows Logs → Application
Look for NetBird-related errors

Connection timeout

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

WireGuard interface errors

Check if WireGuard driver is installed:

Get-NetAdapter | Where-Object {$_.InterfaceDescription -like "*WireGuard*"}

Reinstall NetBird if the driver is missing.

Permission denied errors

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

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

Uninstalling

Stop and uninstall the service

netbird service stop
netbird service uninstall

Uninstall via Control Panel

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

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"

Get Started

Architecture

Deployment

Client Setup

Network Management

Security

Operations

Installation

Download the MSI Installer

Initial Setup

Using the System Tray App

Using the Command Line

Service Management

Configuration

Config File Location

Log Files

Environment Variables

Command-Line Options

Windows-Specific Features

Network Monitor

Windows Firewall

Run as Administrator

Advanced Configuration

Running in Foreground Mode

Custom External IP Mapping

Disable Auto-Connect

Service Reconfiguration

Troubleshooting

Check Connection Status

Common Issues

Debug Bundle

Updating NetBird

Automatic Updates

Manual Update

Uninstalling

Alternative: Uninstall via MSI

Clean Uninstall

​Installation

​Download the MSI Installer

​Initial Setup

​Using the System Tray App

​Using the Command Line

​Service Management

​Configuration

​Config File Location

​Log Files

​Environment Variables

​Command-Line Options

​Windows-Specific Features

​Network Monitor

​Windows Firewall

​Run as Administrator

​Advanced Configuration

​Running in Foreground Mode

​Custom External IP Mapping

​Disable Auto-Connect

​Service Reconfiguration

​Troubleshooting

​Check Connection Status

​Common Issues

​Debug Bundle

​Updating NetBird

​Automatic Updates

​Manual Update

​Uninstalling

​Alternative: Uninstall via MSI

​Clean Uninstall

Installation

Download the MSI Installer

Initial Setup

Using the System Tray App

Using the Command Line

Service Management

Configuration

Config File Location

Log Files

Environment Variables

Command-Line Options

Windows-Specific Features

Network Monitor

Windows Firewall

Run as Administrator

Advanced Configuration

Running in Foreground Mode

Custom External IP Mapping

Disable Auto-Connect

Service Reconfiguration

Troubleshooting

Check Connection Status

Common Issues

Debug Bundle

Updating NetBird

Automatic Updates

Manual Update

Uninstalling

Alternative: Uninstall via MSI

Clean Uninstall