TypeScript SDK

@run-cloud/sdk is the API-key client for iOS simulator sessions, Android emulator sessions, microVM sandboxes, snapshots, account state, and reusable app assets. It requires Node.js 20 or newer. See the latest SDK reference for the complete class, method, option, and response-type index.

Install

npm install @run-cloud/sdk

Authenticate

Create an API key in the run.cloud dashboard, then expose it to the process that runs your application:

export RUN_CLOUD_API_KEY="rc_live_..."

The client reads RUN_CLOUD_API_KEY automatically. You can also pass the key directly when your application loads secrets another way:

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

const cloud = new Client({ apiKey: process.env.MY_RUN_CLOUD_KEY });

Set RUN_CLOUD_API_URL or pass apiUrl to use a non-default API host. Do not put API keys in source code, browser bundles, logs, or committed environment files.

Run the complete example

The runnable example checks account access, creates iOS and Android sessions, opens a URL on each platform, and releases both sessions even when the run is interrupted or fails:

git clone --depth 1 https://github.com/newly-app/run-cloud-examples.git
cd run-cloud-examples/sdk-ios-android
npm install
npm run demo -- --platform both --open

See newly-app/run-cloud-examples/sdk-ios-android for platform, codec, duration, and JSON-output options.

Create and release sessions

Use the platform client when the platform is known. Always release metered sessions in finally so a failed test does not leave them running:

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

const cloud = new Client();
const session = await cloud.ios.create({
  displayName: "iOS smoke",
  labels: { suite: "onboarding" },
  inactivityTimeout: "60s",
  hardTimeout: "10m",
});

try {
  await cloud.ios.openUrl(session.id, "https://run.cloud");
  await new Promise((resolve) => setTimeout(resolve, 3000));
  const screenshot = await cloud.ios.screenshot(session.id);
  await writeFile("run-cloud.png", screenshot);
  console.log(`Captured run-cloud.png (${screenshot.byteLength} bytes)`);
} finally {
  await cloud.ios.delete(session.id);
}

cloud.ios and cloud.android both provide:

Method	Purpose
`create(options)`	Create a metered simulator or emulator session.
`list({ all })`	List active sessions, or include released sessions with `all: true`.
`get(id)`	Read the latest session state.
`openUrl(id, url)`	Open an HTTP URL or app deep link.
`delete(id)`	Release the session and stop future metering.

The iOS client also provides:

screenshot(id), which returns PNG bytes as a Uint8Array.
uploadVideo(id, video, options), which accepts an MP4 or QuickTime Blob and imports it into Photos. The uploaded file remains in cloud.assets for reuse or deletion.
uploadMicrophoneAudio(id, audio, options), which accepts AAC, M4A, MP3, MP4-audio, or WAV and loops it through the foreground app’s microphone input. Pass bundleId when the intended app is not currently in front.

These methods are not currently available on cloud.android.

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

const video = new Blob([await readFile("./proof.mp4")], { type: "video/mp4" });
const imported = await cloud.ios.uploadVideo(session.id, video, {
  filename: "proof.mp4",
});
console.log(`Imported ${imported.filename} (${imported.byteSize} bytes)`);

const audio = new Blob([await readFile("./spoken.wav")], { type: "audio/wav" });
const injected = await cloud.ios.uploadMicrophoneAudio(session.id, audio, {
  filename: "spoken.wav",
  bundleId: "com.example.AudioRecorder",
});
console.log(`Injecting ${injected.filename} into ${injected.bundleId}`);

Use the generic simulator client

Use cloud.simulators when the platform is selected at runtime. Pass the session platform back to methods that operate on an existing session:

const session = await cloud.simulators.create({
  platform: "android",
  displayName: "Android smoke",
  codec: "auto",
});

try {
  await cloud.simulators.openUrl(session.id, "myapp://settings", {
    platform: session.platform,
  });
} finally {
  await cloud.simulators.delete(session.id, {
    platform: session.platform,
  });
}

cloud.simulators.list() returns every platform unless platform is supplied. Other generic simulator lifecycle methods default to iOS when platform is omitted.

Check account state

Use account() before starting a larger test matrix when you want to surface access or organization information early:

const account = await cloud.account();
console.log(account.orgs);

Upload and reuse assets

Upload an artifact once, then reference its id from one or more sessions:

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

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

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

cloud.assets provides upload, list, and delete. Artifact contents must match the target platform: iOS needs a simulator-compatible build, while Android needs an Android-compatible artifact such as an APK.

Handle API errors

Non-successful responses throw RunCloudError with the HTTP status and the API detail:

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

try {
  await new Client().ios.create();
} catch (error) {
  if (error instanceof RunCloudError) {
    console.error(error.status, error.detail);
  }
  throw error;
}

Getting Started

Linux Sandboxes

CI

iOS

Android

Billing

Agents

Install

Authenticate

Run the complete example

Create and release sessions

Use the generic simulator client

Check account state

Upload and reuse assets

Handle API errors

​Install

​Authenticate

​Run the complete example

​Create and release sessions

​Use the generic simulator client

​Check account state

​Upload and reuse assets

​Handle API errors

Install

Authenticate

Run the complete example

Create and release sessions

Use the generic simulator client

Check account state

Upload and reuse assets

Handle API errors