taamarin/box_for_magisk: a Magisk and KernelSU transparent proxy module

What Box for Root actually solves on a rooted Android device

A normal VPN client on Android takes over the VpnService slot: one tunnel, one app, and the operating system decides what enters it. Box for Root takes a different route. It is a Magisk, KernelSU or APatch module that installs proxy cores at the system level and redirects traffic through iptables, so applications do not need to know a proxy exists. The README describes it as a "Transparent Proxy for Android (Root)" and lists five cores in one package: clash, sing-box, v2ray, hysteria and xray.

The audience is narrow and specific. You need root, you need a module manager that supports the module (Magisk, KernelSU or APatch), and you need to be willing to work in a shell. The README's own instructions are all su commands against scripts under /data/adb/box/scripts/, and it warns that tproxy-related configuration must match definitions in /data/adb/box/settings.ini. That is not a consumer app workflow. It is a workflow for someone who already administers their own device.

The payoff is uniformity. One set of rules covers every app, including apps that refuse to route through a user-space VPN. The cost is that a mistake in the iptables rules or the core config can affect all traffic at once, not just one app's tunnel.

How the module is put together: cores, settings.ini and iptables

Three pieces do the work. The proxy cores live under the module directory, the settings live in /data/adb/box/settings.ini, and the traffic redirection lives in /data/adb/box/scripts/box.iptables. The README names the paths explicitly: MODDIR=/data/adb/box, MODLOG=/data/adb/box/run, SETTINGS=/data/adb/box/settings.ini.

The data flow is: an app opens a connection, the iptables rules intercept it and hand it to the local proxy core, the core applies whatever outbound configuration you supplied, and the connection leaves the device through your chosen server. The core itself (clash, sing-box, v2ray, hysteria or xray) is not configured by this project. You bring the config. Box for Root supplies the plumbing that makes the core transparent to the rest of the system.

That division explains the README's central warning. Because the iptables layer and the core config are separate files, they can disagree. The README states that when modifying core configuration files, the tproxy-related configuration must match the definitions in settings.ini. A mismatch is not a syntax error the module will catch for you; it is a routing failure you diagnose from logs in /data/adb/box/run.

The module also ships helper scripts rather than a single binary. box.service handles start, stop, restart, status, cron and kcron. box.iptables handles enable, disable and renew. box.tool handles check, geosub, geox, subs, upkernel, upxui, upyq, upcurl, reload and all, according to the usage line the README prints. Splitting service control from rule control is deliberate: you can tear down the redirect rules without killing the core, which is what makes recovery from a bad rule set possible.

Installing Box for Root and starting the service for the first time

The README does not spell out a full installation walkthrough, but the repository layout and the uninstall section make the shape clear. You install the module through Magisk, KernelSU or APatch, which is the standard path for a module with META-INF/, module.prop and customize.sh at the top level. The uninstall instructions confirm the installed location: /data/adb/modules/box_for_root. There is also an optional BFR Manager app, distributed through the project's Telegram channel, which the README links as "Download BFR Manager".

After installation, the README states the BFR service auto-starts after a system boot, and that starting takes a few seconds while stopping takes effect immediately. To start it manually, the README gives this pair of commands:

su -c /data/adb/box/scripts/box.service start && su -c /data/adb/box/scripts/box.iptables enable

The first command brings up the core, the second installs the redirect rules. Both are needed for traffic to actually flow through the proxy. To reverse it, the README gives the mirror image, and the order matters because you want the rules gone before the core disappears:

su -c /data/adb/box/scripts/box.iptables disable && su -c /data/adb/box/scripts/box.service stop

Before editing anything, note the README's warning: turn BFR off before editing /data/adb/box/settings.ini, otherwise you risk configuration problems. Logs land in /data/adb/box/run, so that directory is your first stop when the service starts but nothing gets through.

One more thing worth doing early. The README says that if your device has a public IP address, you can add that IP address to the internal network in /data/adb/box/scripts/box.iptables to prevent loopback traffic. This is a manual edit, and it is the kind of omission that produces confusing partial failures rather than a clean error.

Where Box for Root breaks, and what it will not do for you

