# Cloud Android Device: Create, Stream and Run Macros

> Create a cloud Android device in Macro Automation Studio, view it over WebRTC, install APKs and run macros server-side with your PC off, and fix stuck devices.

Source: https://automationmacro.com/docs/cloud-devices (Devices, updated 2026-09-04)

A cloud device is an Android device that Macro Automation Studio (MAS) runs for you on its own GPU hosts. It sits next to your local emulators in the app, streams its screen over WebRTC, and runs macros server-side, so your computer can be off. This page covers creating one, its states, apps, runs and limits.

## Before you start

- MAS is installed and you are signed in. See [Install MAS](/docs/install).
- Your plan includes at least one cloud device. Cloud devices are an add-on to a paid plan; see [Billing](/docs/billing).
- For runs: a Python macro in your library. The run dialog lists Python macros only.

## What a cloud Android device is

Each cloud device is a full Android device in a MAS data center, rendered on a server GPU. Start and stop take real time: about 48 seconds for a fresh boot, 17 for a resume and 9 for a stop. The screen reaches you as a WebRTC stream that carries video and your taps, and one viewer holds it at a time; the card shows an eye icon, **Being viewed live**, when it is open elsewhere. Macros run on MAS servers next to the device, so closing the app does not end a run. Installed apps and signed-in accounts survive a stop; only **Delete** erases them.

## Create a cloud device

1. Open **Cloud Devices** in the sidebar.
2. Type a **Device name**.
3. Pick the **Android** version. The list comes from the server; Android 15 is the default.
4. Pick a **Resolution**: **Light** (540 by 960), **Standard** (720 by 1280) or **Sharp** (1080 by 1920). Sharp streams about twice the pixels and needs more bandwidth.
5. Pick a **DPI**, or keep **Default**, the preset's own density. The allowed values are 160, 240, 320 and 480.
6. Optionally tick **Include Google Play Store** (see below).
7. Click **Create**.

The device appears as **Stopped**; creating does not start it. Version, resolution and DPI are fixed once created, so a different profile means a new device. The page header counts **Running** and **Allocated** devices against your plan, and an account can hold up to 20 cloud devices per account.

### Google Play on a cloud Android phone

Google apps are opt-in per device. Tick **Include Google Play Store** when you create a device, or click **Add Google Play** on an existing one: the device restarts once, in about 15 seconds, and keeps its data. **Add Google Play to all** covers every device without it.

The first time, MAS shows the **Install Google apps** disclaimer, which you accept once per account. In short: the device installs MindTheGapps, an independent open-source package maintained by LineageOS developers, containing Google Play Store, Google Play Services and Google Services Framework. MAS is not affiliated with, endorsed by, or licensed by Google; neither MAS nor the MindTheGapps project grants you any license to Google's applications, and your use of Google apps and of any Google account is governed by Google's own Terms of Service. The virtual device is not Play Protect certified, so apps that verify device integrity will not work: banking and payment apps, Google Wallet, HD or DRM streaming, and some games. You install and use Google apps at your own risk.

A device with Google Play shows a **Play** badge. If the install fails, the card offers **Retry**.

## Device states

| State | What it means |
|---|---|
| Stopped | Allocated, not running, data kept. Does not count as running. |
| Placing | MAS is finding a host with room, or provisioning a new one (about 15 minutes). |
| Starting | Android is booting: usually under 1:30 for a first boot, under 0:20 for a resume. |
| Ready | Running. You can view it, install apps and run macros. |
| Stopping | Shutting down, usually under 0:10. |
| Error | Something failed. The card shows the reason, and **Start** retries. |

Every transition is asynchronous; the card shows the elapsed time while a device is moving.

## Start, stop and delete

- **Start** boots the device. When every running slot in your plan is in use, it fails with a message like "2 of 2 running, stop one to start another".
- **Stop** frees the running slot and the host's GPU and RAM while keeping the disk. **Start** resumes it.
- **Delete** destroys the device and everything on it: installed apps, logged-in accounts, game progress. The dialog says so first.

A running device with no active run is stopped automatically after 60 minutes. Its data is kept; **Start** resumes it in seconds. A running macro keeps the device up.

## View the live screen

Click **View** on a ready device. **Negotiating stream** means the WebRTC connection is being set up; once live, your clicks, drags and keys go straight to the device, and the header offers **Full screen**, **Back**, **Home** and **Close**. Closing the viewer releases the stream for another window. In **Device Groups**, a cloud device card has **Watch live**, which docks the same viewer beside the card.

## Install apps

Click **Install APK** on a ready device. The chooser offers three paths:

