Allow background activity for iOS app

[SystemFuchs]

Summary

Currently the iOS version of Pangolin gets disconnected after idling some time. It would be great if the app would run in the background like the original Wireguard client or e.g. Tailscale

Motivation

Permanet access to remote sites is possible, usage of internal ressources from anywhere, usage of DNS blocking internal DNS servers, etc.

Proposed Solution

1. Info.plist Configuration

Add the required background modes:

  <key>UIBackgroundModes</key>
  <array>
      <string>network-authentication</string>
  </array>

For Network Extension-based VPNs, you also need:

  <key>NSExtension</key>
  <dict>
      <key>NSExtensionPointIdentifier</key>
      <string>com.apple.networkextension.packet-tunnel</string>
      <key>NSExtensionPrincipalClass</key>
      <string>$(PRODUCT_MODULE_NAME).PacketTunnelProvider</string>
  </dict>

2. Entitlements

Your app needs specific entitlements in your .entitlements file:

  <key>com.apple.developer.networking.networkextension</key>
  <array>
      <string>packet-tunnel-provider</string>
  </array>

For Personal VPN (older API):

  <key>com.apple.developer.networking.vpn.api</key>
  <array>
      <string>allow-vpn</string>
  </array>

3. Capabilities in Xcode

1. Open your project in Xcode
2. Select your target → Signing & Capabilities
3. Add Network Extensions capability
4. Check Packet Tunnel (for NEPacketTunnelProvider)
5. Add Personal VPN capability if using NEVPNManager

4. App ID Configuration

In the Apple Developer Portal:

1. Go to Certificates, Identifiers & Profiles
2. Edit your App ID
3. Enable Network Extensions and/or Personal VPN

Key Notes

• Network Extension VPNs (NEPacketTunnelProvider) run in a separate process and automatically stay active in the background while connected
• The system manages the VPN extension lifecycle—it launches when the tunnel starts and terminates when disconnected
• You don't need audio, location, or other background modes—the network extension framework handles background execution
• Apple requires a provisioning profile with the Network Extension entitlement, which must be requested from Apple (not automatically available)

Alternatives Considered

No response

Additional Context

No response

[miloschwartz]

Thanks for heads up. We currently use these entitlements as they're required by the system for every VPN.

It's a constant battle against the system to prevent it from getting killed and the reasons and observability are quite opaque from Apple, but we're actively working on improving this. It was fairly stable in our pre-release testing on an iPhone 15 Pro with varying levels of battery life and on and off cellular and WiFi, however performance varies a lot between devices.

Can you provide some more context on your environment? What iPhone model are you using? How old is it? How often is it killed / how long does it take? Are you on WiFi or cellular or switching often?

[SystemFuchs]

Thanks for writing such cool software :-)

I know that background processes and mobile devices is a fight against windmills ;-)

I'm currently using an iPhone 16 Pro max, iOS version 26.2

It is 6 month old. Interestingly it is now running since yesterday evening (phone was charged during the night & is on batterie since 6am now). I'll keep an eye on it & give an update.

[miloschwartz]

Thanks for this info! We're working on a couple improvements which may help. I'll be pushing out an update soon pending App Store approval and we can see if that makes a difference

[SystemFuchs]

In the early evening the client suddenly was disconnected. Perhaps you can add some kind of debug logging?

[Viable8237]

+1

I admittedly have an older iPhone model but it seems like the VPN disconnects every time when the phone is idle (and doesn't reconnect by itself but it has to be done manually).