# Singcast: a Flutter proxy client that unifies Clash, sing-box and v2ray subscriptions

> Singcast is a Dart client built around a customized sing-box core, importing Clash, sing-box and v2ray subscription formats and converting them all to a sing-box config on import, with the core split from the UI differently on desktop and on Android.

**mapleafgo/singcast** — Multi-platform proxy client powered by sing-box, with full Clash, sing-box & v2ray subscription support

- Repository: https://github.com/mapleafgo/singcast
- Website: https://mapleafgo.github.io/singcast/
- Stars: 1,026 · Forks: 145
- Language: Dart
- License: GPL-3.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/mapleafgo-singcast

## One import path for three subscription ecosystems

Singcast is an open source multi-platform proxy client built with Flutter and powered by a customized sing-box core.

The headline capability is the import. It fully supports Clash, sing-box and v2ray subscriptions, and the config file formats those come in, yaml, yml, json and txt, as well as v2ray base64 and URI list subscriptions. All of them are unified to a sing-box config on import, so the client only has to speak one configuration dialect internally. The project's phrasing is that you import and go.

The rest of the feature list is what you would expect from a desktop client: system proxy and TUN mode, proxy node selection with latency testing, real-time traffic statistics, subscription management with import and update of subscription links, a log viewer with export, and a system tray on desktop.

The platform list is Windows, Linux, macOS and Android, and iOS is explicitly not supported. That is a real constraint, and the repository still has an ios/ directory at the top level, so the Flutter project structure includes the platform even though the client is not offered there.

The project is GPL-3.0 licensed, the default branch is named singcast rather than main, the homepage is at mapleafgo.github.io/singcast, and the last push was on 2026-10-13 with v1.3.1 published the same day, after v1.3.0 and a v1.3.0-beta1 a few days earlier.

## The core runs differently on desktop and on Android

The most interesting structural decision in the project is how the sing-box core is hosted, and the two platforms get different treatment for a reason.

On desktop, the core runs as an independent privileged process communicating over JSON-RPC, which the documentation describes as IPC. The effect is that the UI stays sandboxed and stable: a Flutter UI process that could crash or be killed by the desktop environment does not take the proxy down with it, and the core keeps running.

On Android, the core is loaded as a native library via FFI and integrated with the Android VPN service. The reason is platform mechanics. On Android, a VPN service is a system facility, and the process hosting it has particular lifecycle rules, so loading the core as a library inside the app is the arrangement that works with the VPN service integration.

That difference is also visible in the file layout the build instructions ask for. The core goes in different places depending on the role:

```shell
# Desktop (IPC standalone process)
windows/core/singcast-core.exe
linux/core/singcast-core
macos/Frameworks/singcast-core

# Mobile (FFI native library)
 android/app/libs/libsingcast.aar
```

So a desktop build expects a standalone executable, named singcast-core.exe on Windows, singcast-core on Linux, and singcast-core inside a Frameworks directory on macOS, while the Android build expects a native library packaged as an.aar under the app's libs directory.

The Dart packages in the tech stack support that design. dart_ipc is the IPC layer, ffi is the interface to the native library, and the rest are ordinary Flutter packages: signals_flutter for reactive state, go_router for navigation, window_manager for desktop window behaviour and desktop_tray for the system tray.

## TUN mode, and what the system proxy alternative costs

TUN mode is the feature that distinguishes this from a plain system proxy client. The project describes it as a transparent proxy with automatic route management, with no manual system proxy setup needed.

The distinction matters in practice. A system proxy configuration means the browser and the applications that honour the OS proxy setting route through the client, and the applications that do not, which is most of them, do not. A TUN device sits below that layer and captures traffic by interface, so applications that ignore the proxy setting are covered too. The price of that coverage is that the client is manipulating routing, which needs elevated permissions and which is why the desktop core runs as a privileged separate process rather than inside the UI.

So the two modes in the feature list, system proxy and TUN mode, are not equal alternatives. TUN is the more complete one, and it is the one that needs the privileged process and the route management that the core provides.

On Linux there is one dependency to install before the client works, and it is specific:

```bash
sudo apt-get install libayatana-appindicator3
```

That is the AppIndicator library, which provides the system tray interface on Linux desktops. The project says to make sure to install it before using the client, and it is worth following that instruction literally, because a missing tray library tends to show up as a silently absent feature rather than as an error message.

## Building it, and where the core comes from

The build is a Flutter build with a core that you supply separately, and the documentation is explicit that the core is downloaded rather than compiled from this repository.

