Hybrid Mount is a mount orchestration metamodule for KernelSU and APatch. It merges module files into Android partitions through a unified policy engine backed by three mount backends:

• OverlayFS — layered mounts for broad compatibility.
• Magic Mount — bind-mount for direct path replacement or fallback.
• Kasumi — LKM-backed routing with runtime hide, spoof, and stealth features.

A built-in SolidJS WebUI provides graphical management, live state monitoring, and configuration editing.

Releases are published in three flavors — see Build Flavors for a detailed comparison. Unless noted otherwise, the rest of this README describes the full build.

English   简体中文   繁體中文   日本語   Español   Italiano   Русский   Українська   Tiếng Việt

• Features
• Build Flavors
• Quick Start
• Mount Modes
• WebUI
• Language Support
• Configuration
• Kasumi
• Policy Reference
• CLI
• Architecture
• Build
• Operational Notes
• License

Hybrid Mount is released in three flavors, each targeting a different use case:

The full flavor includes all supported mount backends (OverlayFS, Magic Mount, Kasumi), the SolidJS WebUI, the Unix-socket daemon with HTTP/SSE, the CLI, and the Kasumi LKM assets. Use Full when Kasumi-backed routing or auxiliary hide/spoof features are required. Built with Cargo features kasumi (which implies control-plane).

The lite flavor strips the Kasumi LKM and all Kasumi-related features (hide, spoof, stealth, kstat rules, uname spoofing, etc.) but keeps the WebUI, daemon, CLI, and both OverlayFS and Magic Mount backends. Choose Lite if:

• Your kernel doesn't support loading external LKMs.
• You don't need runtime hide/spoof capabilities.
• You want a smaller download while keeping the WebUI and daemon management interface.

Lite builds use the feature set control-plane only (--no-default-features --features control-plane). The WebUI's Kasumi panel is hidden automatically.

The nano flavor is a config-only build (--no-default-features — no Cargo features enabled). It strips the WebUI, daemon, CLI, and all control-plane infrastructure. What remains is a minimal binary that reads config.toml, generates a mount plan, and executes it — then exits. Key characteristics:

• No runtime daemon — no background process, no socket, no WebUI, no CLI subcommands.
• No WebUI — the webroot/, launcher.png, and service.sh assets are removed from the package.
• Mount-only operation — the binary runs during boot, mounts everything according to the config, and terminates.
• Default mode is magic — Nano ships with default_mode = "magic" pre-set in its config, preferring bind mounts when no daemon is available to manage ext4 images.
• Module mode markers — install-time volume-key selection writes an empty overlay or magic marker in each managed module root, and Nano reads that instead of a whitelist. Marker filenames are matched case-insensitively.
• No resident Hybrid Mount process — after boot-time mounting completes, the Nano binary exits.

Choose Nano if you want predictable, daemon-free mount orchestration with a smaller runtime surface.

• Three backends, one policy engine — assign paths to OverlayFS, Magic Mount, or Kasumi with per-path granularity.
• Deterministic planning — conflicts are detected at plan time, not discovered randomly at boot.
• Built-in WebUI — manage modules, edit configuration, monitor runtime state, and control Kasumi features in full builds.
• Kasumi runtime integration — LKM autoload, mirror routing, mount hiding, maps/statfs spoofing, UID hiding, uname spoofing, and kstat rules.
• Config caching — runtime config cache with incremental patching and immediate apply support.
• Recovery-friendly — stale runtime files are cleaned automatically; misconfigurations can be reset via api config-reset.
• Automation-friendly — JSON-over-Unix-socket daemon protocol + HTTP API for scripting or external controllers.

1. Install KernelSU or APatch on your device.
2. Download the latest Hybrid Mount full, lite, or nano release ZIP from GitHub Releases.
3. Flash the ZIP through your root manager's module installer.
4. Reboot. Hybrid Mount will auto-detect your environment and apply the default overlay policy.

# Check runtime status
hybrid-mount daemon status

# List detected modules
hybrid-mount api modules-list

To access the WebUI (Full/Lite flavors), open your root manager app (KernelSU or APatch), find Hybrid Mount in the modules list, and tap it — the manager will launch the WebUI in an embedded WebView.

# /data/adb/hybrid-mount/config.toml
[rules.my_module]
default_mode = "magic"

[rules.my_module.paths]
"system/bin/problematic_binary" = "ignore"

The OverlayFS backend supports two storage strategies for the upper/work layers:

• ext4 (default) — creates an ext4 disk image. Persists across reboots, supports xattr.
• tmpfs — uses a tmpfs mount. Volatile, lighter weight, but lost on reboot.

overlay_mode = "ext4"

