Docs › Android emulators on the workers

Android emulators on the workers

An Android emulator takes 4 to 10 GB of memory while it runs. Several of them at once (one per coding session, say) fill even a big Mac. sparehand emulator boots them on your other machines instead. They run headless there, and adb on this computer reaches each one at a serial of its own:

sparehand emulator setup myworker            # once per machine: the SDK, the emulator, a system image
serial=$(sparehand emulator start Pixel_9)   # boots it on a free worker, prints 127.0.0.1:15555
export ANDROID_SERIAL=$serial                # adb, Gradle and test runners use it from here on
adb install app.apk && adb shell am start -n com.example/.MainActivity
adb exec-out screencap -p > screen.png
sparehand emulator stop $serial

start exits 255 when no worker can take the emulator, the same rule as sparehand run. Boot one on this computer then. A script or an agent does it like this:

if serial=$(sparehand emulator start Pixel_9); then export ANDROID_SERIAL=$serial
else emulator -avd Pixel_9 -no-window & fi   # (exit 255: nothing free; boot it here)

Commands

The dashboard shows the running emulators on each machine's card, with a Stop button for owners. The Activity tab lists every start, stop and setup.

Which machine gets it

Only machines that emulator setup has made ready are used, in this order:

1. A machine at home before a cloud one. A Linux or Windows (WSL) machine before a Mac. Then the one with the most memory free.
2. A machine must have room the way it would for a job: on, not paused, not strained, a job slot free, SPAREHAND_MIN_MEM free, CPU and GPU not busy. It also needs the emulator's memory plus 2 GB free.
3. A Mac takes at most SPAREHAND_EMULATOR_MAC_MAX emulators (1) at a time.
4. A stopped cloud worker (sparehand cloud add) is started for it only when nothing at home can take it, and never past its caps.

A running emulator counts as a job on its machine. It holds a job slot, its memory counts, and sparehand status lists it. A job that arrives later is the one stopped when the machine runs out of memory, not the emulator.

When it stops by itself

• Idle: after SPAREHAND_EMULATOR_IDLE_MIN minutes (30) with no adb traffic to it. The worker watches the bytes on the emulator's adb connections, so a test that is still running keeps it alive and a forgotten one goes.
• Too long: after SPAREHAND_EMULATOR_MAX_HOURS hours (8) in all.
• On a cloud worker, its limit is also what remains of the machine's hours for today (--max-hours-day). When a cap is reached the hub stops the emulator, and the VM then stops after its idle time. While an emulator runs, the VM counts as busy, so its idle power-off doesn't end a test halfway.

An emulator that stopped by itself loses its forward and its adb connection here the next time Sparehand looks at that machine (status, list, the dashboard).

How it works

• On the worker: ~/.sparehand/android holds the SDK, the JDK it may need and the AVDs (avd/); ~/.sparehand/emulators/PORT describes a running emulator and PORT.log is its output. The emulator runs with -no-window -no-snapshot-save -no-boot-anim -no-audio -read-only, with -gpu swiftshader_indirect on Linux and -gpu host on a Mac. -read-only lets several sessions boot the same AVD at once, each from a clean state.
• Its adb port (the console port + 1) is forwarded to this computer with sparehand forward, at 127.0.0.1:15555 and up (SPAREHAND_EMULATOR_PORT). That stays clear of 5555 to 5585, which the adb server here scans by itself. Sparehand then runs adb connect, and the serial is ready when start returns.
• The emulator runs with -skip-adb-auth, so adb here needs no key on the worker. The port only listens on the worker's own 127.0.0.1, which the hub reaches through SSH. Anyone with a login on that worker could reach it too.
• An app built only for arm64-v8a still runs on an x86_64 image: Android's own translation runs it. For performance measurements, or to rule that out, use a Mac worker (arm64).
• sparehand remove NAME --clean removes all of it with the rest of ~/.sparehand.

What an administrator may need to do

emulator setup says so, with the exact command:

• **Linux and Windows (WSL): the kvm group.** The emulator needs /dev/kvm. When the user is not in its group, an administrator on the worker runs sudo usermod -aG kvm USER; on Windows, in PowerShell there: wsl -u root usermod -aG kvm USER (setup prints the right one). The new group counts from the next login, which emulator setup and start always use. On Windows, WSL needs nested virtualization (on by default in Windows 11).
• A Linux server without a desktop: a few libraries. The emulator's own libraries expect some of the system's (NSS, PulseAudio, X11 bits) even headless. Setup names the packages: sudo apt-get install -y libnss3 libpulse0 libxkbfile1 ….
• A cloud VM needs nested virtualization: on Google Cloud an Intel machine (n2, c3; not AMD's c2d) with --enable-nested-virtualization, and the build user in the kvm group.

Settings

For a coding agent, one line in its instructions does it: "Android emulators go through sparehand emulator start; use the printed serial as ANDROID_SERIAL; sparehand emulator stop when done; boot a local one only on exit 255."