The most honest limitation is stated by the project itself: root. No root, no module. That removes the entire stock-device audience, and it means the module's blast radius is the whole device. A bad iptables rule set can cut connectivity for every app, including the one you would use to search for a fix.

Configuration mismatch is the second failure mode, and it is structural rather than accidental. The core config and the tproxy definitions in settings.ini are separate artifacts maintained by hand. Nothing in the described workflow validates that they agree. The README's advice to keep them in sync is a manual discipline, and the logs in /data/adb/box/run are where you find out you got it wrong.

The third limitation is that Box for Root is plumbing, not a service. It does not provide servers, subscriptions or a routing policy. The box.tool script lists a subs action and a geosub action, which suggests subscription handling exists, but the README does not document their formats or behaviour beyond the usage line. If you are looking for a turnkey client where you paste a link and everything works, this is the wrong tool. If you want a per-app split tunnel configured through a GUI, a user-space VPN client is a better fit, because it does not require root and it cannot take down system-wide connectivity.

Finally, the README points to a Telegram channel as the distribution point for the optional manager app rather than a store listing. That is a real constraint for anyone who needs a verifiable distribution channel.

Box for Root compared with a userspace VPN client

The alternative most readers will weigh is a conventional Android VPN client built on the same cores, for example a sing-box or clash front end installed as a normal app. The difference is not the proxy engine, since both can run the same core. The difference is where the redirect happens.

A userspace client uses Android's VpnService. The operating system creates a tun interface, the app reads packets from it, and only traffic the OS routes into that interface is affected. That gives you per-app selection for free, no root, and a clean uninstall. It also means apps that opt out of the VPN, and system-level traffic the OS does not route, stay outside the tunnel.

Box for Root redirects at the iptables layer instead. Nothing needs to cooperate. That is the advantage, and it is the reason the project exists: coverage that a VpnService client cannot offer. The trade-off is that you own the rules, you own the core config, and you own the recovery procedure. There is no app-level switch to fall back on when the rules are wrong; the README's box.iptables disable is that switch, and it requires a shell.

A secondary difference is update mechanics. A VPN client updates through its own channel. A root module updates through the module manager and the project's releases, and the repository's update.json and action.sh entries suggest in-manager update support, though the README does not describe it.

Maintenance, licence and what upgrading costs you

The repository is not archived, and the last push was on 2026-09-24. The most recent release listed is a pre-release, pre-v1.10.2(4cec20f), dated 2025-10-21, following stable v1.10.2 on 2025-09-05 and v1.10.1 on 2025-08-23. The pattern is frequent point releases with pre-releases ahead of them, which tells you the project is moving, but it also means you should read the release notes before upgrading rather than assuming a drop-in replacement.

The upgrade cost is concentrated in the files you edited. A module update can replace files under /data/adb/modules/box_for_root, and the README treats /data/adb/box as the data directory that survives separately, which is why uninstalling requires deleting it explicitly with rm -rf /data/adb/box. Your settings.ini and iptables edits live in that data directory, so the practical upgrade question is whether a new release changes the tproxy keys that settings.ini must match. The README does not document a migration procedure, and it does not document rollback. Back up settings.ini and box.iptables before you update, because that is the only recovery path the repository describes.

The licence is GPL-3.0, stated in the README and present as a LICENSE file at the repository root. For anyone embedding the module in a larger distribution, that is a copyleft licence, and the practical consequence is that derivative distributions carry the same obligations. This is a description of the licence, not legal advice; if you plan to redistribute, read the LICENSE file and get your own counsel.

One credit matters for provenance: the README credits CHIZI-0618/box4magisk as the original Box for Magisk module. Box for Root is a continuation of that lineage, not a from-scratch design.

Editorial conclusion

Adopt Box for Root if you already run a rooted Android device, you are willing to edit /data/adb/box/settings.ini and box.iptables by hand, and you want one proxy core covering every app rather than a per-app VPN client. Skip it if you do not want root, if you need a signed app from a store, or if you cannot test a change before relying on it. Before you commit, verify three things on your own device: which core you intend to run and whether its config matches the tproxy settings in settings.ini, whether your public IP needs adding to box.iptables to avoid loopback traffic, and that you can recover from a bad config by stopping the service with box.iptables disable followed by box.service stop.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. taamarin/box_for_magisk on GitHub