NetProxy-Magisk: a system-level sing-box transparent proxy for rooted Android

What NetProxy-Magisk solves, and for whom

Android proxy apps normally occupy the VPN slot, which means one tunnel at a time and a persistent notification. NetProxy-Magisk takes a different route. It is a system-level transparent proxy module for rooted Android devices, built around the sing-box core, and it is installed as a Magisk, KernelSU or APatch module rather than as an app. The README states that node, subscription, routing, DNS and transparent proxy configuration all live in the module directory, and that the module does not depend on VPN mode.

The audience is narrow and specific. You need root, because the module installs into the module framework and runs with root privileges. You need a kernel that exposes the right hooks. The README is explicit: eBPF inbound requires the kernel to enable BPF, cgroup v2 and the cgroup socket attach capability, and hotspot sharing additionally needs working TC eBPF support. Kernels that do not meet those requirements cannot start this version. If you are on a stock, unrooted phone, nothing here applies to you.

In exchange, the module offers capabilities a VPN-slot app cannot: per-app blacklist and whitelist, hotspot and USB tethering proxying, and automatic switching between the base mode and Direct based on the WiFi SSID. Those are the reasons someone would accept the root requirement.

How the traffic interception actually works

The mechanism is cgroup eBPF, not iptables. The README lists as a core capability that the module takes over local TCP, UDP and DNS traffic using cgroup eBPF, and that it does not modify iptables, nftables or policy routing. That distinction matters for anyone who has fought with rule ordering in a firewall script: there is no firewall script to fight with here, but there is also no iptables chain you can inspect to debug a leak.

The data path has three modes. EBPF_MODE accepts local, shared or hybrid. Local covers the device itself; shared covers tethered clients; hybrid covers both. EBPF_NETWORK defaults to empty, which the README describes as taking over both TCP and UDP. DNS is handled separately per path: EBPF_LOCAL_DNS_MODE and EBPF_SHARED_DNS_MODE both default to hijack. IPv6 on the local path is governed by EBPF_LOCAL_IPV6_MODE, defaulting to auto.

Above the data path sits the sing-box configuration. The module keeps general sing-box configuration, including DNS, routing and the Clash API, under config/singbox/confdir/. Nodes and subscriptions are grouped under data/catalog/<group ID>/, each group holding meta.json and provider.json. At startup the module generates provider, outbound and eBPF configuration into runtime/, which the README says should not be edited by hand. Local routing rule sets live in config/singbox/rules/local/ and are editable; remote SRS rule resources live under config/singbox/rules/remote/ and are managed by a remote provider.

Installing the module and starting the service

Releases ship two packages. The standard package, named NetProxy_<version>_<build>.zip, contains sing-box, the NetProxy native components, the module WebUI, zashboard, the CLI and eBPF, and is the default recommendation. The with-manager package, NetProxy_<version>_<build>_with-manager.zip, adds an Android manager APK that can optionally be installed during flashing. The README states both packages have identical proxy capability, and that the standard package is also the default download target for module self-update.

Download the ZIP from the Releases page and flash it in Magisk, KernelSU or APatch. When updating an existing module, the installer asks whether to keep existing data or do a clean install, and a timeout defaults to keeping existing data. Flashing while booted applies the new version in the background without a reboot; flashing from Recovery requires a reboot afterward.

After flashing, import a node and select it. All commands need root, and the README's quick start uses su -c with the full module path:

su -c '/data/adb/modules/netproxy/netproxyctl node add "vless://..."'
su -c '/data/adb/modules/netproxy/netproxyctl node list'
su -c '/data/adb/modules/netproxy/netproxyctl node use <group ID>/<node tag>'

Subscriptions follow the same pattern. The name argument can be omitted, in which case the module derives it from the Profile-Title, the file name or the URL host, in that order:

su -c '/data/adb/modules/netproxy/netproxyctl sub add https://example.com/sub'
su -c '/data/adb/modules/netproxy/netproxyctl sub list'
su -c '/data/adb/modules/netproxy/netproxyctl sub update <group ID>'

Then start the service and check the mode. The default outbound mode is rule:

su -c '/data/adb/modules/netproxy/netproxyctl service status'
su -c '/data/adb/modules/netproxy/netproxyctl service start'
su -c '/data/adb/modules/netproxy/netproxyctl mode rule'

The README notes AUTO_START defaults to 0, so the service does not come up on boot until you enable it in the manager or set AUTO_START=1 in config/module.conf. Do that only after you have confirmed the node and configuration work.

Hand-written node files and the mistakes they invite

The module's native components convert single links, node files, Clash YAML and subscriptions into the sing-box providers the module needs. Importing through the manager or CLI is the recommended path. Hand-writing a node file is possible but has sharp edges, and the README documents them plainly.

