AfrikTeckMesh iOS & tvOS Client

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

Install

Build the app from source with Xcode. See the build sections below.

Reporting bugs and requesting features

AfrikTeckMesh uses a discussion-first workflow across all its repositories. Bug reports and feature requests for the iOS and tvOS client start in afrikteckmesh 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 afrikteckmesh Go code, included as a git submodule at /afrikteckmesh-core from the AfrikTeckMesh repo, compiled into an xcframework. This contains most of the client logic.
• The network extension /AfrikteckmeshNetworkExtension that is running in the background where the compiled Go code is executed.
• The UI and app code under /AfrikTeckMesh
• The /AfrikteckmeshKit/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 afrikteckmesh submodule's go.mod)
• gomobile (for iOS builds)
• gomobile-afrikteckmesh (for tvOS builds — AfrikTeckMesh's fork with tvOS support)

gomobile

For iOS-only builds, install the standard gomobile:

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

gomobile-afrikteckmesh

For tvOS builds, install gomobile-afrikteckmesh, AfrikTeckMesh'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-afrikteckmesh@latest

Run locally

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

git clone --recursive https://githubafrik.afrikteck.com/root/afrikteckmesh-ios.git
cd afrikteckmesh-ios

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 afrikteckmesh submodule

To update to a newer afrikteckmesh version:

cd afrikteckmesh-core
git fetch --tags
git checkout v0.x.y   # or any branch/commit
cd ..
git add afrikteckmesh-core
git commit -m "update afrikteckmesh 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.

Verifying iOS network reconnection

Network changes are sent to the Go SDK's network event manager, which suspends retries while offline and refreshes stale connections after a handover. The iOS extension observes physical interfaces, IPv4 addresses, IPv6 network prefixes, gateways, IP-family availability and the active data SIM; a SIM switch can retain the same cellular interface. Paths marked requiresConnection allow dialing so the connection can activate the network. After initial connection, the SDK’s Connecting and NoNetwork states set iOS’s reasserting status; SDK connection success clears it. Stopping the tunnel or failing authentication also clears it. The app displays “No network” for the SDK’s NoNetwork state and “Reconnecting…” while reconnecting, and keeps the disconnect control available. Wake reconciles the current physical path without forcing a refresh when it is unchanged. Healthy sockets stay open; the core's normal liveness checks recover connections that actually expired.

The existing core sweep refreshes management, signal and relay connections. ICE/P2P cleanup and the sweep timing are unchanged; P2P is disabled by default on mobile to limit battery usage. Policy restarts interrupted by an outage resume when the physical network returns.

“Connected” reflects management/signal connectivity, not proof that every peer or routed resource is reachable. Verify actual traffic in the checks below.

Run NetworkReconnectionStateTests for event deduplication, rapid SIM changes, offline recovery, wake handling, path capabilities, app reassertion and shutdown behavior. End-to-end handovers require a physical dual-SIM iPhone:

1. Connect the VPN and continuously access a private peer or routed resource.
2. With Wi-Fi disabled, switch Cellular Data from SIM A to SIM B and back. Repeat with Allow Cellular Data Switching enabled and the app in the background. Receive a regular voice call on the non-data SIM, keep traffic running, then end the call and verify recovery as data returns to the original SIM. Repeat with switching disabled: an outage during the call is expected, but recovery after the call must not require toggling the VPN.
3. Test Wi-Fi → cellular → Wi-Fi and airplane mode → recovery on the same SIM.
4. Repeat with an exit node selected; verify both private and Internet traffic recover.
5. Switch between two Wi-Fi networks, including networks with the same local subnet; test IPv6-only/NAT64 and dual-stack networks.
6. Lock the phone, let it sleep, then wake on the same and on a different network. Repeated wakes on an unchanged path must not cause network-change sweeps.
7. Verify that genuinely expired credentials still trigger login and remove the tunnel routes. Offline startup authentication is a separate change.
8. Disconnect the VPN during a handover and verify it stays disconnected with On Demand disabled.

Check the extension log for Network event: and the core's network change: connections marked stale messages. Simulator tests cannot validate carrier handovers or live VPN traffic.

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. For a local device build without Firebase, omit this file from the targets’ Copy Bundle Resources phases. The CI test placeholder is not a production Firebase configuration. Startup skips missing or invalid Firebase settings; unit tests also skip Firebase initialization.

Other project repositories

AfrikTeckMesh project is composed of multiple repositories:

• AfrikTeckMesh: https://githubafrik.afrikteck.com/root/afrikteckmesh, contains the code for the agents and control plane services.
• Dashboard: https://githubafrik.afrikteck.com/root/afrikteckmesh-dashboard, contains the Administration UI for the management service
• Documentations: https://githubafrik.afrikteck.com/root/afrikteckmesh-docs, contains the documentation from https://afrikteck.com/docs
• Android Client: https://githubafrik.afrikteck.com/root/afrikteckmesh-android
• iOS/tvOS Client: https://githubafrik.afrikteck.com/root/afrikteckmesh-ios (this repository)

Network events include their source (path, dataSIM, or wake) and whether they were unchanged, initial, unavailable, recovered, or changed. AppLogger adds timestamps; no SIM identifiers or address values are added to these diagnostics.