Hybrid Mount
Hybrid Mount is a mount orchestration metamodule for KernelSU and APatch.
It merges module files into Android partitions with a hybrid strategy:
- OverlayFS when kernel/filesystem support is stable.
- Magic Mount (bind mount) as fallback or per-path override.
The runtime is designed for predictable boot behavior, conflict visibility, and policy-level control.
Table of Contents
Design Goals
- Compatibility-first mounting across diverse Android kernels.
- Deterministic behavior through explicit planning and conflict analysis.
- Operational safety with recovery-friendly defaults.
- Automation-friendly CLI for WebUI or external controllers.
Architecture
At startup, hybrid-mount follows this pipeline:
- Load config (file + CLI override).
- Scan module tree and inventory mountable entries.
- Generate an execution plan (overlay/magic/ignore).
- Apply mounts and persist runtime state.
- Emit diagnostics/conflict reports when requested.
Key implementation modules:
src/conf: config schema, loader, CLI handlers.src/core/inventory: module scanning and inventory modeling.src/core/ops: planning, execution, synchronization.src/mount: overlayfs + magic-mount backends.src/sys: filesystem/mount helpers and low-level integration.
Repository Layout
.
ββ src/ # daemon/runtime implementation
ββ module/ # module scripts and packaging assets
ββ xtask/ # build/release automation commands
ββ tools/notify/ # optional helper binary
ββ Cargo.toml # workspace + runtime crate settings
ββ README*.md # user and developer docs
Configuration
Default path: /data/adb/hybrid-mount/config.toml.
Top-level fields
| Key | Type | Default | Description |
|---|---|---|---|
moduledir |
string | /data/adb/modules |
Module source directory. |
mountsource |
string | auto-detect | Runtime source tag (e.g. KSU, APatch). |
partitions |
list|csv string | [] |
Extra managed partitions. |
overlay_mode |
ext4 | tmpfs |
ext4 |
Overlay upper/work backing mode. |
disable_umount |
bool | false |
Skip unmount operations (debug-only). |
allow_umount_coexistence |
bool | false |
Allow coexistence with existing umount behavior. |
default_mode |
overlay | magic |
overlay |
Default policy for module paths. |
rules |
map | {} |
Per-module path-level mount policy. |
Example
moduledir = "/data/adb/modules"
mountsource = "KSU"
partitions = ["system", "vendor"]
overlay_mode = "ext4"
disable_umount = false
allow_umount_coexistence = false
default_mode = "overlay"
[rules.my_module]
default_mode = "magic"
[rules.my_module.paths]
"system/bin/tool" = "overlay"
"vendor/lib64/libfoo.so" = "ignore"
CLI
hybrid-mount [OPTIONS] [COMMAND]
Global options:
-c, --config <PATH>custom config path-m, --moduledir <PATH>override module directory-s, --mountsource <SOURCE>override source tag-p, --partitions <CSV>override partition list
Subcommands:
gen-configgenerate config fileshow-configprint effective config JSONsave-config --payload <HEX_JSON>save config from WebUI payloadsave-module-rules --module <ID> --payload <HEX_JSON>update one module rule setmoduleslist detected modules
Build
Prerequisites:
- Rust toolchain from
rust-toolchain.toml - Android NDK (recommended r27+)
- Node.js 20+ (only when building WebUI assets)
Build commands:
# full package
cargo run -p xtask -- build --release
# runtime only (skip web assets)
cargo run -p xtask -- build --release --skip-webui
Artifacts are produced under output/.
Operational Notes
- If a bad config causes boot issues, regenerate a minimal config with
gen-configand reapply module rules incrementally. - For binary size optimization, prefer dependency feature trimming and release profile tuning before invasive refactors.
License
Licensed under GPL-3.0.
Hybrid Mount Developers