DEV Community

Amir Ziari
Amir Ziari

Posted on • Originally published at pub.dev

💻 Flutter V2Ray Client Desktop Plugin — V2Ray/Xray & Sing-Box VPN for Windows, macOS, Linux

#v2ray #flutter #xray #singbox

🧩 Following the success of flutter_v2ray_client (mobile), I'm excited to introduce the Desktop Edition — a premium Flutter plugin that brings V2Ray, Xray, and Sing-Box VPN/TUN capabilities to Windows, macOS, and Linux.

Ideal for developers and companies building cross-platform VPN or proxy tools.

🎥 Quick Youtube Video Demo

Watch Demo

Watch on YouTube

💎 Premium Highlights

🔒 2-Year Guarantee — Free updates & maintenance

💬 Priority Support — Fast Telegram support for all premium users

🚀 Advanced Features — Real-time stats, VPN/TUN mode, delay tests

⚠️ Need help? Contact @AmirZrDevv or open a GitHub issue. Support replies within 24 hours.

🖥️ Overview

flutter_v2ray_client_desktop lets you run V2Ray/Xray and Sing-Box (VPN/TUN) with a unified Flutter API.

It includes system proxy management, URL parsing, and real-time network stats — all in pure Dart.

Component Version
Xray Core 25.10.15
Sing-Box 1.12.10

With each Xray and Sing-Box update, you will receive new updates.

🔎 Key Use Cases

  • Build a cross‑platform VPN client with TUN/VPN and system proxy modes.
  • Parse vmess/vless/trojan/ss/socks links to valid Xray configs.
  • Show live bandwidth, totals, and uptime in your UI.
  • Run delay tests (HTTP/ICMP/TCP) to auto‑pick the fastest server.

✨ Core Features

  • 🔌 Connection Modes: proxy, systemProxy, vpn
  • 📊 Live Status: speed, totals, uptime, connection state
  • ⚙️ System Proxy Control: Windows/macOS/Linux
  • 🔒 VPN/TUN with Sing-Box
  • ⏱️ Server Delay Test: HTTP / ICMP / TCP
  • 🔗 Share-Link Parser: vmess/vless/trojan/ss/socks → Xray JSON

🌐 Platform Setup

Platform Binary Location Notes
Windows windows/resources/ Run app as Administrator for VPN mode
macOS macos/Resources/ Requires sudoPassword at runtime for VPN
Linux linux/resources/ Requires sudoPassword at runtime for VPN

⚠️ VPN mode requires admin/root privileges.

📦 Installation 

dependencies:
  flutter:
    sdk: flutter
  flutter_v2ray_client_desktop:
    git:
      url: # Replace with the actual path to your local flutter_v2ray_client_desktop directory
    # Example (uncomment and modify as needed):
    # path: /path/to/your/local/flutter_v2ray_client_desktop
Enter fullscreen mode Exit fullscreen mode

Run flutter pub get.

🚀 Quick Start 

import 'package:flutter_v2ray_client_desktop/flutter_v2ray_client_desktop.dart';

final client = FlutterV2rayClientDesktop(
  logListener: print,
  statusListener: print,
);

await client.startV2Ray(
  config: jsonConfig,
  connectionType: ConnectionType.systemProxy,
);
Enter fullscreen mode Exit fullscreen mode

Stop it:

await client.stopV2Ray();
Enter fullscreen mode Exit fullscreen mode

🧠 Logs & Status

logListener(String log)

→ Receives raw logs: "[Xray]...", "[sing-box]...".

statusListener(V2rayStatus status)

→ Fires every second:

V2rayStatus(
  state: ConnectionState.connected,
  duration: 0:02:15,
  download: 12456,
  upload: 2345,
  totalDownload: 3456789,
  totalUpload: 456789,
)
Enter fullscreen mode Exit fullscreen mode

🧩 Parser API (V2rayParser)

Convert links into full configs:

final parser = V2rayParser();
await parser.parse('vmess://...');

final fullJson = parser.json();
await client.startV2Ray(
  config: fullJson,
  connectionType: ConnectionType.systemProxy,
);
Enter fullscreen mode Exit fullscreen mode

Supported protocols:

vmess://, vless://, trojan://, ss://, socks://

🧰 API Reference (Summary)

Type Description
ConnectionType proxy, systemProxy, vpn
DelayType http, icmp, tcp
V2rayStatus Tracks speed, totals, duration
FlutterV2rayClientDesktop Main controller

❓ FAQ

  • Does VPN/TUN work on all platforms? Yes. TUN mode uses Sing‑Box. It requires admin/root privileges.
  • How do I disable the system proxy when stopping? stopV2Ray() automatically disables the system proxy or stops VPN depending on ConnectionType (see FlutterV2rayClientDesktop.stopV2Ray() in lib/flutter_v2ray_client_desktop.dart).
  • Can I query versions at runtime? Yes: getXrayVersion() and getSingBoxVersion() return core versions.
  • Which outbound does live stats track? By default it reads outbound>>>proxy uplink/downlink via Xray API (see _startStatusTimer() implementation).

⚙️ Utility Methods 

await client.setSystemProxy('socks://127.0.0.1:10808');
await client.setSystemProxy(''); // disable proxy

final delay = await client.getServerDelay(
  url: 'vmess://...',
  type: DelayType.tcp,
);

print('Delay: ${delay}ms');
Enter fullscreen mode Exit fullscreen mode

🖼 Screenshots

Android

Android Screenshot 1Android Screenshot 2

Desktop

Linux Screenshot

macOS Screenshot

Windows Screenshot

🔗 Related Links

👨‍💻 About the Author

I’m Amir Ziari, a full-stack developer passionate about privacy, VPN technologies, and Flutter performance.

I help developers build secure and reliable network apps.

🏁 Final Words

With flutter_v2ray_client_desktop, you can bring V2Ray/Xray & Sing-Box to desktop Flutter apps — with one unified API and cross-platform control.

Build your next-gen VPN or proxy tool with confidence ⚡

Top comments (0)