# Run an Android emulator

URL: https://briq.cloud/docs/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](https://briq.cloud/cookbook/android-emulator.md): An Android emulator (Pixel 6, Android 14, x86_64) running in a sandbox: it is ready once Android has booted. Use `adb` through briq_exec: `adb install app.apk`, `adb shell input tap 100 200`, `adb exec-out screencap -p > /work/s.png`, then briq_files_get. The first start downloads the Android SDK and system image (5 GB) into /work/sdk, about 2 minutes; later starts take about 30 to 40 seconds. Default size large (4 CPUs, 8 GB); medium works. Pro and Team plans. The first start accepts the Android SDK License Agreement (https://developer.android.com/studio/terms).

An agent builds or tests an Android app. The `android-emulator` recipe is the
[KVM sandbox](https://briq.cloud/docs/guides/run-microvms-in-a-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](https://briq.cloud/docs/getting-started).

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

```text
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

```text
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](https://briq.cloud/docs/guides/run-code-in-a-sandbox). They run after
Android has booted:

```text
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

| Size              | Guest                        |
| ----------------- | ---------------------------- |
| `medium`          | about half the RAM, all CPUs |
| `large` (default) | 4 GB, 4 CPUs                 |
| `xlarge`          | 4 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` says                                     | Fix                                            |
| ---------------------------------------------------- | ---------------------------------------------- |
| `android did not boot in 240 s` and the emulator log | Use `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](https://briq.cloud/docs/guides/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](https://developer.android.com/studio/terms).
