# Throne: a Qt desktop GUI for sing-box, Xray and 25+ proxy protocols

> Throne is a GPL-3.0 C++ desktop client that wraps sing-box and Xray cores behind one GUI, with a Linux CLI installer, portable ZIPs and a large protocol list. This review covers how it works, how to install it, and where it still expects root.

**throneproj/Throne** — Cross-platform GUI proxy utility (Empowered by sing-box)

- Repository: https://github.com/throneproj/Throne
- Website: https://throneproj.github.io
- Stars: 7,321 · Forks: 421
- Language: C++
- License: GPL-3.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/throneproj-throne

## What Throne actually is, and who it is for

Throne is a Qt based desktop proxy client for Windows 11/10/8/7, Linux and macOS, built in C++ and released under GPL-3.0. It is not a protocol implementation of its own: the README states it is empowered by sing-box, and the credits list both SagerNet/sing-box and XTLS/Xray-core, plus the older Qv2ray project. The repository layout matches that description, with a 3rdparty/ directory, a core/ directory and a res/ directory alongside src/ and include/.

The problem it solves is configuration sprawl. The supported protocol list runs from SOCKS and HTTP(S) through Shadowsocks, Trojan, VMess, VLESS, TUIC, Hysteria and Hysteria2, AnyTLS, Mieru, Snell, NaïveProxy, Juicity, TrustTunnel, ShadowTLS, Wireguard, AmneziaWG, MASQUE, SSH, Xray VLESS and OpenVPN/OpenConnect, plus Custom Outbound and Custom Config for both sing-box and Xray, chaining outbounds and an Extra Core slot. Anyone maintaining a handful of subscription links across that many formats would otherwise edit JSON by hand.

It is aimed at desktop users who want one window over several cores, not at server operators or at people building a routing service. The subscription side accepts share links, several JSON representations of sing-box configs, the v2rayN link format, and limited support for Shadowsocks and Clash formats. Deeplinks are documented on the project site. If your workflow is a browser extension or a router firmware, this is the wrong layer.

## Two cores, one GUI: how the pieces fit together

The architecture visible from the repository is a GUI process in front of external cores. The src/ and include/ trees hold the Qt application, core/ holds the core-management side, and 3rdparty/ vendors the supporting libraries credited in the README: simple-protobuf, fkYAML, quirc, QHotkey and sqlitecpp. Those names tell you something about the design. fkYAML and simple-protobuf point at config parsing and serialization, sqlitecpp at local storage for profiles and settings, quirc at QR code scanning for share links, and QHotkey at global shortcuts.

Because both sing-box and Xray are supported, Throne is not a thin wrapper around one engine. The protocol list includes Xray VLESS and Custom Outbound and Custom Config for both engines, which means the GUI has to model two configuration schemas and hand each core what it expects. That is the source of both its reach and its complexity: a feature that exists in one core may not map cleanly onto the other.

Route profiles and rulesets are not bundled. The README points to a separate routeprofiles repository as the source of the downloadable route profiles and rulesets, so routing behaviour depends on files fetched from outside the application. The README does not document rollback if a downloaded profile turns out to be wrong for your network.

## Installing Throne on Linux, Windows and macOS

Windows and macOS users get portable ZIPs from GitHub Releases. The README warns that macOS releases are unsigned, so the quarantine attribute has to be removed before launch, and the app must be moved to /Applications first because the built-in privilege escalation opens Terminal to make the core setuid-root, a step that can fail while the app is still in ~/Downloads.

```bash
xattr -d com.apple.quarantine /path/to/throne.app
```

Run that after moving Throne.app to /Applications. If the escalation step still fails, the README's explanation is the location of the app, not the command.

On Linux, the README gives a one-line CLI installer. It downloads a Python script from the dev branch and runs it with sudo, so read the script before piping it if you care about what lands on disk.

```bash
curl -fsSL https://raw.githubusercontent.com/throneproj/Throne/dev/script/install_linux.py | sudo python3
```

Fedora, RHEL, openSUSE and SLE users can instead use the linked RPM repository. Debian users have a choice the README explains in its FAQ: the debian-system-qt package does not pack Qt libraries and relies on the host's, while the plain debian package bundles everything and is roughly three times heavier. The system-qt variant exists because on legacy systems the provided Qt libraries use unsupported system features.

A first real use is short: install, open the app, import a subscription or share link, pick an outbound, then enable System proxy. The README's troubleshooting entries are the parts worth reading before you do that, because they describe what happens when you close the app the wrong way.

## Root, SUID and the TUN trade-off on Linux

The README is unusually direct about privilege. Creating and managing a system TUN interface requires root access. Without it, the alternative is granting the core some Cap_xxx_admin capabilities, and even then the README says you would need to enter your password three to four times per TUN activation. That is the argument for the SUID bit the installer sets.

Automatic privilege escalation can be disabled under Basic Settings -> Security. The README states plainly that features requiring root access stop working unless you grant the needed permissions manually. So the choice is not "run unprivileged and lose nothing": it is between a setuid-root core, manual capability grants with repeated password prompts, or a client that cannot create TUN interfaces at all.

