Skip to content
NuticastDownload

By Taha Yasin Kucuk · August 10, 2026 · Updated October 7, 2026

Netbird for iOS developers: a practical guide

Short answer: install the free Netbird app from the App Store, sign in with the same account you use on your Mac, allow the VPN configuration, and turn it on. The iPhone gets a stable IP that your Mac can reach from any network, and it shows up in netbird status alongside every other peer.

This guide covers setup on iOS, the settings worth changing, and how iOS developers use Netbird to keep debugging a device from Xcode after it leaves the office or home Wi‑Fi.

This is about installing Netbird's published iOS app so Xcode can reach a physical test iPhone — not about building Netbird's own iOS client from source.

What it is, briefly

Netbird is a newer, open-source mesh VPN built on WireGuard — the same core idea as Tailscale, with its own coordination service (self-hostable, or Netbird's own cloud) and a CLI that's just as script-friendly.

Like Tailscale, Netbird gives every device on your network a stable, routable IP that stays reachable regardless of what physical network that device is actually on. You install the client, sign in, and netbird status shows every peer's hostname and assigned IP alongside your own.

Set up Netbird on your iPhone

  1. Install the app. Search for Netbird in the App Store. It's free.
  2. Sign in. Use the same identity provider and account as on your Mac. Devices signed in under different accounts end up on different networks and can't see each other.
  3. Allow the VPN configuration. iOS asks whether Netbird may add a VPN configuration. Tap Allow and confirm with Face ID, Touch ID, or your passcode.
  4. Turn it on. Flip the switch in the app. A VPN indicator appears in Control Center and, on some devices, in the status bar.
  5. Check the peer list. The app lists every peer on your network with its Netbird IP. Your iPhone's own address is at the top.

Set up Netbird on your Mac

Install Netbird on the Mac and sign in:

brew install netbirdio/tap/netbird
netbird up

Confirm both devices show up, with hostnames and assigned IPs:

netbird status --json

This is the same list Nuticast reads from when you match a device — no extra CLI setup needed on the Mac beyond what netbird up already did.

Settings worth changing

  • Extend or disable Peer Session Expiration for your test devices. New Netbird networks default to requiring re-authentication every 24 hours for any peer added by signing in (not peers added with a setup key). When a peer's session expires it shows Login required and drops off the network until you sign in again. In the Netbird dashboard, open Settings → Authentication, and either extend the Session Expiration period (up to 180 days) or, per device, open that peer in Peers and turn off its own Session Expiration toggle.
  • Turn on Peer Approval if you're on a team. Available on Netbird's cloud plans: new peers need an admin to approve them in Peers before they get network access — worth enabling once more than one person adds devices to the network.
  • Don't use a routing/exit peer on the Mac while debugging. Routing all the Mac's traffic through another peer gets in the way of local debugging; leave it off unless you specifically need it.

Keeping Netbird connected on iOS

iOS decides when background apps run, but Netbird runs as a VPN, which iOS keeps alive much more reliably than a normal app. If the device ever seems unreachable:

  • Open the Netbird app and check that the switch is still on.
  • Check that another VPN didn't take over. iOS runs only one VPN at a time, so turning on a work VPN turns Netbird off.
  • If Peer Session Expiration is on for that device (see above) and the session lapsed, the app will prompt you to sign in again before it reconnects.
  • Low Power Mode and poor Wi‑Fi can delay reconnection after the device wakes. Opening the app usually brings it back right away.

Using Netbird to debug from Xcode on a different Wi‑Fi

Netbird gives the iPhone a fixed IP on Wi‑Fi no matter which access point it joins — which is what Nuticast uses to keep Xcode debugging that device once it leaves your Mac's Wi‑Fi. Xcode's wireless debugging only finds a device on the same local network as the Mac, because it uses Bonjour discovery, which doesn't cross networks; Netbird makes the phone reachable from anywhere, but Xcode still won't discover it on its own. The details are in why Xcode wireless debugging breaks when your iPhone leaves Wi‑Fi.

Nuticast reads your Netbird peer list the same way it reads Tailscale's, so devices show up in a picker rather than needing a pasted IP — the exception being ZeroTier, which doesn't expose peer IPs generically.

What you need:

  1. Netbird on the Mac and the iPhone, signed in to the same network.
  2. The iPhone already paired with Xcode for wireless debugging. That still happens once next to the Mac (over Wi‑Fi on iOS 27+, over USB before); Netbird doesn't replace it.
  3. The iPhone on Wi‑Fi. Cellular doesn't work.

From there, see how it works for the exact three-step pairing flow, and every alternative is compared in how to debug an iPhone in Xcode when it's on a different network.

A note on trust

Netbird's coordination service only helps peers find each other — actual traffic is peer-to-peer WireGuard, and you can self-host the coordination server if you want the whole stack under your own control. Either way, Nuticast just relays over a network you already run, not a third-party relay.

Common questions

Is Netbird free on iPhone? Yes. The iOS app is free, and Netbird's free plan currently covers up to 5 users and 100 machines — see Netbird's pricing page for current limits. Self-hosting the coordination server is free and unlimited, since Netbird is open source.

Does Netbird drain the battery? Not noticeably for most people. WireGuard is lightweight, and an idle connection sends very little traffic.

Why did my iPhone suddenly need to sign in again? Peer Session Expiration (on by default for new networks) requires periodic re-authentication for devices added by signing in. Extend or disable it per device if that's disruptive for a test phone — see "Settings worth changing" above.

Can I use Netbird and another VPN at the same time on iOS? No. iOS allows one active VPN at a time.

Does it work over cellular? Netbird itself does. Debugging from Xcode through Nuticast doesn't — the iPhone has to be on Wi‑Fi.

Prefer a different mesh VPN? Nuticast also supports Tailscale and ZeroTier.