Run an iOS Simulator

Create a remote iOS simulator session, open the signed stream URL in a browser, install simulator-compatible app builds, 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 ios create --json

import { Client } from "@run-cloud/sdk";

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

console.log(session.id, session.url);

The response includes:

Field	Use
`id`	run.cloud session id. Use it with lifecycle, control, screenshot, and log operations.
`url`	Signed browser URL for the live simulator stream. Do not publish it in logs.
`status`	Session status: `active`, `released`, or `failed`.
`createdAt`	Session creation timestamp.
`releasedAt`	Release timestamp once the session is closed.
`expiresAt`	Session expiry timestamp when available.
`inactivityTimeoutSeconds`	Auto-close timeout in seconds, or `null` when disabled.
`inactivityCountdownSeconds`	Visible countdown duration before auto-close, or `null` when disabled.
`queued`	`true` when creation had to wait for simulator capacity before a session was assigned.
`queueWaitMs`	Milliseconds spent waiting for capacity during this create request.
`queueAttempts`	Number of capacity checks made before assignment or failure.

For full runnable SDK source, see newly-app/run-cloud-examples/sdk-ios-android.

Capacity queue

If every compatible simulator is already in use, runcloud ios create waits for the next available session instead of failing immediately. If capacity opens within the wait window, the command returns a normal active session and includes queued: true, queueWaitMs, and queueAttempts in the JSON response. If capacity does not open in time, the command fails with no active session. Retrying is safe because a simulator lease is only created after capacity is assigned.

Configure the session

runcloud ios create \
  --model iphone \
  --display-name "CI smoke" \
  --label env=ci \
  --inactivity-timeout 60s \
  --hard-timeout 10m \
  --json

Supported flags:

Flag	Purpose
`--model MODEL`	Preferred simulator family: `iphone` or `ipad`.
`--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 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.
`--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. The signed simulator URL carries that policy to the iOS simulator; an embedded viewer shows the final 10-second countdown, ends the iOS simulator lease, and posts a session-ended message to its parent page. Billing is organization-level. Active sessions accrue metered usage against the selected organization. If the organization reaches its run.cloud credit ceiling, active simulator sessions are closed automatically.

Install an app

Try the onboarding app without building an iOS project:

runcloud sample download ios
runcloud ios create --install ./run-cloud-sample-ios.app.tar.gz --json

The downloaded archive contains an Apple Silicon iOS Simulator .app; it is not an App Store or physical-device IPA. Install a local simulator build while creating the session:

runcloud ios create --install ./MyApp.tar.gz --json

import { readFile } from "node:fs/promises";
import { Client } from "@run-cloud/sdk";

const cloud = new Client();
const archive = await readFile("./MyApp.tar.gz");
const asset = await cloud.assets.upload(new Blob([new Uint8Array(archive)]), {
  name: "my-app",
  filename: "MyApp.tar.gz",
});

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

console.log(session.url);

Or upload once and reuse the artifact:

runcloud asset push ./MyApp.tar.gz -n my-app --json
runcloud ios create --install-asset my-app --json

--install accepts .tar.gz, .zip, .app archives, and .ipa files. iOS Simulator reliability still depends on the app being built for the simulator runtime. Device-signed App Store IPAs are not a substitute for simulator builds.

Open URLs and deep links

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

An HTTPS target opens the system handler, normally Safari. A custom scheme opens its registered simulator app. The success result identifies the session, device, and lease and echoes the complete input URI without normalizing its encoding. The first custom-scheme handoff can still show an iOS Open in “App”? confirmation after that acknowledgement; confirm Open in the viewer before checking app state. For automated visual proof, allow about five seconds for the prompt before one confirmation tap and another five seconds for the app to render before capture. See Open URLs and Deep Links for authentication, the REST endpoint, a complete encoded example, automated confirmation guidance, 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 ios tap "$SESSION_ID" 0.50 0.23 --json
runcloud ios swipe "$SESSION_ID" 0.50 0.65 0.50 0.54 \
  --duration 300 --json
runcloud ios type-text "$SESSION_ID" "Run Cloud" --json
runcloud ios press-key "$SESSION_ID" enter --json

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

