OneBox: a desktop client that hides the sing-box configuration behind a subscription

A client for people who want a client, not a configuration workshop

OneBox is a cross-platform GUI client based on the sing-box kernel, built with Tauri, React and Rust on top of the sing-box network core.

The design intent is stated without hedging. It is designed for people who want a clean daily-driver client instead of a configuration workshop: add a subscription, pick a route mode, start the service, and let the app handle the platform details.

And then the project says the other half out loud. OneBox is not a playground for wish-list driven sing-box customization. Requests for full manual control, endless knobs, or niche behavior are out of scope, and related pull requests are not guaranteed to be accepted. If you need that workflow, the instruction is to fork the project, build your own copy, and maintain it yourself.

That is unusual and useful. A client that will not absorb your custom sing-box configuration is not a smaller tool, it is a tool with a defined scope, and the scope is drawn where the maintainer can actually support it. The homepage points at sing-box.net, and the repository carries a Chinese readme alongside the English one.

The stack is visible in the package.json. Tauri 2 with the plugin set for autostart, clipboard, deep link, dialog, filesystem, http, log, opener, OS, process, shell, SQL, store, updater and window state, React 19 on the front end with Tailwind 4, framer-motion, sonner for toasts, swr for data fetching, zod for validation, and vitest with the Vite coverage provider for tests. The project is TypeScript for the front end and Rust for the shell, with a deno.json and deno.lock for the task runner.

The feature table is a scope statement, not a list

The capabilities are laid out as a table with a column for what OneBox does, and reading it in that order is the fastest way to understand the product.

The subscription-first workflow imports remote configuration links, tracks traffic metadata, refreshes subscriptions, and supports deep-link based setup. That last part is what makes it a client rather than a configurator: a subscription URL can carry setup, so a service can hand a user a link and have the client configure itself.

Route modes are provided as mixed and TUN modes, with rule and global templates that are maintained for supported sing-box versions. The phrase maintained for supported versions is doing work, because the templates have to track the upstream kernel.

System integration includes tray controls, system proxy helpers, autostart, an updater flow, and platform-specific service handling. The platform-specific part is not optional decoration, since setting a system proxy and running a TUN device are privileged operations that differ per operating system.

Privacy-conscious storage means sensitive values go through system-backed mechanisms instead of being treated as plain UI state, which on macOS means the keychain and on the other platforms the equivalent. Developer visibility ships log, generated config and config-template views for debugging, without exposing casual users to noise.

The last row is the architecture in one line: built on Rust and Tauri, keeping the desktop shell lightweight while delegating network execution to the sing-box core. OneBox does not implement a proxy; it configures and supervises one.

The platform tiers tell you where the bugs will be

The platform support table is the most decision-relevant part of the documentation, because it tells you who is fixing what.

Tier 1 is Official and covers macOS, described as production-ready and maintained by the core team with priority fixes. Tier 2 is Community and covers Windows and Ubuntu, described as stable, with fixes and feature parity depending on community maintenance. Tier 3 is Experimental and covers Linux, with beta quality, incomplete behaviour expected, and use at your own risk.

That third row is worth dwelling on. It is unusual to see a project name Linux as a tier of its own rather than folding it into the community tier, and the reason is probably that the pieces which need the most platform work, the TUN device and the system proxy handling, are the least uniform on Linux. A user on Linux is explicitly told to expect incomplete behaviour.

There is also a specific security note attached to the platform story. The macOS build is notarized by Apple, so it can be installed without manual security overrides. That is a real practical difference for a user who is not going to disable Gatekeeper.

And the security note that comes with the feature table: OneBox applies multiple security and privacy controls, but vulnerabilities in the underlying network core are handled by the upstream sing-box project, and the documentation says to track upstream advisories when assessing operational risk. A client is only as safe as the core it configures.

Development runs on Deno, and the Makefile wraps the awkward parts

The build tooling is unusual enough to be worth describing, because the choice of Deno as the task runner and package manager is a statement.

The dependency install and preparation are:

deno install
deno task prepare

The desktop frontend during development is started with deno task tauri dev, the web bundle is built with deno task build, and the frontend test suite runs with deno task test. The Rust side is tested separately with cargo test -- --nocapture, which shows the captured output.

