NekoBox: eight protocols live in a private sing-box fork, and macOS is out by design

Ten install channels, and one Windows manifest hosted elsewhere

The distribution section is the longest part of the README, and the channels are worth reading as a map of who maintains this.

On the release side there are portable archives for Windows, Windows installers, and AppImages. Everything else is a third-party channel: a Windows package manager entry, a Chocolatey package, and a Scoop package installed from the extras bucket.

On Linux the coverage is broad. An Open Build Service repository covers openSUSE, Mageia, Debian, Raspbian, Ubuntu, openEuler and Arch. A Fedora infrastructure repository covers Red Hat, Fedora, CentOS and AlmaLinux. There are packages in the openSUSE software repositories, a FreeBSD ports entry, a community Arch repository with its own keyring, an Ubuntu personal package archive, and two Arch User Repository entries, one stable and one tracking the repository.

On Windows the package manager entry is a two-line Scoop install from the extras bucket:

scoop bucket add extras
scoop install extras/nekobox

The Ubuntu archive is three commands, adding the archive, refreshing the package lists, then installing:

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

Two of the distribution-native packages are shorter still, one line each on openSUSE and on FreeBSD:

sudo zypper install -y nekobox

sudo pkg install -y nekobox

One detail deserves attention rather than admiration. The Windows package manager manifest is not in the vendor's own manifest repository. It lives in a third-party manifest site, which is one more hop between the project and the package manager's own review.

For a single-maintainer project that is a remarkable amount of packaging surface, and it also means a user has several choices with several different update cadences and trust bases.

Eight protocol additions live in a private core fork

The task list explains where the protocol coverage comes from, and the answer is not the upstream core.

The client is built on sing-box, and the README's own task list includes an item about adding more protocols that upstream sing-box does not support. The parenthetical names what has already been added and where it lives: mieru, juicity, trusttunnel, VLESS encryption, the xhttp transport, the kcp transport, amnezia and snell, all inside the maintainer's own fork of sing-box rather than upstream.

That is eight protocol or transport additions carried by one person, on top of a core they also have to merge forward. Every upstream sing-box release has to be taken, merged, and built before a user sees it, which is a different maintenance model from a client that just tracks a tagged core.

The supported protocol list is long regardless, at more than two dozen entries, mixing mainstream names with the ones the fork adds and with categories rather than protocols: chained outbounds, custom configuration, a custom outbound and an extra core are listed alongside individual transports.

Some of those categories are the interesting ones. An extra core and a custom outbound suggest the client can host more than the bundled core or emit a raw outbound definition, which is a power-user feature rather than a compatibility one.

The task list still lists features that already exist

Two items in the development list are already shipped, and that is a useful signal about how the list is maintained.

The first is command line tools. The README announces them at the top: sing-box command-line mode is available, and typing the core binary with the right flag prints additional information. There is a separate front end as well, a terminal interface with its own readme, which shares the same configuration directory and the same remote procedure call channel as the graphical client, so the two can be used interchangeably.

The second is the terminal interface item itself. Both of those exist in the tree and are described in the README, yet both still appear as open work.

The rest of the list is more revealing. There is service manager integration wanted for three different init systems for the core binary. Remote control is wanted. The static user interface for editing proxies is to be replaced with a declarative one, which is an admission that the current editing model is the weak part of the application. And the last item, phrased as finding the best database storage in the world, is a joke rather than a plan.

So the list mixes shipped work, real plans and one gag, in the same undifferentiated bullet style.

macOS is excluded, and the exclusion is in the task list

Platform support is stated once, at the top: a Qt based desktop cross-platform graphical proxy utility supporting Windows 11 and 10 on arm64, x86_64 and x86, and Linux, out of the box.

So three Windows architectures and Linux. That is already unusual coverage for a Qt desktop tool, particularly the 32-bit Windows target, which is why the credits mention a Windows 7 compatibility library and a separate library for building older Windows binaries.

The reason macOS is absent appears in the development list rather than in the feature statement, where it says support for all platforms that sing-box and Qt support, except macOS and iOS. So the exclusion is deliberate and named, but it is buried in a task item rather than stated where someone looking for a Mac build would read it.

For anyone searching for a client on a Mac, that placement is the difference between a two-second answer and a wasted afternoon.

Naming is part of the confusion, and the credits section explains why. The Android client this project grew out of and the nekoray fork are both listed as sources, so several unrelated applications share either the name or the lineage. The terminal front-end has its own README under src/tui, and it shares the same configuration directory and the nekobox_core RPC with the desktop client, which means the two interfaces can be used interchangeably once either one is running.

