Skip to main content
This is the reference for the latest @run-cloud/sdk release. The SDK controls iOS simulator sessions, Android emulator sessions, microVM sandboxes, snapshots, reusable app assets, remote Xcode builds, usage, and run.cloud account state from Node.js 20 or newer.
For an end-to-end introduction, see the TypeScript SDK guide.

Client

Constructor

The client exposes:

XcodeBuildsClient

XcodeBuildOptions accepts workspace or project, scheme, sdk, configuration, xcodegen, reactNative, gitInit, buildSettings, manual signing, cloudSigning, appStore, upload, timeoutSeconds, source, and idempotencyKey. SDK values are iphonesimulator, iphoneos, watchsimulator, and watchos. Source options accept path matchers in ignore and include, plus additionalFiles: [{ localPath, remotePath }]. Each matcher can be a string, RegExp, or predicate. See Build with Xcode for a complete example and packaging rules. XcodeBuild.status progresses through uploading, queued, running, and one of succeeded, failed, or cancelled. Artifact metadata, logs, result, failure and timing fields are available without access to the remote builder. Successful outputs include an immutable artifact.assetId; React Native builds also expose native-shell reuse metadata. APP_CONFIG_ build-setting values and signing credentials are never returned.

Compatibility adapters

Compatibility adapters are subpath exports of @run-cloud/sdk; no second npm package or scope is required. Adapters preserve the provider’s familiar entry point for core sandbox creation, lookup/listing, synchronous command execution, lifecycle, and destruction. Provider-specific functionality without a public run.cloud equivalent throws UnsupportedCompatibilityFeatureError; unsupported methods never return a fabricated success.

SimulatorClient

cloud.ios and cloud.android expose the same methods: rotateDigitalCrown returns an unsupported-action error on current mobile sessions. setRenderDebug returns one on Android. Button availability also follows the target platform. SimulatorOrientation includes all four Android orientations. Current iPhone Simulator sessions return a typed, non-retryable unsupported_action for portrait_upside_down; portrait and both landscape values are supported. See Control a Simulator for the capability matrix and complete key and button lists. Both cloud.ios and cloud.android expose the camera and microphone methods above. They return the retained uploaded asset; delete it through cloud.assets when it is no longer needed. cloud.ios additionally exposes a Photos import: openUrl preserves the complete input string, including percent encoding, as one inert argument. Android’s platform bridge quotes shell metacharacters so they are not evaluated as commands. See Open URLs and Deep Links for both platform clients, the generic simulator client, the REST request, and error handling.

CreateSessionOptions

Always release metered sessions in finally:

SimulatorInteractionOptions

SimulatorSwipeOptions adds durationMs. SimulatorPressKeyOptions adds modifiers and durationMs; SimulatorPressButtonOptions adds durationMs. Screenshot options accept requestId, timeoutMs, and signal. SimulatorAccessibilityOptions accepts timeoutMs (20,000 by default, from 100 to 60,000) and signal. See Read the Accessibility Tree for roles, states, platform fields, secure-value redaction, and complete examples.

Simulator recordings

SimulatorRecording includes the capture status, content type, byte size, checksum, ETag, duration, attempt count, failure, timestamps, retention deadline, and authenticated API-relative downloadUrl. getRecording returns SimulatorRecordingDetails, which adds retained lifecycle events. startRecording accepts SimulatorRecordingStartOptions with an optional idempotencyKey and signal. Reuse the same key when retrying a start request. The other recording methods accept SimulatorRecordingRequestOptions with an optional signal. Statuses are starting, recording, finalizing, ready, failed, deleting, and deleted. A failure includes stage, code, message, action, retryable, and nextAttemptAt. Recordings are retained for seven days and remain readable after their simulator session is released. See Record a Simulator for a complete CLI, SDK, and REST workflow. Points are normalized display coordinates from 0 to 1 inclusive, with the origin at the top-left. SimulatorInteraction is a discriminated union of tap, swipe, gesture, typeText, pressKey, pressButton, rotate, reload, scroll, toggleSoftwareKeyboard, simulateMemoryWarning, rotateDigitalCrown, and setRenderDebug.

SimulatorsClient

Use cloud.simulators when the platform is chosen at runtime. platform is "ios" | "android" and defaults to "ios".

SandboxClient

Use cloud.sandboxes to create and operate microVM sandboxes through the same run.cloud API key as the CLI.

CreateSandboxOptions

ExecOptions

A string command runs through /bin/sh -c; pass a string array to execute the arguments directly:

SnapshotsClient

Usage

UsageReport.items contains cumulative usage entries with org_id, meter, and seconds.

AssetsClient

Build-output Assets are immutable. origin, parentAssetId, and metadata retain their build and native-shell lineage.

CapabilitiesClient

Supported scopes are asset.read, mobile.launch, xcode.build.create, and xcode.build.read. Resource bindings accept assetIds, buildIds, and idempotencyKeys.

MobileClient

options.idempotencyKey is required. Reusing it with the same request returns the original operation; reusing it with different input fails with 409.

Response types

SimulatorSession

The response may also include allocation, queue, device, lease, and metering metadata.

SimulatorOpenUrlResult

The result acknowledges the platform operation. Inspect the viewer, capture a screenshot, or read app state when the test depends on visible navigation.

SimulatorInteractionResult

Successful interactions contain: The acknowledgement means the control operation was accepted and dispatched. Check app state or take a screenshot when the test depends on a visible effect. SimulatorInteractionFailure describes the wire error envelope. It has ok: false, optional correlation, action, status, timing, and duration fields, plus required error.code, error.message, and error.retryable, and optional error.details. Platform-client methods throw RunCloudError for this response and copy those fields onto the error instance.

Asset

Sandbox

The SDK preserves the API’s raw snake_case fields and also adds the camelCase aliases shown above.

ExecResult

Errors

Non-successful API responses throw RunCloudError:
Caller cancellation rejects with the AbortSignal reason rather than RunCloudError. It stops the request wait but does not release the session or undo an action that was already accepted. Simulator interaction errors use stable interaction_* codes, including interaction_cancelled, interaction_timeout, interaction_transport_error, and interaction_invalid_response. Screenshot capture uses the corresponding screenshot_cancelled, screenshot_timeout, screenshot_transport_error, and screenshot_invalid_response codes. Generic, non-simulator API errors may leave code and retryable undefined. Accessibility reads use accessibility_cancelled, accessibility_timeout, accessibility_transport_error, and accessibility_invalid_response, plus session and capacity codes shared by simulator operations. URL-opening errors use invalid_url, active_session_not_found, open_url_scope_required, simulator_session_ended, ios_url_handler_not_found, android_url_handler_not_found, simulator_unavailable, open_url_timeout, ios_open_url_failed, android_open_url_failed, and the gateway open_url_* codes documented in Open URLs and Deep Links. isSimulatorCapacityError(error) narrows error to the exported SimulatorCapacityError type: HTTP 503, code simulator_capacity_unavailable, and retryable: true. Use the guard before a bounded create retry; authentication, validation, and other 503 responses do not match it.