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

# Run an Android Emulator

> Create, inspect, install into, and release a remote Android emulator session.

Create a remote Android emulator session, open the signed stream URL in a
browser, install Android-compatible app artifacts, and release the session when
finished.

For CLI setup, see [CLI Quickstart](/cli/quickstart). For reusable app
artifacts, see [Assets](/cli/assets).

## Create a session

<CodeGroup>
  ```bash Bash theme={null}
  runcloud android create --json
  ```

  ```typescript TypeScript theme={null}
  import { Client } from "@run-cloud/sdk";

  const cloud = new Client();
  const session = await cloud.android.create({
    displayName: "Android smoke",
    inactivityTimeout: "60s",
  });

  console.log(session.id, session.url);
  ```
</CodeGroup>

The response includes the same fields as iOS sessions, with
`platform: "android"`. Use `id` with `get`, `delete`, and `open-url`; use `url`
for the signed interactive stream.

For full runnable SDK source, see
[newly-app/run-cloud-examples/sdk-ios-android](https://github.com/newly-app/run-cloud-examples/tree/main/sdk-ios-android).

## Configure the session

```bash theme={null}
runcloud android create \
  --model pixel \
  --display-name "Android smoke" \
  --label env=ci \
  --inactivity-timeout 60s \
  --hard-timeout 10m \
  --json
```

Supported flags:

| Flag                            | Purpose                                                             |
| ------------------------------- | ------------------------------------------------------------------- |
| `--model MODEL`                 | Preferred emulator family, for example `pixel`.                     |
| `--region REGION`               | Preferred region when available.                                    |
| `--display-name NAME`           | Human-readable label.                                               |
| `--label KEY=VALUE`             | Repeatable metadata label.                                          |
| `--install FILE`                | Upload and install a local Android app artifact.                    |
| `--install-asset NAME_OR_ID`    | Install an already uploaded asset.                                  |
| `--inactivity-timeout DURATION` | Auto-close after user inactivity. Use `60s`, `3m`, `1h`, or `none`. |
| `--hard-timeout DURATION`       | Maximum requested session lifetime.                                 |
| `--codec auto\|mjpeg\|webrtc`   | Select the viewer stream codec when enabled for the account.        |
| `--rm`                          | Mark the session as auto-delete-on-exit intent.                     |
| `--json`                        | Machine-readable output.                                            |

## Install an app

Try the onboarding app without building an Android project:

```bash theme={null}
runcloud sample download android
runcloud android create --install ./run-cloud-sample-android.apk --json
```

Install a local build while creating the session:

<CodeGroup>
  ```bash Bash theme={null}
  runcloud android create --install ./app-debug.apk --json
  ```

  ```typescript TypeScript theme={null}
  import { readFile } from "node:fs/promises";
  import { Client } from "@run-cloud/sdk";

  const cloud = new Client();
  const apk = await readFile("./app-debug.apk");
  const asset = await cloud.assets.upload(new Blob([new Uint8Array(apk)]), {
    name: "android-smoke",
    filename: "app-debug.apk",
  });

  const session = await cloud.android.create({
    installAssets: [asset.id],
  });

  console.log(session.url);
  ```
</CodeGroup>

Or upload once and reuse the artifact:

```bash theme={null}
runcloud asset push ./app-debug.apk -n android-smoke --json
runcloud android create --install-asset android-smoke --json
```

## Build from source

When you have a Newly project linked locally, the Newly CLI can build an Android
simulator APK and load it into a remote Android emulator:

```bash theme={null}
newly build android \
  --simulator \
  --remote-source \
  --wait \
  --load-to-simulator
```

For local development-client testing, Newly Desktop uses the same flow with an
authenticated Metro tunnel so the remote emulator can request the Android
bundle from your machine.

## Open URLs and deep links

<CodeGroup>
  ```bash Bash theme={null}
  runcloud android open-url https://example.com --id "$SESSION_ID"
  runcloud android open-url myapp://settings --id "$SESSION_ID"
  ```

  ```typescript TypeScript theme={null}
  import { Client } from "@run-cloud/sdk";

  const cloud = new Client();
  const sessionId = process.env.SESSION_ID;
  if (!sessionId) throw new Error("SESSION_ID is required");

  await cloud.android.openUrl(sessionId, "https://example.com");
  await cloud.android.openUrl(sessionId, "myapp://settings");
  ```
</CodeGroup>

## Inspect sessions

```bash theme={null}
runcloud android list
runcloud android list --all
runcloud android get "$SESSION_ID" --json
```

`list` shows active sessions by default. Pass `--all` to include released
sessions.

## Release the session

<CodeGroup>
  ```bash Bash theme={null}
  runcloud android delete "$SESSION_ID" --json
  ```

  ```typescript TypeScript theme={null}
  import { Client } from "@run-cloud/sdk";

  const cloud = new Client();
  const sessionId = process.env.SESSION_ID;
  if (!sessionId) throw new Error("SESSION_ID is required");

  await cloud.android.delete(sessionId);
  ```
</CodeGroup>

Explicit release charges the final started minute and closes the Android
emulator session. If the organization reaches its run.cloud credit ceiling, active sessions are
closed automatically.