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. To show the signed session inside a product, see Embed a Simulator. For taps, gestures, text, keys, buttons, and other device controls, see Control a Simulator.

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 lifecycle, control, screenshot, and log operations; 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.

If --inactivity-timeout is omitted, run.cloud uses a 60-second inactivity timeout. Set it to none to disable inactivity auto-close. Android sessions share one pool with Expo Go 54 preinstalled. No Expo SDK profile is required. To preview projects using another Expo SDK version, install your own development APK; its native runtime is independent of the preinstalled Expo Go app. The APK must support the emulator’s Android version and CPU architecture. Use @run-cloud/sdk 0.35.0 or newer for profile-free Android creation.

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

Open URLs and deep links

runcloud android open-url 'https://example.com/search?q=run%20cloud' \
  --id "$SESSION_ID" --json
runcloud android open-url \
  'runcloudproof://open/items%2F42?message=hello%20world#proof' \
  --id "$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.openUrl(sessionId, "https://example.com/search?q=run%20cloud");
const opened = await cloud.android.openUrl(
  sessionId,
  "runcloudproof://open/items%2F42?message=hello%20world#proof",
);
console.log(opened.platform, opened.url);

An HTTPS target resolves the system VIEW handler, normally the browser. A custom scheme resolves the exported activity that registered it. The success result identifies the session, device, and lease and echoes the complete input URI without normalizing its encoding. See Open URLs and Deep Links for authentication, the REST endpoint, a complete encoded example, and platform-specific errors.

Control the app

The CLI and SDK use normalized display coordinates from 0 to 1, with the origin at the top-left:

runcloud android tap "$SESSION_ID" 0.50 0.23 --json
runcloud android swipe "$SESSION_ID" 0.50 0.65 0.50 0.54 \
  --duration 300 --json
runcloud android type-text "$SESSION_ID" "Run Cloud" --json
runcloud android press-key "$SESSION_ID" enter --json
runcloud android press-button "$SESSION_ID" back --json

await cloud.android.tap(sessionId, { x: 0.5, y: 0.23 });
await cloud.android.swipe(
  sessionId,
  { x: 0.5, y: 0.65 },
  { x: 0.5, y: 0.54 },
  { durationMs: 300 },
);
await cloud.android.typeText(sessionId, "Run Cloud");
await cloud.android.pressKey(sessionId, "enter");
await cloud.android.pressButton(sessionId, "back");

Each operation returns a correlated acknowledgement. Digital Crown and render-debug actions are not supported on Android. Use Control a Simulator for gestures, semantic keys, buttons, orientation, timeouts, cancellation, errors, and the complete capability matrix.

Inspect accessibility

Read the current nested hierarchy without exposing the signed viewer URL:

runcloud android accessibility-tree "$SESSION_ID" --json

See Read the Accessibility Tree for the SDK, React embed, response schema, secure-value redaction, and test examples.

Capture a screenshot

Capture the current Android emulator display as PNG bytes:

runcloud android screenshot "$SESSION_ID" \
  --output ./screenshot.png \
  --json

import { writeFile } from "node:fs/promises";
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");

const screenshot = await cloud.android.screenshot(sessionId);
await writeFile("screenshot.png", screenshot);

curl --fail-with-body -sS \
  -H "Authorization: Bearer $RUN_CLOUD_API_KEY" \
  "https://api.run.cloud/run-cloud/android/$SESSION_ID/screenshot" \
  --output screenshot.png

Screenshots require an active, user-owned Android session. Responses are image/png and are never cached. The maintained Android app screenshot example builds a native fixture, installs it, validates the PNG, and releases the session:

git clone https://github.com/newly-app/run-cloud-examples.git
cd run-cloud-examples/android-app-screenshot
npm install
export RUN_CLOUD_API_KEY="rc_live_..."
npm run demo -- --json

It writes screenshots/run-cloud-proof.png. Building from source requires JDK 17 or newer and Android SDK 35 or newer; pass --app <path> to use a prebuilt APK.

Record screen video