Hybrid Mount includes a SolidJS-based WebUI served by the daemon over a local TCP socket (HTTP/SSE). CLI and automation clients communicate over a Unix socket. The daemon prints the WebUI access URL to logcat on startup.

The WebUI is designed to be opened directly from your root manager app (KernelSU or APatch manager) — tap the module entry and the manager will launch the WebUI in an embedded WebView. No external browser is required on-device.

• Status dashboard — live mount statistics, active partitions, storage mode, daemon health.
• Module management — list all detected modules with their effective mount modes; apply mode changes interactively.
• Configuration editor — full config.toml editing with validation, including per-module path rules.
• Kasumi control panel — LKM status, rule listing, feature toggles, uname configuration, maps/kstat rules (Full flavor only).

The WebUI currently ships with these locales:

• English (en-US, default)
• Español (es-ES)
• Italiano (it-IT)
• 日本語 (ja-JP)
• Русский (ru-RU)
• Українська (uk-UA)
• Tiếng Việt (vi-VN)
• 简体中文 (zh-CN)
• 繁體中文 (zh-TW)

README documentation is available in English, Simplified Chinese, Traditional Chinese, Japanese, Spanish, Italian, Russian, Ukrainian, and Vietnamese.

The WebUI runs on http://127.0.0.1:<random-port> with a cryptographic access token. The daemon manages the lifecycle — no separate web server needed. On-device, open through your root manager's WebView; remotely, forward the port via ADB.

Default path: /data/adb/hybrid-mount/config.toml.

moduledir = "/data/adb/modules"
overlay_mode = "ext4"
default_mode = "overlay"
daemon_startup_mode = "on-demand"

[rules.viper4android]
default_mode = "magic"

[rules.viper4android.paths]
"system/etc/audio_policy.conf" = "overlay"

[rules.sensitive_module]
default_mode = "kasumi"

[rules.sensitive_module.paths]
"system/bin/helper" = "kasumi"
"system/etc/placeholder" = "ignore"

Kasumi is the LKM-backed backend. Beyond mount routing, it provides a suite of runtime hide and spoof capabilities.

Setting kasumi.enabled = true makes the backend available. The Kasumi runtime is actually enabled when at least one of these conditions is met:

• The mount plan contains a Kasumi-managed module or path.
• An auxiliary feature is configured (hidexattr, mount hide, maps spoof, statfs spoof, UID hiding, uname spoof, cmdline replacement, kstat rules, or user hide rules).

# Status and diagnostics
hybrid-mount kasumi status
hybrid-mount kasumi version
hybrid-mount kasumi features
hybrid-mount kasumi hooks
hybrid-mount kasumi list          # list active rules
hybrid-mount lkm status

# Runtime control
hybrid-mount kasumi apply-config-runtime
hybrid-mount kasumi clear
hybrid-mount kasumi release-connection
hybrid-mount kasumi invalidate-cache
hybrid-mount kasumi fix-mounts

# Uname spoofing (scoped or global)
hybrid-mount kasumi set-uname --mode scoped <release> <version>
hybrid-mount kasumi clear-uname --mode scoped
hybrid-mount kasumi restore-uname-global

# Rule management
hybrid-mount kasumi rule add --target /system/bin/tool --source /data/adb/modules/my_module/system/bin/tool
hybrid-mount kasumi rule merge --target /system/lib64 --source /data/adb/modules/my_module/system/lib64
hybrid-mount kasumi rule hide --path /system/bin/su
hybrid-mount kasumi rule delete --path /system/bin/old_tool
hybrid-mount kasumi rule add-dir --target-base /system/lib64 --source-dir /data/adb/modules/my_module/system/lib64
hybrid-mount kasumi rule remove-dir --target-base /system/lib64 --source-dir /data/adb/modules/my_module/system/lib64

When multiple policies could apply to a path, evaluation order is:

1. Path-level override — rules.<module>.paths["<path>"]
2. Module-level default — rules.<module>.default_mode
3. Global default — default_mode

Hybrid Mount also recognizes marker files in module directories. These markers are expected to be regular files; only the filename is used. Marker filenames are matched case-insensitively for ASCII letters, so DISABLE, Disable, and disable are treated as the same marker.

If multiple case variants of the same marker exist in one directory, cleanup operations remove all matching variants.

• One problematic binary on bind mount, rest on overlay: set module default to overlay, override the binary path to magic.
• Temporarily exclude a conflicting file: set the path to ignore.

hybrid-mount [OPTIONS] [COMMAND]

