# Android emulator recipe

URL: https://briq.cloud/cookbook/android-emulator

> 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).

Tags: sandbox, testing, android

Guide:

- [Run an Android emulator](https://briq.cloud/docs/guides/run-an-android-emulator.md): Give the agent an Android emulator in a sandbox, to install an app, drive it with adb and read the screen.

## Run it

CLI:

```bash
briq run android-emulator
```

MCP:

```ts
briq_run({ recipe: "android-emulator", wait: true })
```

REST:

```bash
curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "android-emulator",
    "wait": true
  }'
# → { "briqs": [{ "id": "bq_…", … }], "outputs": { "SANDBOX_HOST": "…" }, … }

# ... when done, for each briq id
curl -X DELETE https://api.briq.cloud/v1/briqs/<id> \
  -H "Authorization: Bearer $BRIQ_API_KEY"
```

briq.yaml:

```yaml
stack: app
services:
  sandbox:
    recipe: android-emulator
    # its defaults, each a field you can set:
    # image: ghcr.io/briq-cloud/sandbox:kvm
    # size: large
    # volume: { gb: 40 }
```

## Fields

Set them beside `recipe`, in briq_run or a briq.yaml service, as a GitHub Actions service.

| Name | Type | Options | Default | What it does |
| --- | --- | --- | --- | --- |
| `image` | string | — | "ghcr.io/briq-cloud/sandbox:kvm" | Another tag of ghcr.io/briq-cloud/sandbox, or any Debian or Ubuntu image with sh, curl and apt. An image with the SDK in /opt/android-sdk skips the download |
| `env` | record | { key: string \| { secret, value?, literal?, scope?, hosts?, locations? } } | {} | Added to the sandbox's environment. A credential as { secret: NAME, value }. One only the steps need (a clone, a private registry) as { secret: NAME, value, scope: "boot" }: a variable of the steps, then gone, never in the environment briq_exec runs in. A credential the code calls an API with, as { secret: NAME, value, hosts: ["api.stripe.com"] }: a placeholder here, the real value put in by the team's credential gateway on the way to those hosts only. A team secret (briq_secrets) as { secret: NAME, scope: "team" }: the same, with the value held by the team |
| `steps` | object[] | — | — | Shell commands run in /work at each start, before the sandbox is ready: [{ run: "git clone https://x:$GITHUB_TOKEN@github.com/acme/shop ." }, { run: "npm ci" }]. A failed step fails the start; briq_logs shows why |
| `cmd` | string \| string[] | — | — | The long-lived process, after the steps. Default: none (the sandbox waits for commands). A server here keeps serving on $PORT |
| `size` | enum | pico, micro, nano, small, medium, large, xlarge | "large" | large by default. medium works, with a smaller guest. xlarge for several apps or heavy builds. Set ANDROID_AVD_MEMORY (MB) and ANDROID_AVD_CORES in env to change the guest; ANDROID_SYSTEM_IMAGE for another image |
| `volume` | object | { gb? } | {"gb":40} | The volume at /work: { gb } |
| `files` | record | { key: string \| { base64 } } | — | Boot files, written at each start: { "/work/check.py": "…" } |

## Outputs

Returned by `briq_run` once the stack is healthy. Hosts resolve inside your team network; secrets are generated per run.

| Output | Value |
| --- | --- |
| `SANDBOX_HOST` | `sandbox.<stack>.internal` |
| `WORKDIR` | `/work` |
| `PORT` | `8080` |

## What it runs

| Briq | Image | Ports | Size | Volume |
| --- | --- | --- | --- | --- |
| sandbox | `ghcr.io/briq-cloud/sandbox:kvm` | 8080 | large | 40 GB at /work |

## When to use it

* Install an APK, drive it with `adb` and read the screen.
* Test an Android app without a device or a desktop.
* Anything the [kvm-sandbox](https://briq.cloud/cookbook/kvm-sandbox) does, with Android booted.

```
briq_run({ recipe: "android-emulator" })
```

The run returns once Android has booted. Then:

```
briq_files_put({ ..., path: "/work/app.apk" })
briq_exec(["adb", "install", "/work/app.apk"])
briq_exec(["adb", "shell", "input", "tap", "540", "1200"])
briq_exec(["sh", "-c", "adb exec-out screencap -p > /work/s.png"])
briq_files_get({ ..., path: "/work/s.png" })
```

## Tips

* **The first start takes about 2 minutes**: it downloads the Android SDK and system image (5 GB) into `/work/sdk`. Later starts take about 30 to 40 seconds.
* **Licence**: the first start accepts the [Android SDK License Agreement](https://developer.android.com/studio/terms).
* **Every start is a cold boot**: the emulator keeps no state in memory. Apps and data stay on `/work/avd`.
* **`large` by default** (4 CPUs, 8 GB). `medium` works with a smaller guest. The guest gets half the RAM, at most 4 GB, and all CPUs.
* **Change the guest in `env`**: `ANDROID_AVD_MEMORY` (MB), `ANDROID_AVD_CORES`, `ANDROID_SYSTEM_IMAGE` (default `system-images;android-34;google_apis;x86_64`).
* **arm64 apps run** through the image's translation layer, slower than x86\_64 apps.
* **Long commands**: `briq_exec` with `async: true`, then `briq_exec_result`.
* **Logs**: `/work/emulator.log`. Pro and Team plans.
