NyameBox (NekoBox for PC): a sing-box GUI that goes past upstream protocols

What NyameBox solves, and who it is actually for

NekoBox was a Qt desktop proxy client built around sing-box. NyameBox is the same project rebranded, and the README credits MatsuriDayo/nekoray and starifly/NekoBoxForAndroid among its sources. The problem it addresses is narrow but real: sing-box is a routing engine with a JSON configuration file, and editing that file by hand for every subscription, route rule and DNS setting is slow. NyameBox puts a Qt GUI in front of that engine, so a profile can be imported from a share link, tested, and switched on without touching JSON.

The intended user is someone who already runs sing-box or a compatible client and wants a desktop interface on Windows or Linux. The README states support for Windows 11/10 on arm64, x86_64 and x86, and for Linux out of the box. macOS and iOS are explicitly excluded from the platform roadmap, which says support is planned for every platform sing-box and Qt support except macOS and iOS. If you are on a Mac, this project is not aimed at you.

How the Qt front end talks to the sing-box core

The repository layout separates the interface from the engine. The src/ directory holds the Qt application, core/ holds the core side, and the credits list Thrift, protorpc and simple-protobuf alongside sing-box. That combination suggests the GUI and the core communicate over a generated RPC layer rather than by spawning a process and parsing stdout. The README also states that a sing-box command line mode is available, invoked as nekobox_core sing-box --help, which means the core binary can be driven directly without the GUI.

On the subscription side the data flow is documented more precisely. Full sing-box JSON profiles are imported with their inbounds stripped and local application inbounds added at runtime. Existing routing and DNS rules are preserved, and the README says the imported profiles work with URL testing, auto testing and TUN mode. For v2rayN-style JSON, the project converts VLESS, VMess, Trojan, Shadowsocks, Hysteria, Hysteria2, TUIC, direct and block outbounds. DNS migration for newer sing-box versions includes fakeip server conversion. That is more than a link parser; it is a compatibility layer for other clients' configuration formats.

Installing NyameBox on Windows, Linux and FreeBSD

The README points to GitHub Releases for portable ZIPs, Windows installers and AppImages. On Windows there are three package managers. Scoop is the example given in the README:

scoop bucket add extras
scoop install extras/nekobox

After that, the nekobox command should resolve to the installed package. WinGet and Chocolatey packages also exist, linked from the README as qr243vbi.NekoBox and nekobox respectively.

On Linux the project maintains several channels. openSUSE users can install from the distribution package:

sudo zypper install -y nekobox

Ubuntu users have a PPA, and the README gives three commands:

sudo add-apt-repository ppa:miamosagernaki/nekobox
sudo apt update
sudo apt-get install -y nekobox

Arch users have two AUR packages, nekobox and nekobox-git, plus an ArchLinuxCN repository the README sets up by appending a repo block to /etc/pacman.conf, syncing, installing archlinuxcn-keyring, and then installing nekobox with pacman. Fedora, RedHat, CentOS and AlmaLinux are covered by a COPR repository. FreeBSD has a freshport entry and installs with sudo pkg install -y nekobox. For a first real use, the shortest path is to install from your platform's channel, open the app, and import a subscription. The README says subscription groups can be added from browser deeplinks using nekobox:// and v2raytun:// URLs, and that Happ links including encrypted happ:// links are supported.

The protocol list is the reason to pick this over upstream sing-box

Upstream sing-box does not implement everything. The README's TODO states the project wants to add protocols not supported by upstream sing-box, and lists what has already been added: mieru, juicity, trusttunnel, vless encryption, xhttp transport, kcp transport, amnezia and snell. The mieru work is credited to enfein/mieru, and the core changes live in a fork at qr243vbi/sing-box rather than in the upstream repository.

