flutter_vless — Xray/V2Ray VPN plugin for Flutter

Build cross-platform VPN and proxy apps for Android, iOS, macOS and Windows with VLESS Reality/XHTTP, VMess, Trojan, Shadowsocks, SOCKS5 and Hysteria2. Import share links, subscriptions, raw Xray JSON, Clash YAML, sing-box JSON and WireGuard profiles.

flutter_vless provides a compact Dart API for parsing share links and subscriptions, importing raw Xray JSON, Clash YAML, and sing-box JSON, generating Xray configurations, and running proxy-only or VPN/tunnel modes through native platform backends. WireGuard profiles are supported through Clash YAML and sing-box JSON imports.

The package is open source and free to use. Platform-specific setup may be required for VPN/tunnel mode. See the documentation, platform guides, and compatibility matrix.

Official Package

flutter_vless is developed and maintained by 13FOX Studio / tfox.dev.

Official package: pub.dev/packages/flutter_vless
Official publisher: pub.dev/publishers/tfox.dev
Official repository: github.com/XIIIFOX/flutter_vless
Website: tfox.dev
Listed in the official Xray-core README under Xray Wrapper: XTLS/Xray-core

Redistributions and derived packages must preserve the copyright and MIT license notices required by the license. See NOTICE and TRADEMARKS.md.

At A Glance

Platform	VPN tunnel	Proxy only	Key setup requirements
Android	✅	✅	Uses `VpnService`; supports per-app bypass through `blockedApps`.
iOS	✅	✅	Requires Network Extension, App Group, and a signed physical device for tunnel testing.
macOS	✅	✅	Requires a Packet Tunnel extension, App Group, and application signing.
Windows	✅	✅	Requires a local `xray.exe`; tunnel mode may need administrator privileges.

Protocol/profile	Clash YAML	sing-box JSON	Raw Xray JSON
VLESS Reality/XHTTP	✅	✅	✅
VMess	✅	✅	✅
Trojan	✅	✅	✅
Shadowsocks	✅	✅	✅
Hysteria2	✅	✅	✅
WireGuard	✅	✅	✅

Key Capabilities

Android 16KB page size support for modern builds.
Swift Package Manager support for iOS and macOS integration.
Android device and emulator runtime binaries delivered through the main Maven runtime AAR.
Share-link, subscription, raw JSON, Clash YAML, and sing-box import paths.
Proxy-only mode and VPN/tunnel mode.
Runtime delay checks and status tracking.
Typed Xray config helpers for more explicit advanced configuration.

Try The Example First

The example app is the quickest way to verify platform setup before copying the plugin into your own project.

If you downloaded a source archive, rename the top-level folder to flutter_vless before running the bundled example. Flutter's SwiftPM integration derives the root plugin package identity from the path dependency directory name.

cd example
flutter pub get
../tool/prepare_apple_swiftpm.sh
flutter run -d android
flutter run -d ios
flutter run -d windows

iOS needs a signed real device for VPN mode, macOS needs the generated SwiftPM metadata prepared for macOS 13.0 plus a valid Apple Team on Runner and XrayTunnel, and Windows needs example/windows/xray/xray.exe.

For macOS, open example/macos/Runner.xcworkspace, select your Apple Team on both macOS targets if signing is not already valid, then run:

flutter run -d macos

If Xcode is already open after running the prepare script, close it and reopen the workspace.

Installation

dependencies:
  flutter_vless: ^1.1.5

Then run:

flutter pub get

For a macOS app, prepare the generated Flutter SwiftPM metadata before the first build. Proxy-only apps can run only the metadata step:

dart run flutter_vless:setup_macos_vpn --prepare-only

VPN mode apps should run the full macOS setup from the platform guide.

Android emulator binaries are included in the main Android Maven runtime AAR.

Quick Start

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

final flutterVless = FlutterVless(
  onStatusChanged: (status) {
    debugPrint(
      'status=${status.state} connection=${status.connectionState.name} '
      'delay=${status.duration}s',
    );
  },
);

Future<void> connect(String shareLink) async {
  final parsed = FlutterVless.parse(shareLink);
  final config = parsed.getFullConfiguration();

  await flutterVless.initializeVless(
    providerBundleIdentifier: 'com.example.myapp',
    groupIdentifier: 'group.com.example.myapp',
  );

  if (await flutterVless.requestPermission()) {
    await flutterVless.startVless(
      remark: parsed.remark,
      config: config,
    );
  }
}

For proxy-only mode, set proxyOnly: true in startVless() and skip the VPN permission step on the paths that do not require a tunnel.

startVless() and getServerDelay() validate that the provided config is a well-formed Xray JSON object before the native layer sees it.

Supported Inputs

FlutterVless.parse() and FlutterVless.parseMany() support:

vmess://
vless://
trojan://
ss://
socks://
hysteria2://
hy2://
raw Xray JSON
base64 subscription payloads
Clash YAML
sing-box JSON

Clash YAML and sing-box JSON imports also cover supported Xray profile objects such as WireGuard and Hysteria2.

Use parse() for a single share link or a raw config, and parseMany() when you want to keep every supported profile from a subscription payload.

Advanced Usage

The parsed URL objects expose low-level Xray maps for advanced configuration work, including inbound, routing, log, and stream settings. That is intentionally powerful, but it is also intentionally low-level.

If you want a typed config builder instead of mutating maps, see lib/url/xray_config_model.dart and lib/url/xray_config_validator.dart. Those helpers are useful when you want to construct or validate a config before turning it into JSON.

If you need to edit the runtime config, start with Configuration Guide and Architecture Notes.

Example App

The bundled example app shows clipboard import, routing edits, proxy-only mode, and status tracking:

Platform Setup

Package Docs

Contributing

Read CONTRIBUTING.md before opening a pull request.

Authorship And Trademarks

flutter_vless is maintained by 13FOX Studio / tfox.dev. See AUTHORS, NOTICE, and TRADEMARKS.md for attribution and brand-use notes.

License

MIT License