Each operation returns a correlated acknowledgement. Use Control a Simulator for gestures, semantic keys, hardware buttons, orientation, timeouts, cancellation, errors, and the full iOS capability list.

Inspect accessibility

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

runcloud ios 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 iOS simulator display as PNG bytes:

runcloud ios 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.ios.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/ios/$SESSION_ID/screenshot" \
  --output screenshot.png

Screenshots require an active, user-owned iOS session. Responses are image/png and are never cached. The maintained iOS 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/ios-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 macOS with Xcode; pass --app <path> to use a prebuilt simulator artifact.

Record screen video

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

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

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

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

Read simulator logs

Read the most recent unified-log entries produced during the current lease, or follow new entries until you stop the command:

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

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

for await (const entry of cloud.ios.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/ios/$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/ios/$SESSION_ID/logs?follow=1"

Snapshots are scoped 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 as they arrive; use --json to emit one JSON object per entry. Snapshot JSON includes since, capturedAt, entries, and truncated. Snapshot and stream responses are never cached.

Upload a video

Import an MP4 or QuickTime video into Photos on an active simulator:

import { readFile } 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 video = new Blob([await readFile("./proof.mp4")], { type: "video/mp4" });
const imported = await cloud.ios.uploadVideo(sessionId, video, {
  filename: "proof.mp4",
});

console.log(`Imported ${imported.filename} (${imported.byteSize} bytes)`);

The SDK stores the uploaded video as a user-owned run.cloud asset before importing it. It remains available through cloud.assets until you delete it. Video imports accept video/mp4 and video/quicktime, with a 500 MB limit.

Inject camera video

Present a prerecorded MP4 or QuickTime file to an installed app as live camera frames:

runcloud ios camera inject "$SESSION_ID" ./quadrants.mp4 \
  --bundle-id com.example.CameraRecorder \
  --json

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

console.log(camera.platform, camera.filename, camera.asset.id);

The video loops until the camera source changes or the session ends. This is separate from uploadVideo, which imports a video into Photos. Camera input is limited to 500 MB, and the returned user-owned asset remains available until you delete it.

Inject microphone audio

Loop a prerecorded audio asset through the foreground app’s AVAudioEngine microphone input:

runcloud ios microphone inject "$SESSION_ID" ./spoken.wav \
  --bundle-id com.example.AudioRecorder \
  --json

const audio = new Blob([await readFile("./spoken.wav")], { type: "audio/wav" });
const injected = await cloud.ios.uploadMicrophoneAudio(sessionId, audio, {
  filename: "spoken.wav",
  // Optional when the intended app is already in front.
  bundleId: "com.example.AudioRecorder",
});

console.log(`Injecting ${injected.filename} into ${injected.bundleId}`);

The operation grants microphone permission and relaunches the target app with the injector attached. AAC, M4A, MP3, MP4-audio, and WAV files are supported, up to 100 MB. The source is stored as a user-owned run.cloud asset.

Inspect sessions

runcloud ios list
runcloud ios list --all
runcloud ios get "$SESSION_ID" --json

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

Release the session

runcloud ios 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.ios.delete(sessionId);

Explicit release charges the final started minute and closes the iOS simulator 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 iOS Simulator

Create a session

Capacity queue

Configure the session

Install an app

Open URLs and deep links

Control the app

Inspect accessibility

Capture a screenshot

Record screen video

Read simulator logs

Upload a video

Inject camera video

Inject microphone audio

Inspect sessions

Release the session

​Create a session

​Capacity queue

​Configure the session

​Install an app

​Open URLs and deep links

​Control the app

​Inspect accessibility

​Capture a screenshot

​Record screen video

​Read simulator logs

​Upload a video

​Inject camera video

​Inject microphone audio

​Inspect sessions

​Release the session

Create a session

Capacity queue

Configure the session

Install an app

Open URLs and deep links

Control the app

Inspect accessibility

Capture a screenshot

Record screen video

Read simulator logs

Upload a video

Inject camera video

Inject microphone audio

Inspect sessions

Release the session