Guides

Run an Android emulator

Give the agent an Android emulator in a sandbox, to install an app, drive it with adb and read the screen.

Recipe: Android emulator

An agent builds or tests an Android app. The android-emulator recipe is the KVM sandbox with an Android 14 emulator booted. It is ready once Android has booted, and the agent drives it with adb. First, connect your agent.

Install this APK in an Android emulator, open it and tell me what the first screen shows.

briq_run({ recipe: "android-emulator" })
→ bq_7k2w9x1m5qzd sandbox (ghcr.io/briq-cloud/sandbox:kvm) running · cost so far … · sleeps at 18:42 UTC unless used

briq_files_put({ briq: "bq_7k2w9x1m5qzd", files: { "/work/app.apk": { base64: "…" } } })

briq_exec({ briq: "bq_7k2w9x1m5qzd", cmd: ["adb", "install", "/work/app.apk"] })
→ Success

briq_exec({ briq: "bq_7k2w9x1m5qzd", cmd: ["adb", "shell", "monkey", "-p", "com.acme.shop", "1"] })

briq_exec({ briq: "bq_7k2w9x1m5qzd", cmd: ["sh", "-c", "adb exec-out screencap -p > /work/s.png"] })
briq_files_get({ briq: "bq_7k2w9x1m5qzd", path: "/work/s.png" })
  1. briq_run starts a large microVM (4 CPUs, 8 GB) with a 40 GB volume at /work.
  2. The boot starts the emulator (Pixel 6, Android 14, x86_64) and waits for sys.boot_completed. briq_run returns after that.
  3. briq_exec runs adb, emulator, sdkmanager and avdmanager. The AVD is in /work/avd, one per system image (pixel_6-android-34-google_apis-x86_64 by default); /work/avd/current holds the name of the running one.

Drive the app

briq_exec({ briq: "bq_…", cmd: ["adb", "shell", "input", "tap", "540", "1200"] })
briq_exec({ briq: "bq_…", cmd: ["adb", "shell", "input", "text", "hello"] })
briq_exec({ briq: "bq_…", cmd: ["adb", "shell", "input", "keyevent", "KEYCODE_ENTER"] })
briq_exec({ briq: "bq_…", cmd: ["adb", "logcat", "-d", "-t", "100"] })

The screen is 1080 × 2400. Take a screenshot after each step and read it with briq_files_get. To see the interface elements and their positions, dump them: adb exec-out uiautomator dump /dev/tty.

Build in the sandbox

Clone and build in steps, as in the sandbox. They run after Android has booted:

briq_run({
  recipe: "android-emulator",
  steps: [{ run: "git clone --depth 1 https://github.com/acme/shop ." }]
})

Apps for arm64

An app built only for arm64 runs through the system image's translation layer. It starts slower than an x86_64 app.

Sizes

SizeGuest
mediumabout half the RAM, all CPUs
large (default)4 GB, 4 CPUs
xlarge4 GB, 8 CPUs

Set ANDROID_AVD_MEMORY (MB) and ANDROID_AVD_CORES in env to change the guest. ANDROID_SYSTEM_IMAGE picks another system image, for example system-images;android-35;google_apis;x86_64. It is downloaded into /work/sdk at the next start.

When it does not start

briq_logs saysFix
android did not boot in 240 s and the emulator logUse large, or set ANDROID_AVD_MEMORY lower
plan_limit/dev/kvm needs a Pro or Team plan
The recipe is not in briq_catalog/dev/kvm is not available here

The emulator log is /work/emulator.log.

Good to know

  • The first start takes about 2 minutes. It downloads the Android SDK and system image (5 GB) into /work/sdk.
  • Every start is a cold boot. No memory is kept while the sandbox sleeps. A wake takes about 30 to 40 seconds, and the emulator starts again. Apps and data on /work/avd stay.
  • Long commands. A build or a test run takes minutes: async: true, then briq_exec_result (Run a long command).
  • x86_64 only. There is no GPU: the screen is drawn by software.
  • Licence. The first start accepts the Android SDK License Agreement.

On this page

Free to try

Try briq, on us.

Every new account starts with €10 of credits. No card.

Start building

How can we help?

Message to the briq team