This is where Throne differs most from a userspace-only proxy client. A tool that only sets a SOCKS or HTTP proxy never needs any of this. Throne's TUN support is what pulls root into the picture, and the README treats that as an accepted cost rather than something to hide. If your threat model or your organisation's policy forbids setuid binaries, that single constraint rules Throne out for TUN use.

## System proxy, system DNS and the force-quit failure mode

Two features reach outside the application: System DNS changes the system's DNS settings, and System proxy changes the system's proxy settings. The README's antivirus FAQ explains that the built-in updater downloads a release, removes the old files and replaces them, which resembles what malware does, and that System DNS is flagged by some antivirus products for the same reason. Those are documented behaviours, not detected threats.

The genuine failure mode is the proxy reset. If Throne is force-quit while System proxy is enabled, the process ends immediately and cannot reset the proxy, so the internet stops working. The README's fix is to open Throne again, enable System proxy, then disable it, which resets the settings. Its recommended practice is to always close Throne normally.

That is a real design weakness worth naming: system-wide state is written by a process that may not get a chance to clean up. A client that only binds a local SOCKS port has no equivalent failure, because nothing outside the process was modified. If you routinely kill GUI applications, budget for this. The README does not describe a watchdog or a startup repair that clears a stale proxy setting automatically.

## Throne against Nekoray and against a bare core

The closest comparison is the one the README makes itself. Nekoray's developer partially abandoned the project in December 2023, and the project is now officially archived. Throne was meant to continue that line, with the README describing improvements, new features, and the removal of obsolete features and simplifications. If you are migrating from Nekoray, the mental model of a Qt GUI over a proxy core carries over; the configuration surface does not.

The other alternative is running sing-box or Xray directly. That removes the GUI, the SUID escalation, the system proxy and system DNS features, and the antivirus heuristics that come with a self-replacing updater. What you give up is the profile store, QR scanning, global hotkeys, subscription parsing across share links and v2rayN link format, and the ability to switch between two cores from one window. For a single static server on a workstation, the bare core is less machinery. For a rotating set of subscriptions in several formats, the GUI is doing real work.

A third path, keeping the core and adding a different front end, is possible in principle because the cores are external, but the README does not document a stable interface for that, so treat it as unsupported.

## Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-19. Release 1.3.0 was published on 2026-09-17, after beta.3 on 2026-09-11 and beta.4 on 2026-09-16, so the release cadence in the period covered by the release list is measured in days rather than months.

Upgrade cost is shaped by the built-in updater: it downloads the new release, removes the old files and replaces them. That is convenient and it is also the reason some antivirus products flag the application, per the README. On Linux, upgrades interact with the packaging choice. A bundled .deb carries its own Qt libraries, so it is larger but less dependent on the host; the system-qt variant is smaller and depends on libraries your distribution provides, which the README notes may use unsupported system features on legacy systems. Choosing the system-qt package means an upgrade can break if the host Qt changes underneath it.

On licensing, the project is GPL-3.0. It links against and drives sing-box and Xray-core as separate cores, and the README credits them along with Qv2ray, Qt and the vendored libraries. Distributing a modified Throne, or bundling it into a product, brings GPL-3.0 obligations into play. That is a description of the licence, not legal advice; check with counsel before shipping anything derived from it.

## Conclusion

Adopt Throne if you want a single desktop GUI over sing-box and Xray cores, you are comfortable with a portable ZIP or a .deb, and you accept that TUN mode on Linux wants the SUID bit or Cap_xxx_admin on the core. Do not adopt it if you need a signed macOS app, a managed policy layer, or a client that never touches system DNS and system proxy settings. Before rolling it out, verify two things on a test machine: that Throne.app launches after the quarantine attribute is removed and the app is moved to /Applications, and that closing the app normally restores your system proxy, since a force quit while System proxy is enabled leaves it set.

## FAQ

### How do I use Throne on Linux?

The README gives a CLI installer that runs a Python script with sudo, and a separate RPM repository for Fedora, RHEL, openSUSE and SLE. Debian users can pick between a bundled package and a system-qt package that relies on the host's Qt libraries.

### How does Throne differ from Nekoray?

The README states that Nekoray's developer partially abandoned the project in December 2023 and that it is now officially archived. Throne was created to continue that line, with improvements, new features, and the removal of obsolete features and simplifications.

### Why does my antivirus detect Throne as malware?

The README attributes this to two behaviours: the built-in updater downloads a release and replaces the old files, which resembles how malware replaces files, and the System DNS feature changes the system's DNS settings, which some antivirus applications treat as dangerous.

### Is the SUID bit really needed for Throne on Linux?

Creating and managing a system TUN interface requires root access according to the README. Without it you would have to grant the core some Cap_xxx_admin capabilities and still enter your password three to four times per TUN activation. Automatic privilege escalation can be disabled under Basic Settings -> Security, but features needing root then stop working.

### Why does my internet stop working after I force quit Throne?

If Throne is force-quit while System proxy is enabled, the process ends immediately and cannot reset the proxy. The README's fix is to open Throne again, enable System proxy, then disable it, which resets the settings.

### Why is the macOS build of Throne unsigned?

The README states that Throne does not have a signed certificate, so you must remove the quarantine attribute with xattr -d com.apple.quarantine before launching, and move Throne.app to /Applications first because the privilege escalation step can fail while it is still in ~/Downloads.

## Sources

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

---

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