flutter_vless 1.1.3

Xray/V2Ray Flutter plugin for VLESS, VMESS, Trojan, Shadowsocks, SOCKS, proxy-only, and VPN tunnel flows on Android, iOS, macOS, and Windows.

flutter_vless

Federated Flutter plugin for VLESS, VMESS, Trojan, Shadowsocks, and SOCKS on Android, iOS, macOS, and Windows.

This package exposes a small Dart API for parsing share links and subscriptions, generating Xray configs, and starting either proxy-only or VPN/tunnel mode through platform backends.

The package is open source and free to use, with Android, iOS, macOS, and Windows support included out of the box. The longer guides live under doc/. For long-form docs, see the documentation link in pubspec.yaml.

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	Mode	Notes
Android	VPN, proxy-only	blockedApps is supported. The Maven runtime AAR includes device and emulator ABIs.
iOS	VPN, proxy-only	Real device required for packet-tunnel testing. App Group and Network Extension are required.
macOS	VPN, proxy-only	Packet Tunnel setup is required. See the macOS architecture notes for route and DNS details.
Windows	VPN, proxy-only	Xray must be available locally. Admin rights may be required for tunnel mode.

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.

Recommended Reading

1. New user setup: Getting Started
2. Platform setup: Platform Guides
3. Public API contract: API Contract
4. Practical scenarios: Examples
5. Config formats and advanced editing: Configuration Guide
6. Compatibility and limits: Compatibility
7. Security and runtime boundaries: Security
8. If something fails: Troubleshooting

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.3

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:

• example/README.md
• example/lib/main.dart

Platform Setup

• Android
• iOS
• macOS
• Windows

Package Docs

• Docs index
• Getting Started
• API Contract
• Examples
• Configuration Guide
• Compatibility
• Security
• Architecture Notes
• Protocol Support Roadmap
• Real-Device VPN Matrix
• Troubleshooting

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