Local & Integrated Modes

When patching with NPatch you must choose one: --manager (Local mode) or --embed (Integrated mode). The two are mutually exclusive on CLI. The difference is where modules come from and whether the patched APK can run standalone.

Local Mode (--manager)

Patches apps without embedding modules. Scope is configured dynamically by NPatch Manager without re-patching; runtime may temporarily use the last synchronized cache.

At runtime, the injected Xposed environment uses the target package name to query NPatch Manager (package top.nkbe.npatch) for modules and scope. Scope remains authoritative in the Manager database; the Remote API does not let the target app choose its own modules.

The loader first connects to the Manager Service. If that Binder is temporarily unavailable, it queries the Manager ConfigProvider. Only when both are unavailable does it reuse the target app's last successfully synchronized module cache. The Manager does not need to remain in the foreground, but it must be installed and reachable to add or remove modules and synchronize current configuration.

The patched APK contains its own bootstrap files:

• assets/npatch/loader.bin (loader dex)
• assets/npatch/so/<arch>/libnpatch.so (arm64-v8a and x86_64)
• android.permission.QUERY_ALL_PACKAGES (to resolve installed modules and the Manager)

The loader and native core are loaded from the patched APK, not extracted from the Manager APK. The Manager is responsible only for modules, scope, Remote data, and management operations.

Example

java -jar jar-v<verName>-<verCode>-release.jar --manager target.apk

Good For

• Your own device, long-term use
• Adjusting modules or scope at any time without re-patching
• Patching multiple apps managed by a single Manager
• Needing higher signature bypass levels (Extreme / Seccomp are exclusive to this mode)

Limitations

• NPatch Manager must be installed on the device
• If the Manager is temporarily unavailable, the last synchronized module cache may continue working, but scope changes, module paths, and Remote data stop updating
• Patched APK and Manager versions may need to match — very old Managers may not recognize new patches

Integrated Mode (--embed)

Patches apps with modules built in. Patched apps run independently without the Manager but cannot dynamically manage configuration. Ideal for devices without NPatch Manager.

Patching bundles module APKs into the output at assets/npatch/modules/<package>.apk. At startup the Loader loads modules directly from assets without asking the Manager for a module list or scope. Integrated Remote data is stored in the target app's own data directory, so separate target apps do not share a module's data.

Patching adds corresponding Xposed metadata to the manifest (xposedmodule, xposeddescription, xposedminversion).

Example

java -jar jar-v<verName>-<verCode>-release.jar --embed module1.apk --embed module2.apk target.apk

--embed can be repeated, once per module.

Good For

• Distributing patched APKs to people who don't have the Manager
• Deploying the same patch across many devices
• Fixed module combinations that don't need dynamic switching

Limitations

• Module versions are locked at patch time — updating modules requires re-patching
• Output APK size increases (contains all module APKs)
• Cannot disable individual embedded modules at runtime
• Signature bypass capped at High (2): Extreme and Seccomp are not allowed in this mode

Comparison

Item	Local (--manager)	Integrated (--embed)
Manager required	For configuration and sync; cached runtime fallback is available	No
Module source	Manager on device	Embedded in APK assets
Dynamic module switching	Yes (via Manager)	No (requires re-patch)
Standalone distribution	Not recommended; only existing cache works without Manager	Yes
Patched APK size	Smaller	Larger (includes modules)
Max signature bypass	Seccomp (4)	High (2)
CLI flag	--manager	--embed <module.apk>
Mutual exclusion	Cannot use with --embed	Cannot use with --manager

Can I Mix Both?

Yes — on the same device you can have app A patched with Local mode and app B patched with Integrated mode. They don't interfere. The Manager only sees Local mode apps; Integrated mode apps operate independently.

Remote API Differences

In Local mode, module UIs and injected Legacy/API 101/API 102 runtimes converge on the same Remote Store in the Manager. The top.nkbe.npatch.remote Provider validates the caller UID, module package, and scope before returning a Binder.

Integrated mode has no Manager endpoint and uses a host-local Store. If the same module is embedded into several apps, each app gets isolated Remote Preferences, Remote Files, and native-library cache. This matches Android's per-app data isolation.

Other Options

Regardless of mode, these options work with both:

• --sigbypasslv 0~4 — Signature bypass level (defaults to High, Integrated mode ≤ 2)
• --useMicroG — Redirect GMS calls to community MicroG (e.g., ReVanced GmsCore), adds fake-signature metadata and FAKE_PACKAGE_SIGNATURE permission to manifest
• --injectdex — For apps with isolated processes (e.g., browser renderers), ensures proper loading
• --provider — Inject file picker (from MT Manager) to manage data directory files without Root
• --debuggable — Mark app as debuggable
• --allowdown / -r — Set output versionCode to 1, allowing future downgrades

Full CLI options: Usage. Manager capabilities: Manager & Shizuku.

How to Choose

Quick decision guide:

• Personal use, will adjust modules → Local mode
• Distributing to others → Integrated mode
• Single device, fixed modules, don't want to install Manager → Integrated mode
• Modules update frequently → Local mode (Integrated requires re-patching each time)
• App has strong signature verification, needs Extreme / Seccomp bypass → Local mode only