@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.
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
Usecloud.simulators when the platform is chosen at runtime.
platform is "ios" | "android" and defaults to "ios".
SandboxClient
Usecloud.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
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 throwRunCloudError:
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.