Subscription import is where the moving parts are

The formats section is the most detailed part of the documentation, and it is where the engineering effort has gone.

The simple cases are share links, a JSON array of outbounds, the v2rayN link format, and limited support for Shadowsocks and Clash formats. Full JSON subscriptions are supported for sing-box and for v2rayN-style configurations, and imported profiles keep their original routing and DNS rules, work with URL testing and automatic testing, and can be used with TUN mode.

The feature list then gets specific about what happens during import. A full sing-box configuration has its inbounds stripped and the application's own local inbounds added at runtime. V2Ray-style JSON is converted for a list of outbound types. Route rules are preserved, including profile-specific direct rules, which is the detail that decides whether a split-routing profile survives an import. DNS configuration is migrated for newer core versions, including converting the fake-IP server. And there is detection for a specific protocol from v2rayN and Happ style JSON.

Subscription links from a Happ-style service are supported, including encrypted ones, and subscription groups can be added from browser deep links using two custom URL schemes.

That combination, especially the routing and DNS preservation, is what makes this a usable client rather than a link importer.

The build runs on a dozen actions, several of them the maintainer's own

The credits section doubles as a build system inventory, and it is long.

The application libraries are the expected set for a Qt project with a core: the Qt toolkit, an RPC library, a YAML parser, a QR code reader, a hotkey library for global shortcuts, a protobuf implementation, a lightweight JavaScript engine, and the core itself. The desktop client this one credits is the Android sibling, and the reference material also includes two comparable desktop clients.

After that comes the build pipeline, listed as a run of GitHub Actions: an installer packager, a package installer, an action that publishes to the Arch User Repository, Windows toolchain setup, a cached download helper, a Microsoft C++ environment setup, Go and Ninja setup, a cached package manager step, a Qt setup action and a gRPC setup action. Plus a Linux application bundler, the MinGW and Microsoft toolchains, the Go toolchain, and two libraries specifically for building on older Windows versions.

Two of those actions are hosted under the maintainer's own account, and several of the others are third-party actions rather than GitHub's own. That is the normal shape of a project that needs a Windows toolchain plus a Qt toolchain plus a bundler in one pipeline.

The last credit in the list is cut off partway through its address, which is a small sign that this section is assembled by appending rather than edited.

It also tells you that the release artefacts are reproducible from the repository rather than assembled by hand, which is the main thing this section is for.

The container is privileged and mounts your working directory read-write

A compose file at the repository root defines a single service, and it is a development container rather than a deployment.

The build context is a script directory with its own Dockerfile, so the image is assembled from the build scripts rather than from the whole tree. It runs with the platform set from a guest architecture variable, which is how the same file cross-builds for another architecture.

Two settings define the security surface. The container runs privileged, and it maps the FUSE device from the host. The working directory is then bind-mounted into the container read-write with SELinux labelling options on the mount.

That combination is what TUN mode work on Linux requires, since TUN needs elevated privileges and FUSE. It also means the container has broad access to the host with write access to your project, which is fine for a build sandbox you start deliberately and worth naming for anyone running it in a shared or CI environment.

The repository layout matches a desktop application built with CMake: a top-level build file, a cmake directory, a core directory, a source directory, the script directory with the container build, a pages directory for the interface, a resources directory, and a changelogs directory that is the only version history beyond the releases.

Release numbering carries four parts, and the last three releases sit in the same minor and patch range across July and August 2026.

Editorial conclusion

NekoBox fits a Windows or Linux user who wants a desktop client over a maintained sing-box core, needs the extra protocols the fork adds, or imports subscriptions in the JSON formats v2rayN and Happ produce. It does not fit a macOS user, and it is not a good fit for someone who wants a client whose core tracks upstream releases automatically. Verify four things before you commit. Read the task list rather than the feature list, because it is where the platform scope is stated honestly and macOS and iOS are excluded, and because two items on it, command line tools and a terminal interface, already exist in the tree. Decide whether you are comfortable with a forked core, since eight protocol additions live in the maintainer's own sing-box fork and every upstream release has to be merged forward by hand. Choose your install channel deliberately, since the Windows package manager manifest is hosted in a third-party repository rather than the vendor's own, and the Linux channels range from official distribution archives to a personal package archive and a community repository. And read the compose file before using it, because the development container runs privileged with the FUSE device mapped and your working directory mounted read-write. Releases 5.11.28.1 through 5.11.28.3 shipped between 2026-07-25 and 2026-08-26, the licence is GPL-3.0, and the last commit is dated 2026-09-26.

Frequently asked questions

Official sources

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