The package.json is a thin shim over that, holding a single script, tauri, which delegates to deno task tauri. The dependencies are the Tauri plugin set, React and the front-end libraries listed above, and the devDependencies carry the Tauri CLI, Vite, vitest with coverage, husky, TypeScript and prettier-adjacent tooling.

The Makefile is where the operations that do not fit a front-end task live. Its help output lists update for updating JavaScript and Rust dependencies, dev to start the Tauri dev server, build for the Tauri application which invokes scripts/prebundle.sh, bump to bump the patch version in tauri.conf.json and commit all changes, helper to build the macOS privileged helper as a universal binary, proxy-info to print the Makefile and inherited proxy environment, and linux-check to run cargo check on the Linux VM with local work in progress patched.

That last target is the tier system in practice. There is a dedicated machine for checking Linux, which is what a project that treats Linux as experimental would need.

Templates are synchronised before every build, and the Windows service is its own script

The project notes are short and each one is a maintenance detail that would otherwise be discovered the hard way.

Config templates are synchronized before dev and build through scripts/sync-templates.ts. That is the mechanism behind the route mode templates the feature table mentions, and it means the template source is not hand-edited at each site.

The Windows TUN service is built through scripts/build-tun-service.ts. On Windows, running a TUN device means installing and managing a service, which is why it gets its own build script rather than being part of the normal application build.

Platform-specific Tauri settings live under src-tauri/tauri.*.conf.json, which is the Tauri convention for per-platform configuration, and it is where the privilege differences between the platforms get expressed.

Human-facing protocol notes are available under docs/spec/zh/, so the protocol documentation is in Chinese, which is a useful signal about who the project serves. The tree also carries a lang/ directory for translations, a docs/ directory, an AGENTS.md and a CLAUDE.md, which tells you the project expects agent-assisted contribution, and a .husky/ directory for git hooks.

The npm package name is one-box, it is private, and its version field is 1.0.0, which is the app's own version placeholder rather than the release version, since the actual versions come from the Tauri configuration and the release tags.

Where OneBox is the wrong tool

The first limit is stated by the project itself, and it is not a limitation to be worked around. Full manual control of sing-box is out of scope, and pull requests for it are not guaranteed to be accepted. If your use case needs a specific outbound, a specific protocol, or a routing rule that the templates do not cover, you are meant to fork it and maintain your own copy. That is a legitimate answer, but it means the project is not for you, and it means the roadmap you are buying into is the maintainer's.

The second is the maintenance horizon, and it is the most consequential fact in the documentation. Maintenance of this project will end on December 31, 2027. A desktop client that announces its own end date is unusual, and the announcement is in an IMPORTANT block at the top of the readme, so it is not hidden. For a daily-driver client that is a real consideration, and it interacts with the third point.

The third is upstream risk. The client can be maintained to the end date, but the network core underneath it is sing-box, and the project is explicit that vulnerabilities in that core are handled upstream. If you are assessing operational risk for a team, the advisories you need to track are sing-box's, not OneBox's, and you will be tracking them for at least as long as the client exists.

The fourth is the platform tier. A user on Linux is told to expect incomplete behaviour and to use it at their own risk, and on Windows and Ubuntu the fixes depend on community maintenance rather than the core team. If you deploy OneBox in a managed fleet on Ubuntu, you are accepting community-tier support with a client that has three years left.

The fifth is what a client is not. OneBox configures and supervises a proxy core; it does not replace the core, and the templates it ships are maintained for supported sing-box versions, which means your client version and your core version have to stay in step.

Editorial conclusion

OneBox is worth using for a person who wants a working network client and not a project, because the subscription-first workflow, the route mode templates and the system proxy helpers are exactly the parts that a hand-rolled sing-box setup leaves you to assemble, and because the project is explicit about not being a configuration workshop. It is the wrong tool if you need full manual control of sing-box, because the project says so and declines pull requests for it. Before you adopt it, check the three things the documentation states: the platform tier you are on, since macOS is production-ready and maintained by the core team while Windows and Ubuntu are community tier and Linux is experimental with beta quality; the end of maintenance on December 31, 2027, which is the single most important fact for a desktop client; and the upstream advisories, because the project says vulnerabilities in the underlying network core are handled by the sing-box project and you should track those yourself.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. OneOhCloud/OneBox on GitHub
3. Project website
4. README
5. Releases