Skip to content
Back to search

emuctl

Android emulators for people and AI agents: lease queue, MCP server, holder-only adb

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/trbutler4--emuctl/badge.svg)](/listings/trbutler4--emuctl)

HTML

<a href="/listings/trbutler4--emuctl"><img src="/api/listings/trbutler4--emuctl/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need the Android SDK with the emulator and at least one system image. If you have Android Studio installed, you already have both.

go install github.com/trbutler4/emuctl/cmd/emuctl@latest
emuctl init      # writes ~/.config/emuctl/config.json with one device
emuctl doctor    # checks the SDK, system image and config
emuctl serve     # boots the emulator, API on 127.0.0.1:7600

Then add the MCP server to your agent (Claude Code, Cursor, Codex, jcode, etc.):

{ "mcpServers": { "emuctl": { "command": "emuctl", "args": ["mcp"] } } }

For Claude Code: `claude mcp add emuctl -- emuctl mcp`.

With no users in the config, the API needs no token, and emuctl only allows that when it listens on loopback.

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 · 380 lines
  1. # emuctl
  2. Android emulators for people and AI agents. emuctl boots and supervises a set
  3. of emulators, hands them out through a FIFO lease queue, and exposes them over
  4. an HTTP API, a CLI and an [MCP](https://modelcontextprotocol.io) server.
  5. Use it on one laptop to give your coding agent an emulator it can install
  6. builds on, tap around in and screenshot. Or run it on a build box and share a
  7. pool of emulators with your team and CI.
  8. **Agents and LLMs:** start at [`llms.txt`](llms.txt) or
  9. [`docs/`](docs/README.md), which cover usage in short, task-focused pages.
  10. - **MCP server.** `emuctl mcp` gives agents tools to acquire a device, run
  11. `adb shell` commands, take screenshots, install APKs, reset and release.
  12. Agents don't need adb or the Android SDK on their machine.
  13. - **Lease queue.** One holder per device, FIFO across users. Ask for a specific
  14. device or any device. Leases expire without a heartbeat, so a crashed agent
  15. frees its device within `lease_ttl`.
  16. - **Supervision.** Emulators restart on crash or boot timeout, with backoff. A
  17. device takes no leases until Android has booted and unlocked. Idle devices
  18. are health-checked, and a device is only restarted on evidence it is
  19. broken, never because a check timed out. Emulators left behind by a killed
  20. `emuctl serve` are stopped on the next start.
  21. - **Clean devices.** Between leases, clear your app's data without a reboot
  22. (`"release": "clear"`) or wipe and reboot (`"release": "wipe"`). Nobody
  23. gets the device until cleanup and a health check finish. Animations are
  24. turned off after boot and on every release.
  25. - **Holder-only adb.** Optionally forward each device's adb port. Only the
  26. current holder's IP can connect, and connections are dropped when the lease
  27. ends. That's enough for `adb`, Maestro, Appium or Android Studio.
  28. - **Single static binary.** Pure Go, standard library only.
  29. ## Quick start (one machine)
  30. You need the Android SDK with the emulator and at least one system image. If
  31. you have Android Studio installed, you already have both.
  32. ```bash
  33. go install github.com/trbutler4/emuctl/cmd/emuctl@latest
  34. emuctl init # writes ~/.config/emuctl/config.json with one device
  35. emuctl doctor # checks the SDK, system image and config
  36. emuctl serve # boots the emulator, API on 127.0.0.1:7600
  37. ```
  38. Then add the MCP server to your agent (Claude Code, Cursor, Codex, jcode, etc.):
  39. ```json
  40. { "mcpServers": { "emuctl": { "command": "emuctl", "args": ["mcp"] } } }
  41. ```
  42. For Claude Code: `claude mcp add emuctl -- emuctl mcp`.
  43. With no users in the config, the API needs no token, and emuctl only allows
  44. that when it listens on loopback.
  45. ## Install
  46. ```bash
  47. go install github.com/trbutler4/emuctl/cmd/emuctl@latest # Go 1.26+
  48. nix profile install github:trbutler4/emuctl # Nix, Linux and Apple Silicon
  49. nix run github:trbutler4/emuctl -- devices # without installing
  50. ```
  51. As a flake input: `inputs.emuctl.url = "github:trbutler4/emuctl";`, then
  52. `inputs.emuctl.packages.${system}.default` or `overlays.default` for
  53. `pkgs.emuctl`.
  54. The server runs the Android emulator, so it needs hardware virtualization:
  55. Linux with `/dev/kvm`, or macOS. Clients (`mcp`, `run`, `acquire`) run
  56. anywhere. `emuctl run` also needs `adb` on PATH.
  57. ## MCP tools
  58. | Tool | |
  59. | --- | --- |
  60. | `emulator_usage` | workflow instructions for the agent |
  61. | `emulator_devices` | devices, state and holders |
  62. | `emulator_queue` | waiting leases |
  63. | `emulator_acquire` | queue for a device, blocks until ready or `wait_seconds` |
  64. | `emulator_status` | state of a lease |
  65. | `emulator_shell` | `adb shell` command, returns output and exit code |
  66. | `emulator_screenshot` | PNG of the screen as MCP image content, optionally saved to a file |
  67. | `emulator_install` | install a local APK |
  68. | `emulator_reset` | reboot, optionally wiping data, waits until ready |
  69. | `emulator_release` | release the lease |
  70. | `emulator_logs` | tail of the emulator log |
  71. The MCP process heartbeats the leases it holds and releases them when it exits.
  72. The client reads `EMUCTL_URL` (default `http://127.0.0.1:7600`) and the token
  73. from `EMUCTL_TOKEN`, the file in `EMUCTL_TOKEN_FILE`, or
  74. `~/.config/emuctl/token`. For a remote server:
  75. ```json
  76. { "mcpServers": { "emuctl": {
  77. "command": "emuctl", "args": ["mcp"],
  78. "env": { "EMUCTL_URL": "http://emu-host:7600", "EMUCTL_TOKEN_FILE": "/home/me/.config/emuctl/token" } } } }
  79. ```
  80. ## CLI
  81. ```bash
  82. emuctl devices
  83. emuctl queue
  84. emuctl run -apk app.apk -- maestro test flows/ # queue, install, connect, run, release
  85. emuctl run -reset -device pixel-1 -- ./e2e.sh
  86. emuctl acquire -note "manual QA" # hold until Ctrl-C, prints lease JSON
  87. emuctl shell LEASE pm list packages
  88. emuctl screenshot LEASE screen.png
  89. ```
  90. `run` exports `ANDROID_SERIAL`, `EMUCTL_SERIAL` (the `adb connect` target),
  91. `EMUCTL_DEVICE` and `EMUCTL_LEASE` to the command. Maestro takes the serial as
  92. `--device`:
  93. ```bash
  94. emuctl run -- sh -c 'maestro --device "$EMUCTL_SERIAL" test flows/'
  95. ```
  96. Maestro only talks to the default adb server (5037), so `run` connects the
  97. device there with `adb connect`. Don't set `ANDROID_ADB_SERVER_PORT` for Maestro.
  98. ## Stored APKs
  99. The server keeps APKs under `state_dir/apks`, by a key you choose, so agents
  100. switching branches don't re-upload or rebuild the same app. Use a key that
  101. changes exactly when the native app changes, such as an Expo native
  102. fingerprint: `android-<fingerprint>`. Entries are immutable, and the server
  103. remembers which key each device last had, skipping the install when it
  104. matches. A wipe or an ad hoc `-apk` install clears that.
  105. ```sh
  106. key=android-$(node scripts/dev-client.mjs --hash)
  107. emuctl run -apk-key "$key" -- maestro test flows/
  108. # exit 3: not stored. Build once, upload, retry:
  109. emuctl apk put "$key" app-debug.apk && emuctl run -apk-key "$key" -- maestro test flows/
  110. ```
  111. `run -apk-key` checks the store before queueing, so a miss never holds a
  112. device. Every builder must sign with the same keystore, or installing over an
  113. existing app fails with `INSTALL_FAILED_UPDATE_INCOMPATIBLE`.
  114. ## Configuration
  115. `~/.config/emuctl/config.json` (or `-config PATH`, or `EMUCTL_CONFIG`):
  116. ```jsonc
  117. {
  118. "sdk": "/path/to/android-sdk", // default: $ANDROID_SDK_ROOT, $ANDROID_HOME, then Android Studio's location
  119. "api": "127.0.0.1:7600", // HTTP API
  120. "listen": "127.0.0.1", // address for the adb forwarders
  121. "lease_ttl": "2m", // lease lifetime without a heartbeat
  122. "max_lease_ttl": "4h",
  123. "boot_timeout": "6m",
  124. "release": "none", // between leases: none | clear | wipe (see below)
  125. "release_packages": [], // packages to force-stop and `pm clear` with "clear"
  126. "release_commands": [], // adb shell commands run on every release; failure restarts the device
  127. "disable_animations": true, // animations off after boot and on release
  128. "health_interval": "2m", // idle health checks, "0" disables
  129. "users": {}, // name -> "sha256:..." token hash; empty = no auth, loopback only
  130. "devices": {
  131. "pixel-1": { "expose_port": 15601 },
  132. "tablet": { "profile": "pixel_tablet", "width": 2560, "height": 1600, "density": 320, "expose_port": 15603 }
  133. }
  134. }
  135. ```
  136. Device fields:
  137. | Field | Default | |
  138. | --- | --- | --- |
  139. | `image` | newest installed image for the host CPU | SDK package, e.g. `system-images;android-36;google_apis;arm64-v8a` |
  140. | `profile` | `pixel_7` | hardware profile (`avdmanager list device`) |
  141. | `expose_port` | none | TCP port on `listen` forwarded to the device's adb, for `adb connect` |
  142. | `ram_mb`, `cores` | 2048, 4 | |
  143. | `width`, `height`, `density` | 1080, 2400, 420 | |
  144. | `gpu` | `swiftshader` | `host` is faster on machines with a GPU |
  145. | `window` | `false` | show the emulator window instead of running headless |
  146. | `console_port` | 5600 + 2n | even, so device ports never collide with other emulators |
  147. | `avd_home`, `avd_name` | per-device AVD in `state_dir` | use an existing AVD instead |
  148. | `unlock_pin` | none | PIN entered after boot if the AVD has a screen lock |
  149. | `extra_args` | none | appended to the emulator command line |
  150. emuctl creates each device's AVD under `state_dir` (default
  151. `~/.local/share/emuctl`) on first start, with `avdmanager` if the SDK
  152. command-line tools are installed and without them otherwise. It never touches
  153. your Android Studio AVDs unless you point `avd_home` at them. To get another
  154. system image: `sdkmanager "system-images;android-36;google_apis;arm64-v8a"`, or
  155. Android Studio > Settings > Languages & Frameworks > Android SDK.
  156. Each device gets its own private adb server, so emuctl never disturbs your
  157. normal `adb` or Android Studio.
  158. ## Sharing over a network
  159. To serve other machines, add users and bind to a reachable address:
  160. ```bash
  161. emuctl add-user alice # prints alice's token once, stores only its sha256
  162. ```
  163. ```jsonc
  164. { "api": "0.0.0.0:7600", "listen": "0.0.0.0", "users": { "alice": "sha256:..." }, ... }
  165. ```
  166. Give each user their token. They put it in `~/.config/emuctl/token` and set
  167. `EMUCTL_URL=http://your-host:7600`. `emuctl new-token` prints a token and its
  168. hash separately, for configs managed elsewhere (e.g. Nix).
  169. Security notes:
  170. - The API uses bearer tokens over plain HTTP. Run it on a trusted network or
  171. VPN (Tailscale, WireGuard), put a TLS reverse proxy in front, or use SSH
  172. (below).
  173. - The adb forwarders (`expose_port`) aren't authenticated by token. They admit
  174. only the current lease holder's IP. On a shared network, firewall those ports
  175. so only your clients can reach them. Leave `expose_port` unset if clients
  176. only use the MCP tools or the API.
  177. - Anyone holding a lease has full control of that emulator, including
  178. `adb shell`. Treat emulators as disposable and use `"release": "wipe"` when
  179. sharing them with people you don't trust (`clear` only resets the listed apps).
  180. ## Between leases
  181. When a lease ends, the device stays out of the pool until emuctl has:
  182. 1. dropped the old holder's adb connections,
  183. 2. cleaned up according to `release`,
  184. 3. run `release_commands` and turned animations off (skipped for `wipe`),
  185. 4. health-checked the device.
  186. | `release` | Effect | Keeps installed APKs |
  187. | --- | --- | --- |
  188. | `none` | Nothing. Fastest; the next user sees the last app state. | yes |
  189. | `clear` | `am force-stop` and `pm clear` each of `release_packages`. Seconds, no reboot. | yes |
  190. | `wipe` | Reboot with `-wipe-data`. Minutes. | no |
  191. For an app under test, `clear` is usually right: every lease starts signed
  192. out with fresh app data, and stored APKs don't need reinstalling.
  193. ```jsonc
  194. "release": "clear",
  195. "release_packages": ["com.example.app", "com.example.app.dev"],
  196. "release_commands": ["rm -f /data/local/tmp/my-test-marker"]
  197. ```
  198. A failing cleanup step restarts the device. Health checks run on release and
  199. every `health_interval` on idle devices. A device is restarted only on
  200. evidence it is broken (its adb port is closed, or Android reports it is no
  201. longer booted). A check that times out or can't reach adb is logged and
  202. counted in `unverified` on `emuctl devices`, but the device stays in service,
  203. so a slow host never restarts healthy emulators.
  204. ## Sizing
  205. Emulators under CPU contention boot slowly and drop to `adb offline`, and an
  206. overloaded host tends to fail every device, not just the extra one. `emuctl
  207. doctor` warns when the configured `cores` or `ram_mb` add up to more than the
  208. host has. Measure under real load: one report saw a 5th emulator on a 48-core
  209. host time out on boot while the others ran tests.
  210. ## Over SSH (no open ports)
  211. If clients can already SSH to the emulator host, nothing else needs to be
  212. exposed. Keep `api` and `listen` on loopback (the defaults), add users, and
  213. point clients at an `ssh://` URL:
  214. ```bash
  215. export EMUCTL_URL=ssh://me@emu-host # or ssh://emu-host:2222/127.0.0.1:7600
  216. emuctl devices
  217. emuctl run -- sh -c 'maestro --device "$EMUCTL_SERIAL" test flows/'
  218. ```
  219. The client runs `ssh -L` itself: one forward for the API, opened on first
  220. use, and one per leased device's adb port, opened when needed. `run`,
  221. `acquire` and `emulator_acquire` return the local end of that forward as the
  222. serial. Tunnels close when the command or MCP server exits. emuctl uses your
  223. `ssh` binary, so `~/.ssh/config`, agents and keys all work. Auth must be
  224. non-interactive (keys or an agent).
  225. Through a tunnel every connection reaches the server from loopback, so the
  226. holder-only check on adb ports can't tell SSH users apart. Anyone who can SSH
  227. to the host can already reach its loopback ports. Tokens still separate users
  228. and leases.
  229. ## Running as a service
  230. systemd user unit:
  231. ```ini
  232. [Unit]
  233. Description=emuctl
  234. After=network-online.target
  235. [Service]
  236. ExecStart=%h/go/bin/emuctl serve
  237. Restart=on-failure
  238. [Install]
  239. WantedBy=default.target
  240. ```
  241. ## Metrics
  242. `emuctl serve` exposes Prometheus metrics at `/metrics`. By default it shares
  243. the API listener and needs a token like every other endpoint:
  244. ```yaml
  245. scrape_configs:
  246. - job_name: emuctl
  247. authorization: {credentials_file: /etc/prometheus/emuctl-token}
  248. static_configs: [{targets: ["emulator-host:7600"]}]
  249. ```
  250. Or set `"metrics_addr": "127.0.0.1:9600"` to serve `/metrics` on its own
  251. listener without a token. Bind it to loopback or a monitoring network only.
  252. | Metric | Labels | |
  253. | --- | --- | --- |
  254. | `emuctl_device_state` | device, state | 1 for the current state (stopped, starting, booted, crashed, resetting) |
  255. | `emuctl_device_leased` | device | 1 while leased |
  256. | `emuctl_device_state_seconds` | device | time in the current state |
  257. | `emuctl_device_health_unverified` | device | inconclusive checks in a row (restarts at 3) |
  258. | `emuctl_device_last_healthy_timestamp_seconds` | device | last passing check or boot |
  259. | `emuctl_emulator_boots_total` | device, result | ok, timeout |
  260. | `emuctl_emulator_boot_seconds` | device | start to booted and unlocked |
  261. | `emuctl_emulator_exits_total` | device | unexpected exits |
  262. | `emuctl_device_restarts_total` | device, reason | broken, unverified, cleanup, wipe, request |
  263. | `emuctl_stale_emulators_reaped_total` | device | leftovers from an earlier emuctl |
  264. | `emuctl_health_checks_total` | device, trigger, result | trigger idle or release; result healthy, unknown, broken |
  265. | `emuctl_leases_granted_total`, `emuctl_leases_ended_total` | device (, reason) | reason released or expired |
  266. | `emuctl_lease_queue_wait_seconds` | device | request to grant |
  267. | `emuctl_lease_duration_seconds` | device, reason | grant to end |
  268. | `emuctl_queue_length` | want | device name or `any` |
  269. | `emuctl_queue_oldest_wait_seconds` | | |
  270. | `emuctl_release_cleanup_seconds`, `emuctl_release_cleanup_failures_total` | device | |
  271. | `emuctl_apk_installs_total` | device, source, result | source store or upload; result installed, skipped, failed |
  272. | `emuctl_apk_install_seconds` | device, source | |
  273. | `emuctl_apk_uploads_total` | result | stored, exists, rejected |
  274. | `emuctl_apk_store_entries`, `emuctl_apk_store_bytes` | | |
  275. | `emuctl_adb_forward_connections_total` | device, result | accepted, refused (not the lease holder) |
  276. | `emuctl_adb_forward_open_connections` | device | |
  277. | `emuctl_http_requests_total`, `emuctl_http_request_seconds` | route (, code) | route is the pattern, e.g. `GET /v1/leases/{id}` |
  278. | `emuctl_build_info` | version | |
  279. Labels stay bounded: device names come from the config, and lease IDs, users
  280. and APK keys are never labels. Use the logs for per-lease detail.
  281. Alert rules for the common failures (no booted device, flapping or
  282. slow-booting devices, a growing queue, failing cleanups or installs, API
  283. errors) are in
  284. [`contrib/prometheus/emuctl-alerts.yml`](contrib/prometheus/emuctl-alerts.yml).
  285. ## HTTP API
  286. Bearer token auth (none in open mode), JSON.
  287. | Method | Path | |
  288. | --- | --- | --- |
  289. | GET | `/v1/devices` | states, holders |
  290. | GET | `/v1/queue` | waiting leases |
  291. | POST | `/v1/leases` `{"device","note","ttl_seconds"}` | enqueue, `device` empty for any |
  292. | GET | `/v1/leases/{id}?wait=30s` | long-poll |
  293. | POST | `/v1/leases/{id}/renew` | heartbeat |
  294. | DELETE | `/v1/leases/{id}` | release or leave the queue |
  295. | POST | `/v1/leases/{id}/install` | body is the APK |
  296. | POST | `/v1/leases/{id}/reset?wipe=1` | reboot, optionally wipe |
  297. | POST | `/v1/leases/{id}/shell` `{"command"}` | `adb shell`, returns `{"output","exit_code"}` |
  298. | GET | `/v1/leases/{id}/screenshot` | `image/png` |
  299. | GET | `/v1/devices/{name}/logs` | emulator log tail |
  300. | POST | `/v1/devices/{name}/restart` | restart a device you hold or nobody holds |
  301. ## Development
  302. ```bash
  303. go test -race ./...
  304. nix build # runs the tests too
  305. nix flake check
  306. ```

Ratings and comments

Sign in to rate this skill.

Sign in

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