Skip to content
Back to search

android-emulator

A containerized emulator with a bundled MCP server and Android QA Agent skills.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/danielhathaway--android-emulator/badge.svg)](/listings/danielhathaway--android-emulator)

HTML

<a href="/listings/danielhathaway--android-emulator"><img src="/api/listings/danielhathaway--android-emulator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 205 lines
  1. # Android emulator runner
  2. An **Android 15 / API 35**, Google APIs, x86_64 emulator in Docker. A Python CLI
  3. lets a Codex chat install APKs, inspect and operate the UI, run instrumentation
  4. tests, and download screenshots and logs. No local Android SDK, Python packages,
  5. network API server, or MCP server is required by the client.
  6. ## Requirements and platform support
  7. - **Runner:** a Linux x86_64 Docker Engine host with working `/dev/kvm` and
  8. hardware virtualization enabled. Current Ubuntu LTS releases are suitable.
  9. A VM needs nested virtualization. Docker Desktop on macOS/Windows is not a
  10. supported emulator host. Passing `--platform linux/amd64` on an ARM machine
  11. does not supply KVM or make this emulator accelerated.
  12. - **Client:** Python 3.12+, Docker CLI with Compose v2.20+ on Ubuntu, Windows,
  13. or macOS. Windows/macOS clients use a remote Linux runner through a Docker
  14. SSH context. The Python CLI uses argument arrays and writes image bytes
  15. directly, including on Windows.
  16. - Start with 4 CPU cores, 8 GiB RAM, and 20 GiB free disk on the runner for one
  17. emulator. Each session is limited to 2 CPUs and 4 GiB RAM; reserve additional
  18. capacity for concurrent sessions, builds, and Docker images.
  19. - Build app APKs in the app project's existing Gradle environment. This image
  20. contains emulator tooling, not an app build toolchain. Native libraries in the
  21. APK must support x86_64; ARM-only APKs are not supported by this runner.
  22. ## Configure the Linux host
  23. Install Docker Engine and the Compose plugin using the
  24. [Docker Ubuntu guide](https://docs.docker.com/engine/install/ubuntu/).
  25. Enable virtualization in BIOS/UEFI and, for VMs, on the outer hypervisor. Check
  26. the host:
  27. ```sh
  28. ls -l /dev/kvm
  29. stat -c %g /dev/kvm
  30. ```
  31. If `/dev/kvm` is absent, fix host virtualization before starting a container.
  32. The user connecting to Docker needs permission to use its daemon. Docker access
  33. provides administrative power on that host; use a dedicated runner you control.
  34. This configuration assumes standard rootful Docker Engine, without user namespace
  35. remapping. Rootless Docker/device mappings need separate host configuration.
  36. On the **client**, copy `.env.example` to `.env` in this directory. Set `KVM_GID`
  37. to the numeric group printed above, from the **Docker host**, not the client.
  38. Review the [Android SDK terms](https://developer.android.com/studio/terms) and set
  39. `ACCEPT_ANDROID_LICENSES=yes` to authorize accepting SDK licenses while building.
  40. Alternatively, pass `build --accept-licenses` to authorize that individual build.
  41. No shell profiles or existing Android installations are modified.
  42. ### Local Ubuntu client
  43. From this directory:
  44. ```sh
  45. cp .env.example .env
  46. # Edit .env with the host KVM group ID and license decision.
  47. python3 android_runner.py doctor
  48. python3 android_runner.py build
  49. python3 android_runner.py --session chat-one start
  50. ```
  51. ### Windows/macOS or another remote client
  52. Set up SSH authentication and verify the runner's host key first. The SSH user
  53. must be able to run Docker on the remote host without an interactive sudo prompt.
  54. Create a context once:
  55. ```sh
  56. docker context create android-linux --docker host=ssh://runner-user@runner-host
  57. ```
  58. Create the local `.env` as above. On Windows use `Copy-Item .env.example .env`.
  59. Then:
  60. ```sh
  61. python3 android_runner.py --context android-linux doctor
  62. python3 android_runner.py --context android-linux build
  63. python3 android_runner.py --context android-linux --session chat-one start
  64. ```
  65. On Windows replace `python3` with `py -3`. Pass `--context android-linux` on
  66. **every** subsequent command, or set `DOCKER_CONTEXT=android-linux` in the client
  67. environment. APK uploads and artifact downloads use Docker's connection; the app
  68. repository and its paths do not need to exist on the remote runner.
  69. `doctor` checks the Docker connection, host architecture, Compose availability,
  70. and configuration. It cannot prove KVM is usable: `start` checks acceleration in
  71. the container and waits for Android boot completion **and** package-manager
  72. readiness. Allow several minutes on the first boot. If startup fails, the session
  73. is retained for diagnosis:
  74. ```sh
  75. python3 android_runner.py --session chat-one status
  76. python3 android_runner.py --session chat-one boot-log
  77. python3 android_runner.py --session chat-one stop
  78. ```
  79. The SDK command-line tools archive is pinned and SHA-256 checked. The API is
  80. fixed at 35; stable emulator, platform-tools, and API 35 system-image revisions
  81. are resolved during each build. The image records them in
  82. `/opt/android-sdk-packages.txt`. Builds are therefore not bit-for-bit reproducible.
  83. Keep the resulting image by digest in your private registry if you need identical
  84. tool versions across runners. Review SDK distribution terms before sharing images.
  85. The image currently uses the still available `sdkmanager` and `avdmanager` tools;
  86. Google marks `sdkmanager` deprecated in favor of Android CLI.
  87. ## Test an app
  88. Use a unique session name per chat. Commands below assume a local/default Docker
  89. context; add the remote context option when needed.
  90. ```sh
  91. python3 android_runner.py --session chat-one install /path/to/app-debug.apk
  92. python3 android_runner.py --session chat-one launch com.example.app
  93. python3 android_runner.py --session chat-one ui --output artifacts/chat-one/ui.xml
  94. python3 android_runner.py --session chat-one screenshot --output artifacts/chat-one/screen.png
  95. ```
  96. Inspect the UI XML and compute the center of a target's bounds, then interact:
  97. ```sh
  98. python3 android_runner.py --session chat-one tap 540 960
  99. python3 android_runner.py --session chat-one text "hello world"
  100. python3 android_runner.py --session chat-one swipe 540 1500 540 500 --duration 300
  101. python3 android_runner.py --session chat-one key KEYCODE_BACK
  102. python3 android_runner.py --session chat-one logs --output artifacts/chat-one/logcat.txt
  103. ```
  104. The coordinates above are examples; derive actual coordinates from the current
  105. UI tree. `text` supports printable ASCII without `%`; use app instrumentation
  106. for Unicode and richer input. Custom-drawn UI elements may not appear in the
  107. accessibility hierarchy and can need app-specific instrumentation.
  108. If launcher resolution fails, specify the activity:
  109. ```sh
  110. python3 android_runner.py --session chat-one launch com.example.app --activity com.example.app/.MainActivity
  111. ```
  112. Build the app and test APKs in your app project, then run AndroidX instrumentation:
  113. ```sh
  114. python3 android_runner.py --session chat-one install /path/to/app-debug-androidTest.apk
  115. python3 android_runner.py --session chat-one instrument com.example.app.test/androidx.test.runner.AndroidJUnitRunner --output artifacts/chat-one/instrumentation.txt
  116. ```
  117. The CLI returns nonzero if the runner does not report `OK (N tests)` or reports
  118. a crash/failure. Other instrumentation runners may have different output formats;
  119. use the `adb` escape hatch and inspect their results explicitly.
  120. Additional ADB commands run inside the selected container:
  121. ```sh
  122. python3 android_runner.py --session chat-one adb -- shell getprop ro.build.version.sdk
  123. python3 android_runner.py --session chat-one adb -- shell pm clear com.example.app
  124. ```
  125. Do not use raw `adb` output redirection for screenshots on Windows; use the
  126. `screenshot` command to preserve bytes. This version deliberately publishes no
  127. ADB ports, so host Gradle `connectedDebugAndroidTest` cannot discover it. Install
  128. the two APKs and use `instrument` as above. An MCP wrapper can call this CLI later
  129. if chats need tool-based access without shell access.
  130. ## Isolation and cleanup
  131. Each session maps to a Compose project named `codex-android-<session>` and has
  132. one emulator with its own writable AVD. No host directories, Docker socket,
  133. ports, or persistent data volumes are mounted in the emulator. KVM is the only
  134. device passed through; it does not require `privileged: true`. Android can access
  135. the network through Docker's normal networking. App backend access is something
  136. you must configure for your app's deployment.
  137. `start` refuses to overwrite an existing session. To reset it, explicitly stop
  138. and start it again:
  139. ```sh
  140. python3 android_runner.py --session chat-one stop
  141. python3 android_runner.py --session chat-one start
  142. ```
  143. `stop` removes the session container and its device data; downloaded artifacts
  144. and the shared Docker image remain. Always collect evidence before cleanup.
  145. Multiple clients using the **same session name and Docker host** share a device;
  146. there is no scheduler, lock manager, automatic expiry, or tenant authentication.
  147. Use unique names and trusted clients. Containers sharing a kernel and KVM are not
  148. a hardened boundary for hostile tenants. No browser viewer is bundled initially;
  149. the CLI provides screenshots for visual inspection.
  150. ## Development checks
  151. ```sh
  152. python3 -m unittest discover -s tests -v
  153. python3 -m py_compile android_runner.py
  154. bash -n entrypoint.sh
  155. docker compose --env-file .env config --quiet
  156. ```
  157. Unit tests use mocked Docker calls and temporary files. Actual image builds,
  158. KVM startup, and APK testing need the Linux host described above.
  159. References: [Android emulator acceleration](https://developer.android.com/studio/run/emulator-acceleration),
  160. [emulator command line](https://developer.android.com/studio/run/emulator-commandline),
  161. [ADB](https://developer.android.com/tools/adb),
  162. [SDK Manager](https://developer.android.com/tools/sdkmanager).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.