Start an MP4 capture, stop it, and download it through the authenticated API:

RECORDING_ID=$(runcloud android recording start "$SESSION_ID" \
  --idempotency-key "android-smoke-1" \
  --json | jq -r '.id')

runcloud android recording stop "$SESSION_ID" "$RECORDING_ID" --json
runcloud android recording download "$SESSION_ID" "$RECORDING_ID" \
  --output ./android-recording.mp4 \
  --json

The TypeScript equivalents are cloud.android.startRecording, getRecording, listRecordings, stopRecording, and downloadRecording. See Record a Simulator for lifecycle, idempotency, retention, release, and failure behavior.

Read emulator logs

Read retained logcat entries from the current lease, including the app, system, and crash buffers, or follow new entries:

runcloud android logs "$SESSION_ID" --tail 200
runcloud android logs "$SESSION_ID" --follow

const snapshot = await cloud.android.logs(sessionId, { tail: 200 });
for (const entry of snapshot.entries) console.log(entry.message);

for await (const entry of cloud.android.followLogs(sessionId)) {
  console.log(entry.timestamp, entry.message);
}

curl --fail-with-body -sS \
  -H "Authorization: Bearer $RUN_CLOUD_API_KEY" \
  "https://api.run.cloud/run-cloud/android/$SESSION_ID/logs?tail=200"

curl --fail-with-body -sS -N \
  -H "Authorization: Bearer $RUN_CLOUD_API_KEY" \
  -H "Accept: text/event-stream" \
  "https://api.run.cloud/run-cloud/android/$SESSION_ID/logs?follow=1"

Snapshots are restricted to the active, user-owned lease, return 200 lines by default, and accept --tail values from 1 to 1,000. --follow streams only new entries. Add --json for structured snapshot output or newline-delimited JSON while following. Snapshot JSON includes since, capturedAt, entries, and truncated. Snapshot and stream responses are never cached.

Inject camera and microphone input

Start the installed app’s camera or microphone receiver, then inject a deterministic prerecorded source:

runcloud android camera inject "$SESSION_ID" ./quadrants.mp4 \
  --bundle-id com.example.CameraRecorder \
  --json
runcloud android microphone inject "$SESSION_ID" ./tone.wav \
  --bundle-id com.example.AudioRecorder \
  --json

import { readFile } from "node:fs/promises";

const cameraVideo = new Blob([await readFile("./quadrants.mp4")], {
  type: "video/mp4",
});
const camera = await cloud.android.uploadCameraVideo(sessionId, cameraVideo, {
  filename: "quadrants.mp4",
  bundleId: "com.example.CameraRecorder",
});

const tone = new Blob([await readFile("./tone.wav")], { type: "audio/wav" });
const microphone = await cloud.android.uploadMicrophoneAudio(sessionId, tone, {
  filename: "tone.wav",
  bundleId: "com.example.AudioRecorder",
});

console.log(camera.asset.id, microphone.asset.id);

Camera input accepts MP4 and QuickTime files up to 500 MB and loops until the source changes or the session ends. Microphone input accepts AAC, M4A, MP3, MP4-audio, and WAV up to 100 MB. Each result contains the user-owned source asset; delete it through runcloud asset delete or cloud.assets.delete() when the proof is complete.

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

Integrations

Platform

iOS

Android

Billing

Agents

Run an Android Emulator

Create a session

Configure the session

Install an app

Open URLs and deep links

Control the app

Inspect accessibility

Capture a screenshot

Record screen video

Read emulator logs

Inject camera and microphone input

Inspect sessions

Release the session

​Create a session

​Configure the session

​Install an app

​Open URLs and deep links

​Control the app

​Inspect accessibility

​Capture a screenshot

​Record screen video

​Read emulator logs

​Inject camera and microphone input

​Inspect sessions

​Release the session

Create a session

Configure the session

Install an app

Open URLs and deep links

Control the app

Inspect accessibility

Capture a screenshot

Record screen video

Read emulator logs

Inject camera and microphone input

Inspect sessions

Release the session