A transparent networking control plane for rooted Android.
Subscriptions · app and domain routing · DNS · TUN/eBPF · sing-box-compatible runtime · web console
| Goal | Entry point |
|---|---|
| Install and use MagicNet | Releases and v1.8.1 installation notes |
| Rebuild the product with a code agent | recipes/magicnet/ and the commands below |
| Work on the maintained implementation | generated/magicnet-android/ or the source repository |
| Audit claims and limitations | Verification, performance and provenance |
MagicNet separates the product contract from the generated implementation. The recipe says what must exist and how it is accepted; the source submodule is one concrete implementation; Releases contain the installable Android artifacts.
MagicNet is designed for rooted Android devices that need one place to manage network behavior:
- multiple subscription sources, cached state and per-source diagnostics;
- app, domain, Wi-Fi and hotspot routing policies;
- custom groups, selectors, exits and DNS behavior;
- Tailscale integration and transactional network recovery;
- TUN/eBPF boundaries with sing-box-compatible behavior;
- a multilingual web console for configuration and status;
- signed, verifiable component delivery and root-module packaging.
Changes are previewed before they are applied. Private subscriptions, credentials, device identities and raw local logs are not part of the public recipe or release source.
| Layer | Current state |
|---|---|
| Published Android package | v1.8.1 / 10609 |
| Recipe | 0.3.3 |
| Fixed implementation commit | fd0e2dabf668e9b8cd6e16f5058e06517fe110c2 |
| Fixed sing-box core | ff669d45e6562a790a49ef066340dbed5df46363 / 1.15.0-alpha.13 |
| Unreleased implementation work | process handoff, PID validation, log-memory fixes, frontend refinement, per-source conversion guards, bounded subscription observation, upstream core synchronization, connection lifecycle fixes and mobile navigation/input improvements |
The fixed source commit contains work newer than the published Android package. A successful recipe check proves that the rebuild materials are complete; it does not prove that an APK/module was built, installed on a device or validated against real traffic. Those claims are recorded separately in VERIFICATION.md.
Recipe 0.3.3 adds the core lifecycle contract: fixed upstream synchronization, handshake failure cleanup, and complete registration cleanup when flow attachment overlaps closure. It retains the subscription and recovery requirements from recipe 0.3.2. The fixed core passed host tests, Linux amd64 and Android arm64 builds and final Linux configuration/DNS checks. Measured memory results apply to the specific sing-tun lifecycle experiment; Android RSS and device traffic remain unverified. Source identities, exclusions and original evidence are tracked in the verification record.
Use the Releases page for the lightweight installer, offline package, components and checksums. The release notes document the exact scope that was built and tested.
To obtain the repository together with its fixed implementation:
git clone --recurse-submodules https://github.com/LIghtJUNction/MagicNet.git
cd MagicNet
git submodule update --init --recursive generated/magicnet-androidA local implementation build currently uses the source repository's pinned Rust, Go, Node, Java and Android toolchain contracts:
cd generated/magicnet-android
kam build -j 2See the implementation build guide before treating a local archive as a release artifact.
Requirements: Git, the Recipkg CLI, and a code agent capable of implementing and validating rooted Android software.
recipkg check recipes/magicnet
set -eu
recipe_tmp="$(mktemp -d)"
trap 'rm -rf "$recipe_tmp"' EXIT
recipkg pack recipes/magicnet \
-o "$recipe_tmp/magicnet-0.3.3.recipe.tar.gz"
recipkg check "$recipe_tmp/magicnet-0.3.3.recipe.tar.gz"
recipkg build "$recipe_tmp/magicnet-0.3.3.recipe.tar.gz" --lang zh-CNrecipkg build produces a complete implementation prompt. It does not call a model or build the software itself. Give the full generated prompt to the implementation agent, then require it to execute every item in ACCEPTANCE.md and record real results in VERIFICATION.md.
Do not hand .env files, subscriptions, credentials, device state or raw private logs to the agent or include them in a recipe archive.
recipes/magicnet/ product requirements and acceptance
recipes/magicnet-control-plane/ CLI, JSON schema, MCP and file-state contract
recipes/magicnet-network-runtime/ subscriptions, processes and recovery transactions
recipes/magicnet-packet-engine/ TUN/eBPF and sing-box compatibility
recipes/magicnet-routing-policy/ selectors, DNS and routing order
recipes/magicnet-web-console/ web workflows, i18n and visual requirements
recipes/magicnet-module-delivery/ root module, components and trusted updates
recipes/software-quality/ shared design, code and performance bar
generated/magicnet-android/ fixed implementation submodule
The repository keeps the implementation as a fixed Git submodule so recipe history and generated source history remain independently auditable.
Product behavior changes begin in the relevant recipe, interface and acceptance documents. The implementation is then changed and verified in its own repository. Only after the source commit is pushed should this repository update the submodule pointer.
The release workflow is Build and release MagicNet:
# Build artifacts without publishing a release
gh workflow run release.yml \
--repo LIghtJUNction/MagicNet \
--ref main \
-f mode=buildmode=publish is the explicit publication path. Build, quality and emulator gates use one implementation SHA; failed gates do not publish. Emulator success still does not substitute for arm64 hardware and real-network validation.
Local lightweight checks:
python3 scripts/check-recipes.py
python3 scripts/test-release.pySOURCE_AUDIT.mdrecords which fixed source was inspected.PERFORMANCE.mddistinguishes measured baselines from targets and unknowns.PROVENANCE.mdlabels documentation, source evidence, measurements, inference and unknowns.VERIFICATION.mdseparates recipe checks, source tests, package checks and device validation.
Historical source anchors
The initial observed source was fixed at 96993ea5c851b8d51cc562c3ca0766a2ca571210. The source state after code PRs #420–#423 and README PR #416 was fixed at ae4de1ce4d77f1a2a4c8d9656da8101c472fa3a0. The v1.8.0 import baseline 0dca28dd984d82333707cbf4b222596934b4d847 has the same complete Git tree as the original f13ca61b9c3477aee3b1380d71815c84b3a2a6bf source tag.
These anchors preserve auditability; they are not claims that every later recipe requirement has already been independently rebuilt and device-tested.
MagicNet is released under the MIT License. Third-party implementations, rules and tools retain their own licenses as recorded by the recipe's provenance and external prerequisite documents.