android-emulator-harness

Android Emulator Harness (headless, WSL/Linux, Maestro-driven)

Specializations (e.g. camera/mask) sit ON TOP of this kernel and override only the parts they must.

Runtime/package manager. Examples use bun/bunx; substitute your own runner (npm/npx, pnpm/pnpm dlx, or yarn) wherever they appear. The Android tooling itself (adb, emulator, Maestro, the JDK) is unaffected.

Environment gotchas (verify once per machine)

• KVM group. x86/x86_64 emulation needs /dev/kvm; the user must be in the kvm group: sudo gpasswd -a $USER kvm (needs a real terminal for the password). No relogin if you launch under sg kvm -c "...". Symptom if missing: x86_64 emulation currently requires hardware acceleration!.
• JDK 17 must be the active java for sdkmanager/avdmanager/Maestro. Maestro 2.x aborts on Java 8 with ERROR: Java 17 or higher is required; it reads the java on PATH, so exporting JAVA_HOME alone is not enough; prepend it to PATH. Symptom: bare ~/.maestro/bin/maestro --version fails until you do.
• EAS builds/artifacts. If eas isn't on PATH, install eas-cli and use it directly, or use the Expo MCP mcp__expo-mcp__* tools if your host provides them.
• GPU. Under WSL there is usually no GPU passthrough (/dev/dri absent); on native Linux you may have one. Either way the default software GLES is fine for UI/logic; only GPU-compute workloads (e.g. MediaPipe) need the swangle override, which the specialized camera skill covers.
• Resolve binaries explicitly and put JDK 17 on PATH; don't trust a stale PATH emulator or the system java. This one block gets you to an operating state:

  # ANDROID_HOME varies by OS: Linux (Android Studio default) $HOME/Android/Sdk, macOS $HOME/Library/Android/sdk
  export ANDROID_HOME="${ANDROID_HOME:-$HOME/Android/Sdk}"
  # JDK 17 home is OS/distro-specific; point this at wherever your JDK 17 lives.
  #   Debian/Ubuntu: /usr/lib/jvm/java-17-openjdk-amd64   macOS: $(/usr/libexec/java_home -v 17)
  export JAVA_HOME="${JAVA_HOME:-/usr/lib/jvm/java-17-openjdk-amd64}"
  export PATH="$JAVA_HOME/bin:$PATH"          # so Maestro's wrapper sees Java 17
  SDK="$ANDROID_HOME"; EMU="$SDK/emulator/emulator"; ADB="$SDK/platform-tools/adb"
  # modern SDKs install to cmdline-tools/latest/bin; older/hand-installed to cmdline-tools/tools/bin
  CLT="$(ls -d "$SDK"/cmdline-tools/latest/bin 2>/dev/null || ls -d "$SDK"/cmdline-tools/*/bin 2>/dev/null | head -1)"
  SDKMGR="$CLT/sdkmanager"; AVDMGR="$CLT/avdmanager"
  MAESTRO="$HOME/.maestro/bin/maestro"
  # preflight: java -version → 17; $ADB version; $MAESTRO --version → 2.x