NetProxy-Magisk: A cgroup eBPF Transparent Proxy for Rooted Android

What NetProxy-Magisk Actually Solves

The module is not for casual users. It requires a kernel with BPF, cgroup v2, and cgroup socket attach capabilities, as the README warns. If your kernel lacks these, the module will not start. That is a hard constraint, not an optional optimization. The project also assumes you are comfortable with command-line tools or the companion Android manager, because the core configuration lives in files under the module directory, not in a simple toggle.

The eBPF and cgroup Mechanism

This design avoids the classic Android proxy problem of VPN conflicts. Since no VPN interface is created, other apps that check for VPN status will not see one. But it also means the proxy is invisible to the system, so debugging requires the module's logs and CLI, not the standard Android network settings.

Installation and First Run

The README gives a concrete example for a SOCKS5 node file. The file must be a complete sing-box configuration fragment with a top-level `outbounds` array. You cannot use a single outbound object as the root. That is a common mistake for users coming from Xray, where the field is `protocol`; sing-box uses `type`. The module's native component converts single links, node files, Clash YAML, and subscriptions into sing-box providers, but hand-written files must follow the sing-box schema exactly. The CLI exposes `node import` to load such files, and `node use default/fr-socks` to select a node by group and tag.

The Management Interfaces and Their Trade-offs

The WebUI is accessible from the module page in Magisk, KernelSU, or APatch, which is convenient for quick checks. But the CLI remains the only way to script operations like subscription updates. The `netproxyctl` command has a `--json` flag for machine-readable output, which is useful for scripts. The command set covers service control, catalog management, node operations, subscription handling, mode switching, network evaluation, app management, and eBPF status. That is a broad surface, but it also means the learning curve is steep for a proxy tool.

Configuration Files and Defaults

The default values are conservative. `AUTO_START=0` means no surprise network interception after a reboot. `OUTBOUND_MODE=rule` uses rules for routing, while `SELECTOR_MODE=urltest` means the module automatically tests node latency to pick the fastest. `EBPF_MODE=local` only intercepts local traffic, not shared, until you change it. These defaults make sense for a first install, but they also mean that out of the box, the module does nothing until you explicitly configure and start it. That is a good safety posture, but it can confuse users who expect a proxy to work immediately after flashing.

Limitations and the Kernel Dependency Problem

The module also does not support VPN mode, which means it cannot be used on devices that require a VPN for other purposes. The documentation says it does not rely on VPN mode, but that is a feature, not a bug. However, if you need both a transparent proxy and a VPN for another app, you may run into conflicts because the eBPF interception happens at the cgroup level, and the VPN interface is a separate network layer. The README does not address such coexistence scenarios.

Comparing with VPN-Based Proxy Solutions

Another alternative is a traditional iptables-based transparent proxy module, such as those that use redsocks or similar. Those modify iptables rules, which can conflict with other firewall tools and require careful rule ordering. NetProxy-Magisk explicitly avoids iptables, which is a cleaner approach but requires the eBPF kernel support. The trade-off is between compatibility (iptables works on almost any kernel) and cleanliness (eBPF avoids rule clashes).

Maintenance, Upgrades, and License

The documentation is thorough but mostly in Chinese, with an English README available. The CLI help is in Chinese, which may be a barrier for non-Chinese speakers. The project's Telegram channel is the primary support channel. There is no mention of a formal issue tracker or contribution guidelines in the provided material, but the repository is public on GitHub. The maintenance cost is moderate: you need to keep the module updated, verify kernel compatibility on each device, and understand the file-based configuration. The nightly builds indicate rapid iteration, which is good for features but means you may encounter regressions if you use pre-release versions.

Editorial conclusion

Adopt NetProxy-Magisk if you have a rooted Android device with a kernel that supports BPF, cgroup v2, and cgroup socket attach, and you need a transparent proxy that does not rely on iptables or VPN. Avoid it if your kernel lacks these features, or if you prefer a simpler VPN-based solution. Before installing, verify your kernel capabilities with `netproxyctl ebpf status`, and check that your node files use sing-box `type` fields, not Xray `protocol`. The module's default `AUTO_START=0` means you must explicitly enable boot start after testing. This is not a plug-and-play tool; it is a system-level component that requires kernel awareness and configuration care.

Official sources

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