MiniDroid

View saved version →

---
name: minidroid
description: Use for MiniDroid, the bundled minidroid-x86_64 runtime, MiniDroidManager.apk, ART/Bionic/linker64 bootstrapping, APK lifecycle, Android resources/views, MiniDroid bridges, package/process/storage management, ADB integration, add-ons, Android compatibility packs, runtime testing, debugging, patching and release work.
---

# MiniDroid

MiniDroid is a portable Android compatibility runtime for Linux x86_64. It is not a full Android OS, emulator, VM, WSA clone, or containerized system image.

## Prime directive

Preserve the architectural goal:

**As much Android compatibility as possible, as little Android system as necessary.**

The working runtime path is conceptually:

`Linux -> Android linker64 -> Bionic -> ART -> Java core/framework -> DEX/APK -> MiniDroid host bridges`

Do not replace this with a full Android boot, system_server stack, Android VM, or emulator merely because that would be easier.

## Bundled runtime

The plugin includes the user-supplied runtime archive at:

`assets/minidroid-x86_64.zip`

Treat that archive as the project snapshot to inspect, test, patch or extract when the task needs concrete files. Do not invent files or APIs that are not present.

Before making implementation claims, inspect the current runtime and tests. Prefer evidence from the bundled files and actual executions over assumptions.

## Existing snapshot structure

The bundled archive contains, among other things:

- `bin/minidroid`
- `bin/minidroid-bridge`
- `bin/adb`
- `manager/MiniDroidManager.apk`
- `framework/framework.jar`
- `framework/framework-res.apk`
- `framework/minidroid-framework-patch.jar`
- `host/minidroid-window-x11`
- Android ART/Bionic/APEX runtime files under `rootfs/`
- tests under `TESTS/`
- `MANIFEST.sha256`
- license and third-party notice material

Read `references/PROJECT_STATE.md` for the intended engineering baseline and open work.

## Engineering rules

1. Inspect first. Do not patch blindly.
2. Preserve all working ART/Bionic/linker behavior.
3. Create a checkpoint before risky changes.
4. After each substantial change, rerun relevant regression tests.
5. Never report a UI button or backend as functional unless the actual operation succeeds.
6. Do not hide missing behavior behind unconditional PASS messages or fake return values.
7. Use explicit, diagnosable error codes for unimplemented or failed operations.
8. Keep the runtime relocatable; do not introduce absolute build paths.
9. No root, chroot, host `/apex` mount, Android SDK/JDK, Python or build tree may be required at runtime unless the user explicitly changes that requirement.
10. Respect the core compressed-size target of <=100 MiB; prefer leaving reserve rather than filling it.
11. Keep runtime data, app data, add-ons and imported images separate.
12. Preserve and update license/provenance metadata when adding binaries or libraries.

## APK runtime

An APK is not a JAR. Treat APK execution as:

`APK -> AndroidManifest.xml -> package/application/activity -> resources/assets/native libs -> framework -> MiniDroid host backend`

When debugging APK startup, separate these failure domains:

- manifest / binary AXML
- DEX / multidex
- Application bootstrap
- Looper/lifecycle
- Activity attach/state
- resources.arsc
- binary XML layout
- Views/widgets
- host window backend
- input
- JNI/native libraries
- missing framework APIs/services

Do not introduce Binder/system_server simply to satisfy one incidental framework initialization if a small compatible local façade is sufficient and semantically safe.

## GUI architecture

The product manager remains an Android app:

`MiniDroidManager.apk -> Application -> MainActivity -> Android Views -> MiniDroid graphics bridge -> Linux window`

Do not replace the product manager with Qt, GTK, Tk or another native GUI. Host-native helpers are acceptable as backend implementation details.

Wayland is preferred where practical; X11 is an acceptable fallback. The bundled snapshot includes a

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.