A hand-written node file must be a complete sing-box configuration fragment whose top level is an outbounds array. You cannot drop a single outbound object in as the file root. The README gives a SOCKS5 example with type, tag, server, server_port, version, username and password fields, then imports it with node import.

{
  "outbounds": [
    {
      "type": "socks",
      "tag": "fr-socks",
      "server": "proxy.example.com",
      "server_port": 1080,
      "version": "5"
    }
  ]
}

Two field-level traps are worth repeating. The sing-box outbound protocol field is type, not protocol as in Xray configuration. And tags direct, block, Proxy and Auto-Fastest are reserved; do not use them as node labels. Local file imports append nodes to the default local configuration group, so tags should be unique within that group. The README also warns against manually editing provider.json inside data/catalog/, because a malformed file prevents the corresponding group from loading.

Where NetProxy-Magisk is the wrong choice

The root requirement is the first filter, and the kernel requirement is the second. The README states the constraint without hedging: eBPF inbound needs BPF, cgroup v2 and cgroup socket attach enabled in the kernel, and hotspot sharing needs usable TC eBPF support. A kernel that does not satisfy this cannot start this version. That is a hard failure mode, not a degraded mode, and it is the single most likely reason an installation goes nowhere.

The second limitation is diagnostic. Because the module deliberately does not touch iptables, nftables or policy routing, you lose the familiar place to look when traffic goes somewhere unexpected. The README points you at logs/service.log for module service, subscription updates and transparent proxy logs, and logs/sing-box.log for the core. That is where you debug, and it is a different workflow from reading packet counters in a firewall chain.

The third is configuration surface. There is a CLI with many subcommands, a WebUI, an Android manager, a Clash API and a Service API dashboard, plus a set of config files split between module.conf, ebpf.conf, the sing-box confdir, the catalog and the runtime directory. The README's own warning about runtime/ being generated and not hand-edited is a signal that the layering is real. If you want a single toggle, this is more machinery than you need.

How it differs from Clash-based Magisk modules

The most direct alternative in the same niche is a Clash-family Magisk module, which typically pairs a Clash Meta or Mihomo core with a Clash API and a dashboard. The practical differences are the core and the interception layer.

NetProxy-Magisk runs sing-box as the core, and its import pipeline converts Clash YAML and subscriptions into sing-box providers. So Clash-format subscription links are still usable as input, but the runtime configuration, the outbound schema and the rule resources are sing-box's, including the SRS rule format under config/singbox/rules/remote/. If your existing setup depends on Clash-specific rule providers or on YAML you have hand-tuned, expect to translate rather than copy.

The interception layer is the bigger split. This module takes traffic through cgroup eBPF and explicitly leaves iptables, nftables and policy routing alone. Clash-based modules commonly rely on iptables or nftables redirection rules. Which is better depends on your kernel: eBPF gives per-cgroup control and avoids firewall rule ordering, but it fails outright on kernels without cgroup v2 and socket attach, where a firewall-based module might still work. The README's own compatibility list (Magisk, KernelSU, APatch) is broader than the kernel list, which is the constraint that actually decides.

Licence, upkeep and what an upgrade costs you

The repository is licensed GPL-3.0 and ships a NOTICE file alongside the LICENSE. If you redistribute the module or build on its source, the GPL-3.0 obligations attach to that redistribution. This is a statement about the licence identifier in the repository, not legal advice; read the licence text and the NOTICE before shipping anything derived from it.

On maintenance, the last push to the main branch was on 2026-08-29, and releases in the days before that include v8.1.0 and v8.1.1 on 2026-08-26 and a nightly pre-release on 2026-08-29. The repository is not archived. That is the extent of what the metadata supports.

The upgrade path is the part worth planning for. The standard package is the default self-update download target, so routine updates do not require the with-manager build. When you flash an update, the installer offers to keep existing data or do a clean install, and a timeout defaults to keeping existing data. Keeping data preserves your nodes, subscriptions and configuration across the upgrade; a clean install does not. The README does not document a rollback procedure, so a clean install taken by mistake has no described way back. Flashing while booted applies the new version in the background without a reboot, while a Recovery flash needs one.

Editorial conclusion

Adopt NetProxy-Magisk if you have a rooted device, a kernel with BPF, cgroup v2 and cgroup socket attach, and you want per-app or tethered proxying without a VPN slot. Do not adopt it if you cannot root, or if your kernel lacks TC eBPF and you depend on hotspot sharing. Before flashing, verify the kernel capabilities the README lists and check whether your device is on the standard package or needs the with-manager build.

Frequently asked questions

Official sources

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