# Sing-Box Windows is a desktop shell around the sing-box core

> Sing-Box Windows is a Tauri 2 and Vue 3 client for the sing-box core, handling subscription import, proxy mode switching, kernel management and tray integration on Windows, Linux and macOS. It suits users who want a GUI over a sing-box setup, and it depends on a separate kernel binary it manages for you.

**xinggaoya/sing-box-windows** — 🚀 现代化 sing-box 跨平台桌面客户端｜订阅导入・代理模式切换・运行态监控・托盘自动启动｜基于 Tauri 2 + Vue 3 + Rust｜🪟 Windows / 🐧 Linux / 🍎 macOS。A modern cross-platform sing-box GUI client built with Tauri 2 + Vue 3 + Rust, with TUN/system proxy modes and multi-language UI.

- Repository: https://github.com/xinggaoya/sing-box-windows
- Stars: 899 · Forks: 72
- Language: Rust
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/xinggaoya-sing-box-windows

## The kernel is a separate thing the app fetches and manages

Sing-Box Windows is described as a modern desktop client built around the sing-box core, providing a cleaner workflow for importing subscriptions, switching proxy modes, inspecting runtime state and managing desktop integration across Windows, Linux and macOS.

The separation between the app and the core is the design fact that everything else follows from. The app does not contain sing-box. It manages it. The feature list calls this kernel management: a built-in kernel resource pipeline, version download and manual kernel import. The build pipeline has a matching piece, scripts/tauri-wrapper.mjs injects target-specific kernel resources before tauri dev or tauri build, and there are separate scripts for fetching a kernel and for fetching all of them.

That means the application and the core version can move independently, and a user can point the app at a kernel they downloaded themselves. For a project whose whole point is to make a proxy setup less fiddly, handing the core download to the user is the obvious move, since a core that is bundled into the app binary would have to be replaced by a new application release every time the core changed.

The repository acknowledges the sing-box core itself in the acknowledgements section, alongside Tauri, Vue.js, Naive UI and Vite, which is a useful reminder that this is a front end over someone else's engine.

## Three subscription formats, and they take different paths

The subscription import is the feature most users will meet first, and the documentation is precise about the formats.

Sing-box JSON is raw JSON configuration, and the app parses the top-level outbounds. Clash or Mihomo YAML is a YAML subscription where the app parses proxies and converts the supported nodes. A URI list is a text file of node links, and the supported schemes are vmess://, vless://, trojan://, ss://, hysteria2://, tuic:// and anytls://, with one or several nodes allowed in a single list.

The node types currently supported are vless, vmess, trojan, shadowsocks, shadowsocksr, socks, http, hysteria2, tuic and anytls.

The reason to care about the distinction is that a Clash YAML subscription and a sing-box JSON configuration are not the same kind of artefact, even though both end up as a set of nodes. A Clash file is a provider format that happens to be able to describe proxies, while a sing-box JSON file is the core's own configuration with outbounds at the top level. A client that accepts both is doing more than parsing, because in one case it is consuming a provider list and in the other it is reading an already-valid core configuration.

That also explains why the import path is a place where a user can get stuck. A subscription endpoint that returns a Clash YAML produces a converted set of nodes, and a node type the converter does not handle is dropped rather than reported in a way the user can act on.

For users on Android, the README points to a separate repository, sing-box-windows-android, so the desktop and mobile clients are distinct projects with distinct repositories.

## Three proxy modes, and the one that needs privileges

The proxy modes are system proxy, TUN mode and manual mode, and the difference between them is the difference between a setting and a driver.

System proxy is the conventional approach: the operating system is told to route browser traffic through the local proxy, and applications that respect the system proxy setting follow. TUN mode works at the network interface level, catching traffic that does not respect a system proxy setting, which is why it is the mode people reach for when a specific application keeps bypassing the proxy. Manual mode is the no-interference option, where the app is present and reports state without changing how traffic is routed.

That third mode is worth noticing. A client whose selling point is transparent traffic control also offers a way to be present without taking over the machine's networking, which is a reasonable thing for a tool that lives in the system tray.

The runtime visibility features sit alongside the modes: monitoring traffic, active connections, rules and logs in real time. For a user debugging why a particular site is not going through the proxy, having the rule list and the live connection list in the interface is often the difference between fixing it and guessing.

The desktop integration features are the other half of what makes this a client rather than a console. Tray mode, auto-start, hide-to-tray on autostart, lightweight mode which destroys the main window on close, update checks and window state persistence. The lightweight mode is the one with an operational consequence: closing the window does not stop the kernel, it removes the window, and the app keeps running in the tray.

## The reliability features exist because a proxy app fails quietly

One line in the feature list is longer than the others and deserves to be read on its own: backup and restore, subscription rollback, update channels, self-heal restart logic, and structured startup diagnostics with actionable failure hints.

Each of those exists because of a specific failure mode. A subscription provider changes its URL or serves an expired one, and the app has nodes that no longer resolve; rollback to the previous subscription is the fix. The kernel binary is the wrong architecture or fails to start, and self-heal restart logic restarts it. The app starts but nothing routes, and structured startup diagnostics with actionable failure hints say what went wrong instead of leaving a blank log.

