Start using NetBird at netbird.io
See Documentation
Join our Slack channel

NetBird iOS & tvOS Client

The NetBird iOS/tvOS client allows connections from mobile devices running iOS 14.0+ and Apple TV running tvOS 17.0+ to private resources in the NetBird network.

Install

You can download and install the app from the App Store:

Screenshots

Reporting bugs and requesting features

NetBird uses a discussion-first workflow across all its repositories. Bug reports and feature requests for the iOS and tvOS client start in netbird Discussions, not as issues here.

What you want to do	Where to go
Report a bug, regression, or unexpected behavior	Issue Triage
Request a feature or share an idea	Ideas & Feature Requests
Ask about setup, configuration, or self-hosting	Q&A / Support
Report a security vulnerability	Security policy, never a public thread

Our team triages each discussion. Validated reports become issues in this repository, linked back to the discussion. See How to use Discussions, Issues, and Pull Requests for the full workflow.

Code structure

The code is divided into 4 parts:

• The main netbird Go code, included as a git submodule at /netbird-core from the NetBird repo, compiled into an xcframework. This contains most of the client logic.
• The network extension /NetbirdNetworkExtension that is running in the background where the compiled Go code is executed.
• The UI and app code under /NetBird
• The /NetbirdKit/NetworkExtensionAdapter that controls the extension and builds the link between UI and extension

Requirements

• iOS 14.0+ / tvOS 17.0+
• Xcode 16.1+
• Go (version determined by the netbird submodule's go.mod)
• gomobile (for iOS builds)
• gomobile-netbird (for tvOS builds — NetBird's fork with tvOS support)

gomobile

For iOS-only builds, install the standard gomobile:

go install golang.org/x/mobile/cmd/gomobile@latest

gomobile-netbird

For tvOS builds, install gomobile-netbird, NetBird's fork of gomobile that adds tvOS support. See: https://github.com/netbirdio/gomobile-tvos-fork

go install github.com/netbirdio/gomobile-tvos-fork/cmd/gomobile-netbird@latest

Run locally

The main netbird Go code is included as a git submodule at netbird-core/.

git clone --recursive https://github.com/netbirdio/ios-client.git
cd ios-client

If you already cloned without --recursive:

git submodule update --init --recursive

Build the XCFramework for iOS:

./build-go-lib.sh

Or for tvOS (includes iOS, iOS Simulator, tvOS, and tvOS Simulator targets):

./build-go-lib.sh --tvos

You can also pass an explicit version:

./build-go-lib.sh 0.2.0
./build-go-lib.sh --tvos 0.2.0

Open the Xcode project, and we are ready to go.

Updating the netbird submodule

To update to a newer netbird version:

cd netbird-core
git fetch --tags
git checkout v0.x.y   # or any branch/commit
cd ..
git add netbird-core
git commit -m "update netbird submodule to v0.x.y"

Running on iOS Device

Note: The app cannot run in the iOS simulator. To test the app, a physical device needs to be connected to Xcode via cable and set as the run destination.

Running on Apple TV

Note: The app cannot run in the tvOS simulator. To test the app, a physical device running tvOS 17.0 or later needs to be paired with Xcode.

Firebase Configuration (Optional)

The app supports Firebase for analytics and crash reporting. To enable it, add your GoogleService-Info.plist file to the project root. The app will work without Firebase configuration.

Other project repositories

NetBird project is composed of multiple repositories:

• NetBird: https://github.com/netbirdio/netbird, contains the code for the agents and control plane services.
• Dashboard: https://github.com/netbirdio/dashboard, contains the Administration UI for the management service
• Documentations: https://github.com/netbirdio/docs, contains the documentation from https://netbird.io/docs
• Android Client: https://github.com/netbirdio/android-client
• iOS/tvOS Client: https://github.com/netbirdio/ios-client (this repository)