The first step is the toolchain, Flutter v3.41 or newer, with the official Flutter documentation for the environment setup and the target platform, and Android SDK if the target is Android.

The second step is the core. You download the core for your platform from the singcast-cli releases and place it at one of the paths listed above, and the file is a shell block with a comment per platform. Because the core is a customised sing-box build rather than the upstream one, it comes from the singcast-cli project rather than from SagerNet, and the app will not work with a stock sing-box binary dropped in its place.

The third step is the standard Flutter sequence:

```shell
# Install dependencies
flutter pub get
# Generate code
dart run build_runner build
# Run
flutter run -d linux
```

The build_runner step is there because the project uses code generation, which is consistent with the signals_flutter dependency. The Taskfile.yml at the repository root is the task runner, and there are structure description files alongside it, adapter-structure.yml, outbound-structure.yml and github-repo-structure.yml, which is a sign of a project large enough that its own layout needs documenting.

The top level also carries a build.yaml, which is the Dart build configuration for code generation, pubspec.yaml and pubspec.lock, analysis_options.yaml for the linter, and a test directory.

## The subscription fetch failure, and the User-Agent that causes it

The FAQ section documents one problem, and it is worth reading because it is the failure you are most likely to hit.

If the subscription keeps loading or returns an error, the cause may be that the provider is restricting certain User-Agent strings. The fix is to change the User-Agent under Settings, General, Subscription User-Agent, with the examples given being clash-verge/v2.0.0 and clash-meta, and then update the subscription again.

This is a small but instructive detail. A subscription URL is fetched with an HTTP client that identifies itself, and providers differ in which clients they will serve. The default User-Agent of the client may be one that the provider refuses, and the symptom is a subscription that never loads. The workaround is to tell the server which client you are, which is a reasonable thing to do and also a slightly uncomfortable one, since it means your request identifies as another product.

The broader point for an adopter is that Singcast talks to a third-party service on your behalf, and the provider's response depends on how you identify. If a subscription is important to you, a client that can serve a plain default User-Agent and let the provider behave consistently is easier to reason about than one whose default is refused.

The project also runs a Telegram group, linked from the README, and ships the documentation site at mapleafgo.github.io/singcast, with a home page screenshot in the docs images directory.

## Conclusion

Singcast fits a user who has subscriptions in more than one format, especially Clash or v2ray ones, and wants a single client that imports them and hands the result to a sing-box core, and it fits someone who wants TUN mode without hand-editing system proxy settings. It is a poor fit on iOS, which the project states is not supported, and a poor fit if you want to run the stock sing-box core, since this one is customized. Before adopting, check that your subscription provider accepts the User-Agent you set under Settings, General, Subscription User-Agent, and install libayatana-appindicator3 on Linux before the first run or the system tray will be missing.

## FAQ

### What is Singcast and what does it do?

Singcast is an open source multi-platform proxy client built with Flutter and powered by a customized sing-box core. It fully supports Clash, sing-box and v2ray subscriptions and config files in yaml, yml, json and txt, as well as v2ray base64 and URI list subscriptions, and unifies them all to a sing-box config on import.

### Which platforms does Singcast support?

Windows, Linux, macOS and Android. iOS is not supported, even though the Flutter project still contains an ios/ directory at the top level of the repository.

### How does Singcast run the sing-box core on desktop and on Android?

On desktop the core runs as an independent privileged process communicating via JSON-RPC, which keeps the UI sandboxed and stable. On Android the core is loaded as a native library via FFI and integrated with the Android VPN service, placed at android/app/libs/libsingcast.aar.

### What is TUN mode in Singcast?

TUN mode is a transparent proxy with automatic route management, so no manual system proxy setup is needed. It is available alongside the system proxy mode in the feature list, and it is the mode that needs the privileged core process on desktop.

### My subscription fetch keeps failing in Singcast, what should I check?

The provider may be restricting certain User-Agent strings. Change the UA in Settings, General, Subscription User-Agent, for example to clash-verge/v2.0.0 or clash-meta, and then update the subscription again. On Linux, also install libayatana-appindicator3 before using the client.

## Sources

- [License: GPL-3.0](https://github.com/mapleafgo/singcast/blob/singcast/LICENSE)
- [mapleafgo/singcast on GitHub](https://github.com/mapleafgo/singcast)
- [Project website](https://mapleafgo.github.io/singcast/)
- [README](https://github.com/mapleafgo/singcast/blob/singcast/README.md)
- [Releases](https://github.com/mapleafgo/singcast/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mapleafgo-singcast