> ## Documentation Index
> Fetch the complete documentation index at: https://instabox.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Android apps

> A machine with Android 14 in it, to install and test apps with adb.

At the end of this page, your app runs on Android 14 in a machine, and you can drive it with adb and
see the phone in the dashboard. The `android` template is for testing Android apps and for agents
that drive a phone. Android runs as a container on the machine's own Linux kernel, with no emulator
and no nested VM. The machine also has everything `agent-browser` has: Docker, Node.js, Python, and
the desktop.

**1. Create an Android machine**

```bash theme={null}
instabox create --name phone --template android
```

Android is up about 20 seconds after the machine starts. Use the default size or larger. Android
uses 1 to 2 GiB of memory while it runs.

**2. Wait for Android to boot**

```bash theme={null}
instabox exec phone -- 'until [ "$(docker exec instabox-android getprop sys.boot_completed 2>/dev/null)" = 1 ]; do sleep 1; done'
```

The command returns once Android reports `sys.boot_completed`. Right after a create or a fork,
`adb devices` is empty until Android has booted.

**3. Install your app**

```bash theme={null}
instabox push phone ./app-debug.apk
instabox exec phone -- adb install app-debug.apk
```

`app-debug.apk` stands for your own app's APK. `push` puts it in the machine's home, and
`adb install` prints its result when the install ends.

**4. Drive and test the app**

```bash theme={null}
instabox ssh phone
adb devices                               # emulator-5554 (or 127.0.0.1:5555)
adb shell input tap 360 640
adb exec-out screencap -p > screen.png
```

`adb devices` lists the phone. `screencap` saves a screenshot of the phone to `screen.png` in the
machine.

**5. See the phone**

Open the machine in the dashboard and choose the **Computer** tab. The phone is the **Android**
window on the desktop, and it takes clicks and typing. An agent drives it the same way, with the
desktop API or with `adb shell input`. See [Computer use](https://instabox.sh/docs/use-cases/computer-use.md).

> [!NOTE]
>
> The free plan creates from agent-browser, android, omarchy, ci, so `android` works on every plan.

## Limits of the android template

* **No Google Play or Google services.** Install apps with `adb install`. Apps that need Google
  services for sign-in, maps or push do not fully work.
* **x86\_64 only.** Apps that ship only ARM native code do not run (no ARM translation). Apps with no
  native code, or with x86\_64 libraries, run.
* **Software rendering.** It is fine for app testing and UI automation, and slow for games and heavy 3D.

> [accordion] adb lists nothing
>
> If `adb devices` still lists nothing after boot, run `adb connect 127.0.0.1:5555` once. Do not
> connect while `emulator-5554` is listed. With the same phone listed twice, `adb shell` asks which
> one to use.

> [accordion] Pause, idle pause and fork
>
> Pause and resume, and idle pause and wake, keep the same running Android. Apps, their state, and
> the clock carry on. A fork copies Android's data (installed apps and their data) and boots its own
> Android from it about 20 seconds later. Apps that were running are not carried over.

> [accordion] Free Android's memory
>
> To stop Android, run `sudo systemctl stop instabox-android`. To keep it off across restarts, also
> run `sudo systemctl disable instabox-android`.

> [card] [Computer use](https://instabox.sh/docs/use-cases/computer-use.md)
>
> Screenshots, clicks and keys from your code.

> [card] [Parallel forks](https://instabox.sh/docs/use-cases/parallel-forks.md)
>
> Copy a set-up phone into several machines.