HOA runs OpenHarmony HAP apps on Android without modifying them

An experimental bridge between two app ecosystems

HarmonyOS and Android split their app formats years ago, and HOA, short for Harmony on Android, attacks that wall from an unusual direction: it runs OpenHarmony and HarmonyOS HAP application packages on Android devices with no modification to the app. The project is explicit about its status as an experiment under active development. The core runtime is standing, ArkTS page rendering and native .so loading have both been verified end to end, but a large number of system APIs remain unimplemented and compatibility is limited.

That honesty is worth taking seriously, because the achievement here is technical rather than practical today. Getting one HAP to launch on an Android phone means solving bytecode execution, rendering, native library loading, resource parsing, and device protocol emulation at once. HOA does all five, which makes it one of the more interesting compatibility projects in the mobile open-source scene even while only some HAPs run correctly.

What works today

The capability table in the README separates what functions from what does not. ArkTS page rendering works, drawing through SurfaceView and Skia with compatibility for both SDK 5.0 and 6.0 ABC formats. HAP installation and startup work, including ZIP parsing, streaming decompression, and multi-process slot management across five slots. resources.index parsing handles both the V1 format from OHOS 5.0 and the V2 format from SDK 6.0.

On the native side, closed-source .so files load without RUNPATH through topological dependency resolution, and C++ STL support through libc++_shared passes for strings, containers, threads, exceptions, and RTTI. The HDC protocol runs over TCP port 8710 with install, uninstall, shell, and file-send support, enough for DevEco Studio to recognize an Android device as a target. Permission mapping is partial, with normal permissions like INTERNET mapped automatically and dangerous ones needing manual handling, and lifecycle support covers the main callbacks with intermediate states still missing.

How the runtime is built

HOA is built on the ArkUI-X Android build system, with targeted adaptations across seven repositories so the runtime can load and execute HAPs in their native OHOS format. The ETS virtual machine executes the modules.abc bytecode from inside the HAP, and the ACE engine renders the resulting UI tree onto an Android SurfaceView. The switch happens at the Java layer: setOhosHapMode(true) sets an environment variable that crosses JNI into the ETS VM and activates the OHOS compatibility path during module routing, which automatically handles the ABC record name format differences between SDK 5.0 and 6.0.

The full flow from package to pixels looks like this:

┌─────────────────────────────────┐
│  HAP (entry.hap)                │
│  ├── module.json                │
│  ├── ets/modules.abc            │  ← OHOS 原生字节码
│  ├── libs/arm64-v8a/*.so        │  ← OHOS 闭源 .so（musl ABI）
│  ├── resources.index            │
│  └── resfile/                   │
└──────────┬──────────────────────┘
           │ HapInstaller 解压 + ELF patch (libc.so → libb.so)
           ▼
┌─────────────────────────────────┐
│  HOA Application                │
│  ├── StageApplication           │  ← ArkUI-X Android 适配器
│  ├── libarkui_android.so        │  ← 内嵌 ETS VM + ACE 渲染引擎
│  ├── libb.so (musl bridge)      │  ← musl ABI 桥接（pthread/stdio/dirent/signal）
│  └── OHOS HAP Mode Patches      │  ← 7 仓库定向适配
└──────────┬──────────────────────┘
           │
           ▼
┌─────────────────────────────────┐
│  Android SurfaceView            │
│  └── Hello World (ArkUI)        │
└─────────────────────────────────┘

Building the whole stack from source is a serious commitment, measured in hours and roughly 100GB of disk for sources and artifacts:

build_all.sh (ArkUI-X → libb.so → sync → APK)

或分步：
repo init (HOA manifest) → prebuilts_download.sh → build.sh → build_musl_bridge.sh → sync_arkui_x.sh → gradlew assembleDebug

The musl ABI bridge

The hardest problem in the whole project is native code. HarmonyOS native libraries are compiled against musl, Android's bionic libc is a different implementation, and HAPs ship closed-source .so files that cannot be recompiled. HOA's answer is libb.so, a musl ABI bridge that provides the OHOS-side symbols, covering pthread, stdio, dirent, and signal, so the HarmonyOS libraries run unmodified on top of Android's linker.

Wiring it in takes two tricks. An ELF patch rewrites each library's DT_NEEDED entry, replacing libc.so with libb.so so dependencies resolve against the bridge instead of bionic. Then elf_load_with_deps performs topological dependency loading for .so files that ship without RUNPATH, walking the graph and loading each library in the right order. With that in place, the STL tests through libc++_shared pass completely, which is the milestone that turned the project from a rendering demo into something that can host real applications with native components.

HDC protocol and DevEco Studio integration

The developer-experience piece is the HDC daemon. HOA implements OHOS's device connector protocol over TCP port 8710, supporting install, uninstall, shell, and file send operations. The practical payoff is that DevEco Studio, HarmonyOS's official IDE, recognizes an Android phone running HOA as a valid device target, which enables one-click deployment of a HAP straight from the IDE.

For anyone developing HarmonyOS apps without HarmonyOS hardware, that closes a real gap: build on a workstation, deploy over HDC to an Android test device, and iterate. It also explains one of the project's deployment requirements, since the test path uses adb to launch a dedicated DevTestActivity with auto-launch enabled. Production use skips that activity and goes through the app's install-and-start flow: pick a HAP file, install it, and launch it from the main screen, on any Android 11 or newer arm64 device.

Limits and cautions

The known-limitations list is refreshingly specific. HAP compatibility is partial: apps depending on unimplemented system APIs white-screen or crash. The ArkUI-X rendering pipeline is unoptimized, so complex pages stutter. Each HAP gets its own process, so running several at once creates memory pressure. Long sessions can leak resources, and the README suggests restarting the app after extended testing.

Several subsystems are simply not there yet: the full Bundle Manager, background services, and distributed multi-device features are unimplemented, and more than seventy HDS components are exported as mocks that behave correctly but look noticeably different from the originals. The sharpest warning concerns security: the HDC daemon has no authentication mechanism on its default port 8710, so the project is suitable for development and debugging only, never for production devices. Treat HOA as a research and testing tool today, watch the progress notes as the API coverage grows, and keep it off any device that holds data you care about until the security posture changes.

Editorial conclusion

HOA is a genuinely novel piece of engineering: OpenHarmony ABC bytecode executing through an embedded ETS VM, Skia rendering into an Android SurfaceView, musl-linked native libraries running over an ELF-patched ABI bridge, and an HDC daemon that makes DevEco Studio treat an Android phone as a HarmonyOS target. It is also exactly what the README says it is, an early experiment with partial compatibility and a development-only security posture. For developers who need to test HAP behavior without HarmonyOS hardware, or anyone tracking cross-platform runtime work, it is a project worth following as the missing system APIs land.

Frequently asked questions

Official sources

1. harmony-on-android/HOA on GitHub
2. Issues
3. README
4. Releases