Hybrid Mount
Hybrid Mount is a mount orchestration metamodule for KernelSU and APatch.
It merges module files into Android partitions with three mount modes:
- OverlayFS for compatibility-first layered mounts.
- Magic Mount (bind mount) for direct path binding or fallback.
- HymoFS for explicit HymoFS routing and runtime-backed hide/spoof features.
The runtime is designed for predictable boot behavior, conflict visibility, and policy-level control.
Table of Contents
- Design Goals
- Mount Modes
- Architecture
- Repository Layout
- Configuration
- HymoFS
- Policy Behavior Matrix
- CLI
- Build
- Operational Notes
- License
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.
Mount Modes
Hybrid Mount currently supports three backend strategies:
overlay: use OverlayFS for module paths that can be merged safely.magic: use Magic Mount bind mounts for direct per-path replacement or fallback.hymofs: route module paths through the HymoFS mirror/runtime when the module or path explicitly requires it.
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/hymofs/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, and HymoFS 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
ββ 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 umount operations (debug-only). |
enable_overlay_fallback |
bool | false |
When overlayfs is unavailable, allow falling back to Magic Mount for planned overlay modules. |
default_mode |
overlay | magic | hymofs |
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
enable_overlay_fallback = false
default_mode = "overlay"
[rules.my_module]
default_mode = "magic"
[rules.my_module.paths]
"system/bin/tool" = "overlay"
"vendor/lib64/libfoo.so" = "ignore"
HymoFS
HymoFS is the third mount backend in Hybrid Mount. It is kernel/LKM-backed and is used when a module/path is explicitly routed to hymofs, or when HymoFS-only runtime features are required.
It currently covers two categories of work:
mode = "hymofs"mount mapping for modules or paths that should resolve from the HymoFS mirror tree.- Auxiliary runtime features such as stealth/hide-xattr behavior, mount hiding,
/proc/<pid>/mapsspoofing,statfsspoofing, UID hiding, uname/cmdline spoofing, and per-file kstat spoof rules.
When runtime turns on
Setting hymofs.enabled = true only makes the backend available. Hybrid Mount actually enables the HymoFS runtime when at least one of these is true:
- the generated mount plan contains at least one HymoFS-managed module/path
- an auxiliary feature is configured (
enable_hidexattr,enable_mount_hide,enable_maps_spoof,enable_statfs_spoof,hide_uids,cmdline_value,uname*,maps_rules,kstat_rules, or persisted user hide rules)
Behavior details that matter in practice:
enable_hidexattris a compatibility umbrella and effectively turns onstealth,mount_hide,maps_spoof, andstatfs_spoofmount_hide.path_patternandstatfs_spoof.{path,spoof_f_type}also count as enabling those features- the CLI disable commands now clear those subordinate structured fields so
disablereally disables the feature instead of leaving it implicitly active
Key config fields
| Key | Purpose |
|---|---|
hymofs.enabled |
Master switch for HymoFS integration. |
hymofs.ignore_protocol_mismatch |
Allow operation even when userspace/kernel protocol versions differ. |
hymofs.lkm_autoload |
Try to auto-load the HymoFS LKM during startup. |
hymofs.lkm_dir / hymofs.lkm_kmi_override |
LKM search directory and optional KMI override. |
hymofs.mirror_path |
Runtime mirror root used by HymoFS rules, default /dev/hymo_mirror. |
hymofs.enable_kernel_debug |
Toggle kernel-side debug output. |
hymofs.enable_stealth |
Explicit stealth mode toggle. |
hymofs.enable_hidexattr |
Compatibility umbrella for stealth + hide/spoof helpers. |
hymofs.enable_mount_hide / hymofs.mount_hide.path_pattern |
Hide mounts globally or with a path pattern. |
hymofs.enable_maps_spoof / hymofs.maps_rules |
Enable maps spoofing and install inode/device rewrite rules. |
hymofs.enable_statfs_spoof / hymofs.statfs_spoof.* |
Enable generic or path-scoped statfs spoofing. |
hymofs.hide_uids |
Hide selected UIDs from HymoFS-aware queries. |
hymofs.uname.* |
Structured uname spoof fields. |
hymofs.cmdline_value |
Replacement kernel cmdline payload. |
hymofs.kstat_rules |
Per-target stat metadata spoof rules. |
Example
[hymofs]
enabled = true
lkm_autoload = true
mirror_path = "/dev/hymo_mirror"
enable_mount_hide = true
[rules.my_module]
default_mode = "hymofs"
[rules.my_module.paths]
"system/bin/su" = "hymofs"
Useful commands
# runtime/LKM status
hybrid-mount hymofs status
hybrid-mount hymofs version
hybrid-mount hymofs features
hybrid-mount lkm status
# enable/disable runtime-backed features
hybrid-mount hymofs enable
hybrid-mount hymofs disable
hybrid-mount hymofs mount-hide enable --path-pattern /dev/hymo_mirror
hybrid-mount hymofs statfs-spoof enable --path /system --f-type 0x794c7630
hybrid-mount hymofs maps add --target-ino 1 --target-dev 2 --spoofed-ino 3 --spoofed-dev 4 --path /dev/hymo_mirror/system/bin/sh
hybrid-mount hymofs kstat upsert --target-ino 11 --target-path /system/bin/app_process64 --spoofed-ino 22 --spoofed-dev 33
Operational caveat:
hymofs kstat clear-configonly removes persisted config. Existing kernel kstat spoof rules may remain until the HymoFS LKM is reloaded or the whole runtime is rebuilt.
Policy Behavior Matrix
This matrix clarifies what happens under each policy and runtime condition:
| Rule result | Backend availability | enable_overlay_fallback |
Effective behavior |
|---|---|---|---|
overlay |
OverlayFS available | any | Mount with OverlayFS. |
overlay |
OverlayFS unavailable | false |
Skip mount and report as failed planning/execution item. |
overlay |
OverlayFS unavailable | true |
Retry as Magic Mount (bind mount). |
magic |
n/a | any | Mount with Magic Mount directly. |
hymofs |
HymoFS available | any | Mount with HymoFS directly. |
hymofs |
HymoFS unavailable or disabled | any | Skip HymoFS mapping for this path/module. |
ignore |
n/a | any | Do not mount this path. |
Rule precedence
When multiple policies may apply, evaluation follows this order:
- Path-level override (
rules.<module>.paths["..."]) - Module-level default (
rules.<module>.default_mode) - Global default (
default_mode)
Practical examples
- Keep one problematic binary on bind mount while the rest of the module uses overlay:
- set module default to
overlay - set
rules.<module>.paths["system/bin/<tool>"] = "magic"
- set module default to
- Temporarily disable one conflicting file without disabling the full module:
- set
rules.<module>.paths["..."] = "ignore"
- set
- For kernels with unstable OverlayFS support:
- set
enable_overlay_fallback = trueto reduce boot-time mount failures.
- set
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+)
Hybrid-Mount/nuke-kpmcheckout for the GPL-2.0-only APatch KPM module source (HYBRID_MOUNT_KPM_DIR, or clone into./nuke-kpm)AndroidPatch/kpmcheckout for APatch KPM builds (HYBRID_MOUNT_KP_DIRorKP_DIR)- 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
# local arm64 debug package
./scripts/build-local.sh
# local package with prebuilt HymoFS LKM assets
./scripts/build-local.sh --release --hymofs-lkm-dir /path/to/hymofs-lkm
For APatch-ready release packages, export HYBRID_MOUNT_KPM_DIR to point at the Hybrid-Mount/nuke-kpm checkout, plus HYBRID_MOUNT_KP_DIR (or KP_DIR) and an Android NDK path before invoking xtask. Set HYBRID_MOUNT_BUILD_KPM=1 if you want to force a KPM rebuild instead of reusing an existing artifact.
If KPM build prerequisites are available, xtask also builds nuke_ext4_sysfs.kpm from the external KPM source repo and stages it into the module zip. Release builds require that artifact; debug builds will warn and continue when KPM prerequisites are missing.
Artifacts are produced under output/.
Operational Notes
- Fresh installs now rely on mount-source auto-detection unless
mountsourceis explicitly set inconfig.toml. - On APatch, Hybrid Mount loads
/data/adb/hybrid-mount/kpm/nuke_ext4_sysfs.kpmthrough/data/adb/ap/bin/kptools kpm load/control/unloadto callext4_unregister_sysfsbefore falling back toMNT_DETACH. - APatch runtime overrides are available through
HYBRID_MOUNT_APATCH_KP_BIN,HYBRID_MOUNT_APATCH_KPM_MODULE,HYBRID_MOUNT_APATCH_KPM_ID,HYBRID_MOUNT_APATCH_KPM_CALL_MODE,HYBRID_MOUNT_APATCH_KPM_CONTROL, andHYBRID_MOUNT_APATCH_KPM_UNUSED_NR. - 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