flutter_singbox_client

A Flutter plugin for integrating the Sing-box core into applications with a clean, stateless, event-driven Dart API.

Lightweight · Stateless · Engine-focused

---

Features

Feature	Description
🔒 VPN Mode	Full device-wide TUN tunnel via Android VpnService
🌐 Proxy Mode	HTTP/SOCKS proxy without a TUN device, no permission required
⚔️ Clash API	Runtime mode switching and outbound group control with latency testing
📱 Per-App Proxy	Include or exclude specific apps from the tunnel (split tunneling)
🌍 System Proxy	Register HTTP inbound as device-wide proxy on Android Q+
🔑 Kill Switch	Block all traffic at the OS level when the tunnel is down
📊 Live Traffic	Real-time upload/download speeds and session totals at ~1 Hz
🔌 Connection Tracking	Full per-connection metadata, lifecycle, and close control
📋 Live Logs	Real-time Go core log streaming with per-level filtering
⚠️ Fault Alerts	Dedicated fault stream for actionable service errors
🧠 Memory Limits	Go runtime soft memory cap (GOMEMLIMIT) with optional connection kill
🧪 Network Testing	Built-in STUN (NAT type, latency) and network quality (speed, RPM) tests
✅ Config Validation	Go core validation and JSON formatting before connecting
🔄 Hot Reload	Reload config without restarting the service or dropping connections
🚀 Boot Auto-start	Boot broadcast relay so your app can reconnect after device restart
📦 Zero Persistence	No database, no shared preferences, no file I/O for user data

---

Screenshots

Home	Logs	Network Test

Per-App Proxy	Settings	Settings (2)

---

Sing-Box Supported Protocols & Features

VMess · VLESS · Trojan · Shadowsocks · Hysteria2 · TUIC · WireGuard · ShadowTLS · AnyTLS · Naive · Tor · SSH

Includes full support for V2Ray transports (WebSocket, gRPC, HTTPUpgrade, QUIC), TLS security (uTLS, Reality, ECH, ACME), FakeIP DNS, rule-based routing, and anti-censorship obfuscation.

➡️ See Supported Protocols & Features for the complete reference.

---

Supported Platforms

Platform	Status	Core	Availability
Android	✅ Done	Sing-box 1.14.0-alpha.20	Free
iOS	🔧 In Development	—	Coming Soon
macOS	🔧 In Development	—	Coming Soon
Windows	🗓 Planned	—	—
Linux	🗓 Planned	—	—

---

Requirements

Requirement	Minimum
Flutter SDK	>=3.19.0
Dart SDK	>=3.3.0
Android minSdk	23 (Marshmallow)
Android compileSdk	35
Java target	17

---

Installation

1. Add the dependency (pubspec.yaml):

dependencies:
  flutter_singbox_client: ^1.0.0

2. Configure Android Gradle (android/app/build.gradle):

android {
    compileSdk 35
    defaultConfig { minSdk 23 }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions { jvmTarget = "17" }
}

3. Permissions — declared in the SDK manifest and merged automatically. See Android Permissions for optional and sensitive permissions.

---

Quick Start

import 'package:flutter_singbox_client/flutter_singbox_client.dart';

final client = SingboxClient();

// Initialize once at app startup
await client.initialize();

// Request VPN permission (VPN mode only)
if (!await client.requestVPNPermission()) return;

// Validate config — throws with the Go core's error message on failure
try {
  await client.checkConfig(myConfigJson);
} catch (e) {
  showError('$e');
  return;
}

// Connect
await client.connect(SessionOptions(
  config: myConfigJson,
  networkMode: NetworkMode.vpn,
  notification: NotificationConfig(
    title: 'My VPN',
    showTrafficStats: true,
    showStopButton: true,
    stopButtonLabel: 'Disconnect',
  ),
));

// Subscribe to live events
client.serviceStateStream.listen((state) => print('State: $state'));
client.trafficStatsStream.listen((s) => print('↑${s.uplinkBps} ↓${s.downlinkBps}'));
client.faultStream.listen((error) => showSnackbar(error));

// Disconnect
await client.disconnect();

---

VPN Mode vs Proxy Mode

Select the operating mode via SessionOptions.networkMode.

	VPN Mode	Proxy Mode
Android service	VpnService	Foreground Service
TUN device	✅	❌
Traffic capture	System-wide at OS level	Manual (apps must use the proxy)
VPN permission required	✅	❌
Kill switch	✅	❌
System proxy	✅ (Android Q+)	❌
Per-app routing	✅	❌
tun inbound in config	Required for auto-route	Must not be present

Use NetworkMode.vpn when your config uses "type": "tun" or "auto_route": true, or when you need kill switch, per-app routing, or system proxy.

Use NetworkMode.proxy when you only need HTTP/SOCKS proxy ports without requesting VPN permission.

---

Documentation

Guide	Contents
Getting Started	Initialization, lifecycle, config validation, traffic, outbound groups, Clash mode, connections, network testing, system proxy, boot
API Reference	All methods and event streams
Data Models	Field reference for every SDK type
Best Practices	Integration patterns, pitfalls, and a full example
Supported Protocols & Features	All Sing-box protocols, transports, TLS, DNS, routing, and obfuscation
Android Permissions	Required, optional, and sensitive permissions
Troubleshooting	Common errors and fixes

---

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

---

Attribution

This project uses third-party libraries and resources. See ATTRIBUTION.md for details.

---

Donation

If you liked this package and want to accelerate the development of iOS and desktop platform support, consider supporting the project with a donation. Your contributions will directly help bring flutter_singbox_client to more platforms faster.