┌─────────────────────────────────────────────┐
│                  config.toml                  │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│              Inventory Discovery              │
│         Scan module tree, classify entries    │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│              Mount Planner                    │
│    Evaluate rules (path > module > global)    │
│    Generate overlay / magic / kasumi plan     │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│              Executors                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│  │ OverlayFS│ │  Magic   │ │   Kasumi     │ │
│  │ executor │ │  Mount   │ │   executor   │ │
│  └──────────┘ └──────────┘ └──────────────┘ │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│            Runtime State + Daemon             │
│   Persist state → Unix socket → WebUI/CLI     │
└─────────────────────────────────────────────┘

The executor is driven by a typestate state machine (src/core/controller.rs): MountController<Init> → StorageReady → Planned → Executed. Each transition represents one pipeline stage, ensuring the mount process is always in a well-defined state.

src/
├── conf/          Config schema, TOML loader, CLI definition, handlers
├── domain/        Core types: MountMode, ModuleRules, path matching
├── partitions/    Managed partition auto-discovery
├── core/
│   ├── inventory/ Module discovery and listing
│   ├── ops/       Mount plan generation and per-backend execution
│   ├── daemon/    Unix + TCP dual-protocol daemon (CLI + WebUI/SSE)
│   ├── api/       Payload builders for WebUI endpoints
│   ├── startup/   Boot sequence, recovery, retry logic
│   ├── storage/   Shared storage helpers (ext4 image, tmpfs)
│   └── runtime_state/ Daemon state persistence
├── mount/
│   ├── overlayfs/ OverlayFS backend (ext4 image / tmpfs)
│   ├── magic_mount/ Bind-mount backend
│   └── kasumi/    Kasumi rule compilation, runtime, status
├── sys/           Low-level: mount syscalls, LKM load/unload, Kasumi UAPI
└── utils/         Logging, path utilities, validation

webui/
├── src/
│   ├── routes/    Page components (Status, Config, Modules, Kasumi, Info)
│   ├── components/ Shared UI components (NavBar, Toast, Skeleton)
│   ├── lib/       API bridge, stores, codecs, i18n
│   └── locales/   9-language internationalization

xtask/             Build and release automation
module/            Module packaging scripts and static assets

• Rust nightly (from rust-toolchain.toml)
• Android NDK r27+ and cargo-ndk
• Node.js 20+ and pnpm (for WebUI)

# Full release package (binary + WebUI + Kasumi) → output/
cargo run -p xtask -- build --release --flavor full

# Lite release package (binary + WebUI, no Kasumi) → output/
cargo run -p xtask -- build --release --flavor lite

# Nano release package (config-only, no WebUI/CLI/daemon) → output/
cargo run -p xtask -- build --release --flavor nano

# Binary only (skip WebUI)
cargo run -p xtask -- build --release --skip-webui

# Local arm64 debug build
./scripts/build-local.sh

# Local lite debug build
./scripts/build-local.sh --lite

# Local nano debug build
./scripts/build-local.sh --nano

# Local build with prebuilt Kasumi LKM .ko assets (full only)
./scripts/build-local.sh --release --kasumi-lkm-dir /path/to/kasumi-lkm

# WebUI dev server (hot reload)
cd webui && pnpm install && pnpm dev

# Lint everything
cargo run -p xtask -- lint
cd webui && pnpm lint

# Run tests
cargo +nightly test
cd webui && pnpm test

The release profile uses opt-level = 3, lto = "fat", codegen-units = 1, strip = true, and panic = "abort" to reduce binary size.

Every change must pass the following CI checks (defined in .github/workflows/):

• cargo fmt --all -- --check
• cargo clippy --all-targets -- -D warnings (warnings are errors)
• cargo test --all-targets --workspace
• WebUI: pnpm lint + pnpm test
• License header check on all source files

cargo clippy --all-features (what xtask lint runs) only checks the full flavor. When making changes, also verify that the lite (--no-default-features --features control-plane) and nano (--no-default-features) flavor combinations compile. Code touching Kasumi must be behind #[cfg(feature = "kasumi")]; code touching the daemon/CLI/WebUI API must be behind #[cfg(feature = "control-plane")].

• Mount source auto-detection: fresh installs detect the runtime environment automatically. Only set mountsource explicitly if auto-detection fails.
• Recovery from bad config: run hybrid-mount api config-reset to reset to defaults, then reapply rules incrementally. Use gen-config to regenerate a fresh config file.
• Config caching: the runtime maintains a cached config. Use api config-patch --apply-runtime to apply changes immediately, or restart the daemon.
• Kasumi LKM (full builds only): the LKM must match the running kernel. Use lkm_kmi_override if the auto-detected KMI is incorrect.
• kasumi clear: clears runtime state and releases kernel connection. Existing kernel-side rules may persist until LKM reload.
• Binary size: prefer dependency feature trimming and profile tuning before invasive refactoring.

Licensed under Apache-2.0.