The supported protocol list is long: SOCKS, HTTP(S), Shadowsocks, Trojan, VMess, VLESS, Hysteria 1 and 2, TUIC, AnyTLS, ShadowTLS, Mieru, Juicity, TrustTunnel, Naive, Wireguard, AmneziaWG, Tailscale, SSH, Tor, Snell, Custom Outbound, Custom Config, Extra Core and chaining outbounds. Two entries deserve attention. Extra Core means the GUI can delegate to a separate core binary, and chaining outbounds means one outbound can route through another. Both are features a plain sing-box configuration can express, but having them exposed in a GUI is the point of the project.

The cost is that the protocol set depends on a fork. If a protocol is added in qr243vbi/sing-box and not upstream, NyameBox users get it first and upstream sing-box users do not get it at all.

TUN mode, platform gaps and the missing command line tooling

The README is unusually direct about unfinished work. The TODO list includes command line tools, OpenRC/runit/systemd integration of nekobox_core, a terminal UI, remote control, and replacing the static UI with a declarative UI for editing proxies. It also includes a line about finding the best database storage, which reads as an admission that the current choice is not settled.

The practical consequence is that NyameBox is a desktop GUI first. If you want to run the core under systemd and manage it remotely, the README says that integration is still on the TODO list. The nekobox_core sing-box --help entry point exists, but the surrounding service management does not.

TUN mode is the other boundary. The README states that full JSON profiles can be used with TUN mode, and that route rule preservation includes profile-specific direct rules in TUN mode. It does not claim TUN mode works on every supported platform. One of the search questions asks what TUN mode is, which suggests the concept is not obvious to new users: it is the mode where the client takes over the system's network stack instead of relying on per-application proxy settings. Because the README does not enumerate platform support for TUN, that is the first thing to confirm on your own system before relying on it.

How NyameBox differs from running sing-box directly

The obvious alternative is sing-box itself, without a GUI. The difference is not feature parity, it is where the configuration lives. With sing-box you write and maintain a JSON file, and every subscription change is an edit. With NyameBox the README describes importing share links, JSON arrays of outbounds, v2rayN link format, and limited Shadowsocks and Clash support, then running URL testing and auto testing against the imported profiles.

That conversion layer is the real product. The README states that full sing-box configuration import strips inbounds and adds local application inbounds at runtime, and that DNS migration handles fakeip server conversion for newer sing-box versions. A user running sing-box directly has to do that migration by hand when the schema changes. A second alternative is MatsuriDayo/nekoray, which the README credits. NekoBox for Android, credited as starifly/NekoBoxForAndroid, is a separate mobile codebase, so a search for NekoBox on Android is not about this desktop project. If you want the Android client, this repository is the wrong place.

Licence, release cadence and the cost of tracking a fork

NyameBox is GPL-3.0. That matters because the project links against Qt, which has its own licensing options, and because the core is a fork of sing-box. If you intend to redistribute a build or bundle it into a product, the GPL-3.0 terms and Qt's terms both apply, and the fork means your upstream is qr243vbi/sing-box rather than SagerNet/sing-box. This is a description of the licence identifier in the repository, not legal advice; check the terms yourself before shipping anything.

On cadence, the repository is not archived and the last push was on 2026-08-26. Recent releases are 5.11.28.3 on 2026-08-26, 5.11.28.2 on 2026-07-30 and 5.11.28.1 on 2026-07-25. The version scheme keeps a 5.11.28 base and increments a fourth component, which suggests patch releases on top of a stable line rather than a rolling version. There is a changelog channel on Matrix and Telegram linked from the README, and a changelogs/ directory in the repository.

The upgrade cost is the fork. Protocol additions land in qr243vbi/sing-box first. If upstream sing-box changes its configuration schema, the README's DNS migration note implies NyameBox has to absorb that change on its own schedule. Budget for reading release notes rather than assuming a drop-in update.

Editorial conclusion

Adopt NyameBox if you want a Qt desktop client for sing-box that speaks share links, v2rayN JSON, Clash and Happ subscriptions, and you are willing to track releases rather than a stable API. Skip it if you need a terminal UI, remote control or systemd/OpenRC/runit integration of nekobox_core today, because the README lists those as TODO. Before installing, check the release notes for your platform and confirm whether TUN mode is supported there, since the README does not enumerate platform support for TUN.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes