Run an Android Emulator

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. For reusable app artifacts, see Assets.

Create a session

runcloud android create --json

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

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.

Configure the session

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:

runcloud sample download android
runcloud android create --install ./run-cloud-sample-android.apk --json

Install a local build while creating the session:

runcloud android create --install ./app-debug.apk --json

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

Or upload once and reuse the artifact:

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:

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

runcloud android open-url https://example.com --id "$SESSION_ID"
runcloud android open-url myapp://settings --id "$SESSION_ID"

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");

Inspect sessions

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

runcloud android delete "$SESSION_ID" --json

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

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.

Getting Started

Linux Sandboxes

CI

iOS

Android

Billing

Agents

Run an Android Emulator

Create a session

Configure the session

Install an app

Build from source

Open URLs and deep links

Inspect sessions

Release the session

​Create a session

​Configure the session

​Install an app

​Build from source

​Open URLs and deep links

​Inspect sessions

​Release the session

Create a session

Configure the session

Install an app

Build from source

Open URLs and deep links

Inspect sessions

Release the session