- **Upload a file (.apk / .xapk)**: a `.apk`, `.xapk`, `.apkm` or `.apks` file of up to 1 GiB. MAS checks it, uploads it to the device's host and installs it there. Container formats are unpacked, 32-bit and x86 splits are dropped, expansion files are placed, and the rest installs as one bundle. A package with no arm64 build is refused before upload; cloud devices are 64-bit ARM only.
- **Search for apps to download**: type an app name, or paste a link or package id, and click **Install**. MAS downloads the app on this computer and installs it the same way.
- **Manage installed apps**: see what is on the device, **Update** an app when the catalog has a newer build, or uninstall one with the trash button (click twice to confirm). The header shows app slots used against the device's limit.

Progress shows on the card: **Checking app**, **Uploading app**, **Installing app**. Failures show the verbatim reason, including adb's INSTALL_FAILED codes.

## Run macros 24/7 on a cloud device

1. Start the device and wait for **Ready**.
2. Click **Run** on the card and pick a Python macro.
3. Follow the run line: launching, running with elapsed time, finished or failed. **Stop run** ends the run and leaves the device on.

Before the run starts, MAS syncs your code: it hashes the macro's project folder and uploads a snapshot only when the tree changed. A snapshot holds at most 500 files and 10 MiB zipped; dot-folders such as `.git` and `.venv`, plus `__pycache__`, `node_modules`, `venv` and `.pyc` files, are skipped. A project over a limit fails before the run with the reason, for example "project has more than 500 files". The snapshot is what the cloud runs, so the Code Editor's working tree executes without a commit or push. See [Git projects and code sync](/docs/git-and-code-sync).

Runs started from a cloud [device group](/docs/device-groups) use the device's macro and its arguments or settings profile, and show the script's output in the card. Every run lands in **Runs** with its status.

> [!NOTE]
> A finished macro runs on a cloud device at zero AI credits. Credits are spent only when MAS Agent authors on it.

## Cloud device groups and proxies

A device group holds one kind of device. Create a group with **Type** set to **Cloud**, click **Add cloud device** and pick an allocated device; a cloud device can only join a cloud group. Each device in the group has its own macro, arguments or settings profile, proxy and webhooks, and **Start All** launches a server-side run per device in turn. See [Device groups](/docs/device-groups).

A proxy attached to a cloud device is applied inside the device's network when the device next starts, so all of its traffic exits through the proxy and the card shows the exit IP. See [Proxies](/docs/proxies).

## REST API and MCP

With an [API key](/docs/api-keys) you can start and watch server-side runs: `POST /api/hosted/devices/{id}/run` with `macro_id` and optional `args`, `POST /api/hosted/runs/{id}/stop`, `GET /api/hosted/runs/{id}`, and `GET /api/macros/{id}/code-state` plus `POST /api/macros/{id}/code-snapshot` to sync code. Device lifecycle, streaming and app installs need the app's own sign-in. See the [REST API](/docs/rest-api). The [MAS MCP server](/docs/mcp) exposes cloud devices to MCP clients.

## What it costs

Cloud devices are an add-on to any paid plan, priced per device per month, with a monthly AI credit allowance included for MAS Agent. Add or remove devices mid-cycle; the change is prorated and the renewal date stays. See the [pricing page](/pricing) and [Billing](/docs/billing).

## Troubleshooting

### Device stuck in placing or starting

Placing means no host has room yet. MAS provisions a new host, which takes about 15 minutes, and the device moves on by itself. If nothing frees up within 45 minutes the device goes to **Error** with "no capacity became available", and **Start** retries. A first boot usually finishes under 1:30 and a resume under 0:20; if the elapsed time runs well past that, click **Stop**, wait for **Stopped**, then **Start** again. That also moves the device onto a current host, which fixes "this device's host does not support APK installs yet".

### Stream does not connect

- The device must be **Ready**. A stopped device answers "The device must be running before you can view it".
- Stuck at **Negotiating stream**: the stream ticket is short-lived, so close the viewer and click **View** again, or click **Reconnect** when offered.
- Open elsewhere: one viewer holds the stream. Close it in the other window or MAS instance.
- A network that blocks WebRTC never paints the video. Try another network, then ask in [Discord](https://discord.gg/macroautomationstudio).

### App install fails

- "this package has no arm64-v8a build": the app ships only 32-bit or x86 code. Get an arm64 version.
- "not a valid APK": the file is not an Android package or is corrupted.
- "the limit is 1024MB": the package is over 1 GiB.
- "INSTALL_FAILED_MISSING_SPLIT": the bundle is incomplete. Download the full XAPK and install that.
- "install timed out": the host is under load. Retry in a few minutes.