TurnBridge

TurnBridge is annetwork utility. It allows you to securely route your iOS network traffic through TURN servers and WireGuard / Amnezia WG endpoints.

To run the application, you must use a server running on a VPS.

The project is based on the repositories listed in the Acknowledgments section.

✨ Features

• Custom Routing: Route your traffic through specific TURN protocols and WG endpoints.
• WireGuard & Amnezia WG Integration:
  • Complete WireGuard protocol support with key management, routing, and DNS configuration
  • Full Amnezia WireGuard obfuscation support including jitter parameters (Jc, Jmin, Jmax), packet size obfuscation (S1-S4), and magic headers (H1-H4)
• 1-Click Import: Quickly import complex configurations via base64-encoded clipboard links (turnbridge://).
• Multi-Profile Management: Create, edit, and seamlessly switch between multiple VPN configurations using a convenient dropdown picker.

📸 Screenshot

🚀 Installation & Build

To build and run TurnBridge locally, you need a macOS environment with Xcode installed, as well as Go (for compiling the WireGuard/TURN bridge).

⚠️ Important: TurnBridge uses a Network Extension (VPN). Signing with a free Apple ID (via standard AltStore or Sideloadly) will not work because free accounts lack the required VPN entitlements. You must use a paid Apple Developer account ($99/year) or a third-party paid signing service.

1. Clone the repository:

   git clone https://github.com/nullcstring/turnbridge.git
   cd TurnBridge

2. Build the Go Bridge: Ensure you have Go installed (brew install go).

Modify the Go path in the script at script/build_wireguard_go_bridge.sh, according to your setup. Refer to this Stack Overflow answer for guidance.

3. Open the project in Xcode: Open TurnBridge.xcodeproj (or .xcworkspace if applicable) in Xcode.
4. Configure Code Signing:

• Select the TurnBridge project in the Project Navigator.
• Go to the Signing & Capabilities tab.
• Select your personal Apple Developer Team.
• Ensure you update the Bundle Identifier (for both the main app and the network-extension target) to match your team provisioning profile.

5. Build and Run: Select your target device (iPhone/iPad) and press Cmd + R to build and run the app.

📲 Install Pre-built IPA (No Xcode Required)

If you don't have a Mac or Xcode, you can download the pre-built unsigned IPA from the Releases page and sign it yourself.

Signing & Installation

Manual Installation Tools: If you already possess a paid Apple Developer certificate (or bought one from the services above), you can sign and install the IPA yourself using:

Tool	Requirement
KravaSign	⚠️ Without a developer certificate, price $10 #2 (comment)
GBox	Paid Certificate Needed
ESign	Paid Certificate Needed

🛠 Usage (Configuration Import)

TurnBridge uses a specific JSON structure encoded in Base64 for fast configuration imports for WireGuard / Amnezia WG.

Configuration JSON Structure

{
  "turn": "https://vk.com/call/join/...",
  "peer": "SERVER_IP:PORT",
  "listen": "127.0.0.1:9000",
  "n": 1,
  "wg": "[Interface]\nPrivateKey = ...\nAddress = 10.100.0.2/32\nDNS = 8.8.8.8\nMTU = 1280\n\n[Peer]\nPublicKey = ...\nAllowedIPs = 0.0.0.0/0\nEndpoint = 127.0.0.1:9000\nPersistentKeepalive = 25"
}

Generate a Quick Import Link

You can use the included quick_link.py script to easily generate valid turnbridge:// clipboard links.

1. Open quick_link.py in your text editor and replace the placeholder values in the config dictionary with your actual server parameters and WireGuard keys.

2. Run the script from your terminal:

   python3 quick_link.py

3. Copy the generated turnbridge://... link from the terminal output to your iOS clipboard.

4. Open TurnBridge, tap the + icon, select Paste from Clipboard, and tap Connect.

☕ Support My Work

If TurnBridge saved you some time, consider supporting its development! As an independent open-source project, any contribution is greatly appreciated.

Crypto:

• TON: UQBisIcwzfQz5Rj0TofZhN2CSZXvUhQrwMmTGEiSSa9ErW5b

Thank you for keeping the open-source spirit alive! 🚀

License

TurnBridge is released under the GNU General Public License v3.0.

Copyright (C) 2026 nullcstring

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

---

Acknowledgements

This project was made possible thanks to the work of the open-source community. It includes code and concepts from the following excellent repositories:

• WireGuard-Apple — Licensed under MIT / GPL.
• Wireguardkit — Licensed under MIT / GPL.
• vk-turn-proxy — Licensed under the GNU GPL.
• Amneziawg-Apple — Licensed under MIT.