The kernel story is where the platform difference bites. The scripts include separate build targets for Linux rpm and for Windows arm64, and the build pipeline injects target-specific kernel resources, which means the kernel artefact has to match the platform and the architecture of the machine. The app supports a manual kernel import, which is the escape hatch when the automatic download does not produce a usable binary.

The update channels are a related mechanism. A user on a stable channel gets the tested combination, and a user who wants the newest core can follow the other channel, at the cost of a configuration that changes under them.

None of this is glamorous, and all of it is what separates a client someone keeps installed from one they abandon the first time a provider breaks.

## A local SQLite store and a documented data directory

Storage is SQLite-backed local persistence for application settings, subscriptions, locale, theme and update preferences, and the data stays on the local machine.

The locations are given per platform, which is the detail an adopter actually needs:

- Windows: `%LOCALAPPDATA%\sing-box-windows\`
- Linux: `~/.local/share/sing-box-windows/`
- macOS: `~/Library/Application Support/sing-box-windows/`

The directory typically contains the SQLite database, generated configs, logs, backups and downloaded kernel metadata. Those generated configs are worth noting separately, because they are the actual sing-box configuration the core reads, and they are a derived artefact rather than something the user writes by hand.

Because the app keeps backups in the same directory as the database, the backup and restore feature is a file-level operation rather than an export. That makes a backup cheap to take before a risky change, and it also means the directory is the single thing to copy when moving to another machine.

The frontend side is Vue 3 with TypeScript, Pinia for state, Vue Router, Vue I18n for the built-in zh-CN, en-US, ja-JP and ru-RU locales, and Naive UI for the component set. The bridge between the two halves is Tauri invoke commands for request and response, with Tauri events carrying runtime updates, and the Rust side is split into core, network, storage, system and tray modules.

## Building it needs Rust, Node and a fetched kernel

The development section gives a full command sequence, and it is the clearest indication of the toolchain involved:

```bash
pnpm install
pnpm kernel:fetch
pnpm tauri dev
pnpm type-check
pnpm lint
cd src-tauri && cargo clippy && cargo test
pnpm tauri build
```

The kernel:fetch step is commented as recommended on first setup, and the comment notes that dev and build also auto-fetch when the kernel is missing, so the explicit command is an optimisation rather than a hard requirement.

The checks are split into frontend and backend, and the split is not cosmetic. The frontend checks are vue-tsc for types and the lint task, which runs oxlint and eslint in sequence with the fix flag. The backend checks are cargo clippy and cargo test inside src-tauri. The test suite has a few specific targets worth noting: test:kernel-targets, a node test for the kernel target script, test:i18n, a script that checks the translation files, and test:country-codes, a script that generates country code data.

The package manifest also shows the Tauri plugins in use, which map directly onto the desktop integration features. There is plugin-autostart for the auto-start behaviour, plugin-opener, plugin-updater for the update checks, plugin-websocket for the runtime event stream, and plugin-window-state for the window state persistence.

The licence is MIT, with the LICENSE file at the root, and the README carries a disclaimer that the project is for learning and communication purposes only and that users should comply with local laws and regulations. The repository is not archived and the last push was on 2026-10-19, with the recent releases being v2.3.2, v2.3.1 and v2.3.0.

## Conclusion

Sing-Box Windows suits a user who already runs sing-box or has a subscription file and wants a desktop interface with mode switching, traffic inspection and kernel management rather than a hand-edited JSON config. It is the wrong tool for a server or a headless router, since the project is built around a desktop shell, and it is the wrong tool for anyone who wants a single self-contained binary, because the kernel is a separate artefact that the app downloads and manages. Before you adopt it, read the release notes for the version you install, check the local data directory paths for your platform, and confirm the subscription format you have is one of the three the importer parses, since a Clash YAML and a sing-box JSON take different paths through the app.

## FAQ

### What is Sing-Box Windows and what does it add to sing-box?

It is a cross-platform desktop client built around the sing-box core, providing a GUI for importing subscriptions, switching proxy modes, inspecting runtime state and managing desktop integration on Windows, Linux and macOS. The core itself is a separate binary that the app downloads and manages.

### Which subscription formats can Sing-Box Windows import?

Three: sing-box JSON, where the app parses top-level outbounds; Clash or Mihomo YAML, where it parses proxies and converts supported nodes; and URI lists containing vmess, vless, trojan, ss, hysteria2, tuic or anytls links, with one or several nodes allowed.

### Where does Sing-Box Windows keep its data?

All data stays on the local machine in a per-platform directory: %LOCALAPPDATA%\sing-box-windows\ on Windows, ~/.local/share/sing-box-windows/ on Linux and ~/Library/Application Support/sing-box-windows/ on macOS. It holds the SQLite database, generated configs, logs, backups and downloaded kernel metadata.

### What proxy modes does Sing-Box Windows offer?

System proxy, TUN mode and manual mode. The app also monitors traffic, active connections, rules and logs in real time, and offers backup and restore, subscription rollback, update channels and self-heal restart logic.

## Sources

- [Issues](https://github.com/xinggaoya/sing-box-windows/issues)
- [License: MIT](https://github.com/xinggaoya/sing-box-windows/blob/master/LICENSE)
- [README](https://github.com/xinggaoya/sing-box-windows/blob/master/README.md)
- [Releases](https://github.com/xinggaoya/sing-box-windows/releases)
- [xinggaoya/sing-box-windows on GitHub](https://github.com/xinggaoya/sing-box-windows)

---

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