Installation
- iOS
- Android
Download from App Store
Install NetBird from the Apple App Store:NetBird for iOS
Download from the App Store
Requirements
- iOS 15.0 or later
- iPhone, iPad, or iPod touch
Installation Steps
Initial Setup
Choose authentication method
- SSO Login
- Setup Key
- Tap Sign in with SSO
- Choose your identity provider (Google, Microsoft, GitHub, etc.)
- Complete the authentication in your browser
- Return to the NetBird app
Connect to your network
- Tap the Connect button
- Grant VPN permissions if prompted
- Wait for the connection to establish
App Features
Dashboard
The main screen displays:- Connection status: Connected, Disconnected, or Connecting
- NetBird IP: Your assigned mesh network IP (e.g., 100.x.x.x)
- Data transfer: Upload/download statistics
- Connected peers: List of active peer connections
Peer List
View and interact with peers:- See all peers in your network
- Check peer connection status (Direct/Relayed)
- View peer IP addresses and hostnames
- Monitor peer connection quality
Settings
Access app settings:- Auto-connect: Automatically connect on app launch
- Always-on VPN: Keep NetBird running in the background
- Management URL: Change management server (for self-hosted)
- Notifications: Configure connection notifications
- Debug logs: Enable detailed logging for troubleshooting
Mobile-Specific Considerations
Battery Optimization
- iOS
- Android
iOS manages VPN connections efficiently, but you can optimize battery life:
- Background refresh: NetBird uses VPN APIs that allow background connectivity without significant battery drain
- Low Power Mode: NetBird continues to work in Low Power Mode but may experience reduced performance
- Go to Settings → NetBird
- Enable Background App Refresh
Network Connectivity
Mobile Carrier NAT Mobile carriers often use carrier-grade NAT (CGNAT), which can make direct peer-to-peer connections difficult. NetBird automatically:- Attempts direct connection first
- Falls back to relay servers (TURN) when direct connection fails
- Maintains secure encryption regardless of connection type
- Wi-Fi ↔ Mobile data switching
- Roaming between cell towers
- Reconnection after network loss
Data Usage
Monitor NetBird’s data consumption:- iOS
- Android
- Go to Settings → Cellular
- Scroll down to NetBird
- View current period data usage
NetBird only transfers data when you access resources through the mesh network. Background keep-alive traffic is minimal.
Configuration
Management URL (Self-Hosted)
If you’re using a self-hosted NetBird instance:- Open NetBird app
- Tap Settings (or gear icon)
- Tap Management URL
- Enter your custom management server URL
- Tap Save
- Reconnect to apply changes
Custom Hostname
Set a custom device name:- Open Settings
- Tap Device Name or Hostname
- Enter your preferred name (e.g., “John’s iPhone”)
- Save and reconnect
Troubleshooting
Cannot connect to peers
Cannot connect to peers
Check network permissions:
- Ensure VPN permissions are granted
- Check if NetBird is allowed through firewall (if using VPN/Firewall apps)
- Disconnect and reconnect
- Check peer status in the app
- Ensure peers are online
- Mobile carrier NAT may require relay connections
- Check if you see “Relayed” connection type (this is normal)
VPN permission errors
VPN permission errors
iOS:
- Go to Settings → General → VPN & Device Management
- Remove any existing NetBird VPN configurations
- Reopen NetBird and grant permissions again
- Go to Settings → Network & Internet → VPN
- Remove NetBird configuration
- Reopen NetBird and grant permissions again
App keeps disconnecting
App keeps disconnecting
iOS:
- Enable Background App Refresh for NetBird
- Check if Low Power Mode is affecting connectivity
- Disable battery optimization for NetBird
- Enable Always-on VPN in Android settings
- Check manufacturer-specific battery settings (Samsung, Xiaomi, etc.)
High battery drain
High battery drain
- Check if you’re connected to many peers
- Reduce background refresh frequency
- Consider using auto-connect only on Wi-Fi
- Check for app updates (newer versions may improve efficiency)
SSO login fails
SSO login fails
- Ensure you have a stable internet connection
- Try using a setup key instead
- Clear app cache and try again
- Check if your browser blocks pop-ups
Cannot access local network resources
Cannot access local network resources
- Verify DNS settings in NetBird dashboard
- Check if routes are properly configured on management server
- Ensure target resources allow connections from your NetBird IP
Enable Debug Logs
- iOS
- Android
- Open NetBird app
- Go to Settings
- Enable Debug Logging
- Reproduce the issue
- Share logs from Settings → Share Logs
Limitations
Mobile clients have some limitations compared to desktop clients:- SSH access: Mobile apps don’t support SSH server functionality
- Network routing: Cannot act as routing peers (gateway/exit nodes)
- Custom DNS resolvers: Limited DNS configuration options
- Kernel WireGuard: iOS always uses userspace WireGuard; Android may use kernel or userspace depending on device
Best Practices
Use Setup Keys
For easier onboarding, use setup keys instead of SSO on mobile devices.
Enable Auto-Connect
Configure auto-connect to ensure your device is always protected.
Monitor Data Usage
Keep an eye on data consumption, especially on mobile networks.
Update Regularly
Keep the app updated for the latest features and security patches.
Getting Help
If you encounter issues not covered here:- Check the NetBird Community Forum
- Join the NetBird Slack
- Report bugs on GitHub Issues