wireguard_flutter_pro

A Flutter plugin for configuring and controlling WireGuard VPN tunnels across Android, iOS, macOS, Windows, and Linux.

Official package publisher: bgtunnel.com

Project Origin and Attribution

This is not the original upstream package.

This project is a maintained derivative of the original wireguard_flutter work:

• Original upstream repository: Caqil/wireguard_flutter
• Current maintained repository: 4bhisheksharma/wireguard_flutter_pro
• Maintainer portfolio: abhishek-sharma.com.np

Features

• Initialize and manage a WireGuard interface lifecycle.
• Start and stop tunnels using WireGuard quick config content.
• Listen to tunnel stage changes as a Dart stream.
• Query current connection stage on demand.
• Generate key pairs on supported platforms.

Supported Platforms

Platform	Minimum
Android	SDK 21+
iOS	15.0+
macOS	12.0+
Windows	7+
Linux	Any modern distro with WireGuard tools

Installation

flutter pub add wireguard_flutter_pro

Import the package:

import 'package:wireguard_flutter_pro/wireguard_flutter_pro.dart';

Quick Start

import 'package:flutter/foundation.dart';
import 'package:wireguard_flutter_pro/wireguard_flutter_pro.dart';

final wireguard = WireGuardFlutter.instance;

const String conf = '''[Interface]
PrivateKey = <client-private-key>
Address = 10.8.0.4/32
DNS = 1.1.1.1

[Peer]
PublicKey = <server-public-key>
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25
Endpoint = <server-host>:51820
''';

Future<void> setupAndConnect() async {
  await wireguard.initialize(interfaceName: 'wg0');

  wireguard.vpnStageSnapshot.listen((stage) {
    debugPrint('VPN stage: $stage');
  });

  await wireguard.startVpn(
    serverAddress: '<server-host>:51820',
    wgQuickConfig: conf,
    providerBundleIdentifier: 'com.example.app.WGExtension',
  );
}

Future<void> disconnect() async {
  await wireguard.stopVpn();
}

For WireGuard config format details, see wg-quick documentation.

API Summary

• initialize({required String interfaceName})
• startVpn({required String serverAddress, required String wgQuickConfig, required String providerBundleIdentifier})
• stopVpn()
• refreshStage()
• stage()
• vpnStageSnapshot
• generateKeyPair()

VPN Stages

Available enum states:

• connecting
• connected
• disconnecting
• disconnected
• waitingConnection
• authenticating
• reconnect
• noConnection
• preparing
• denied
• exiting

Platform Setup

Android

• Works with both FlutterActivity and FlutterFragmentActivity hosts.
• VPN permission is requested with an ActivityResultListener flow.
• Ensure the activity remains attached while calling initialize or startVpn.

iOS and macOS

Apple platforms require a Packet Tunnel Network Extension.

Required setup:

1. Add a packet tunnel extension target (for example, WGExtension).
2. Set deployment target to iOS 15.0+ and macOS 12.0+ where applicable.
3. Add entitlements in app and extension:
   • com.apple.developer.networking.networkextension = packet-tunnel-provider
   • com.apple.security.application-groups = <your-app-group>
4. Pass providerBundleIdentifier as your extension bundle id.

If this setup is invalid, startVpn returns a FlutterError.

Windows

• Run as Administrator to create and manipulate tunnels.
• During debug, open an elevated terminal before running flutter run.

Linux

Install dependencies:

sudo apt install wireguard wireguard-tools openresolv

Notes:

• The system may prompt for your sudo password when the tunnel is manipulated.
• Do not launch your app as root (sudo flutter run), because it can break the expected tunnel flow.

FAQ and Troubleshooting

Linux: resolvconf: command not found

Install openresolv or remove DNS from your WireGuard config.

iOS/macOS: tunnel does not start

Verify:

• Packet tunnel extension target exists.
• Extension bundle id matches providerBundleIdentifier.
• Network Extension and App Group entitlements are present in both targets.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening pull requests.

License

This project is released under the MIT License. See LICENSE.

---

"WireGuard" is a registered trademark of Jason A. Donenfeld.