Quickstart

Use the CLI for interactive terminal workflows or the TypeScript SDK for API-key based applications, CI, and agents.

Install the CLI

curl -fsSL https://run.cloud/install | sh

This installs the CLI and starts sign-in. With Node already available:

npm install -g runcloud
# or
npx runcloud ios create

See Install the CLI for pinned versions, install paths, and how sign-in is skipped in CI, containers, and agent environments.

Authenticate

CLI commands can use a saved browser-authenticated session:

runcloud login

For CI and other non-interactive CLI use, provide both the API key and API URL:

export RUN_CLOUD_API_KEY="rc_live_..."
export RUN_CLOUD_API_URL="https://api.run.cloud"

The TypeScript SDK uses an API key created in the run.cloud dashboard:

export RUN_CLOUD_API_KEY="rc_live_..."

The SDK does not require RUN_CLOUD_API_URL; it defaults to the production API. The CLI accepts either the saved runcloud login credential or the API key and API URL together. It does not require both login and an API key. See the TypeScript SDK guide for the walkthrough, or use the CLI reference and SDK reference for the complete surface.

Create a Linux sandbox

SANDBOX_ID=$(runcloud sandbox create --json | jq -r '.id')
trap 'runcloud sandbox rm "$SANDBOX_ID"' EXIT

runcloud sandbox exec "$SANDBOX_ID" "echo hello from the microVM"

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

const cloud = new Client();
const sandbox = await cloud.sandboxes.create({ image: "runcloud/agent-base" });

try {
  const result = await cloud.sandboxes.exec(sandbox.id, "echo hello from the microVM");
  console.log(result.exitCode, result.stdout);
} finally {
  await cloud.sandboxes.destroy(sandbox.id);
}

The CLI example extracts the returned sandbox ID and releases the sandbox when the shell exits. See Linux sandboxes for sizing, snapshots, and the full API.

Stop reinstalling dependencies on every boot

If your sandbox installs the same system packages or project dependencies every time it starts, bake them into an OCI image and register that image once:

runcloud image create --ref ghcr.io/acme/video-renderer:latest
runcloud sandbox create --image ghcr.io/acme/video-renderer:latest

runcloud image create converts the image to a bootable microVM filesystem ahead of time and waits until it is ready. Later sandboxes reuse that prepared image instead of repeating setup work on every boot. Publish the OCI image to a registry first; local Dockerfile build contexts are not supported yet. See Custom images for deterministic digest pins, CI pre-baking, refreshes, and build status.

Create a mobile simulator

runcloud ios create --json
runcloud android create --json

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

const cloud = new Client();
const ios = await cloud.ios.create({
  displayName: "iOS smoke",
  inactivityTimeout: "60s",
});
try {
  const android = await cloud.android.create({
    displayName: "Android smoke",
    inactivityTimeout: "60s",
  });
  try {
    await cloud.ios.tap(ios.id, { x: 0.5, y: 0.5 });
    await cloud.android.tap(android.id, { x: 0.5, y: 0.5 });
    console.log([ios.url, android.url]);
  } finally {
    await cloud.android.delete(android.id);
  }
} finally {
  await cloud.ios.delete(ios.id);
}

Create returns a signed browser URL, device id, lease id, and session id. For CLI scripts, prefer JSON:

SESSION_ID=$(runcloud ios create --json | jq -r '.id')
runcloud ios get "$SESSION_ID" --json

See Run an iOS Simulator and Run an Android Emulator for platform-specific command references. See Control a Simulator for taps, gestures, text, keys, buttons, screenshots, MP4 screen recordings, and other interactions. For full runnable SDK source, see newly-app/run-cloud-examples/sdk-ios-android.

Run a bundled demo

The CLI includes its maintained demos, so you can launch the default eight-device mosaic from any directory without cloning a repo or installing project dependencies:

runcloud demo run --open

Run the live camera relay explicitly when you want to connect your webcam to one broadcaster simulator and two receivers:

runcloud demo run live-camera-relay --open

Both demos release their sessions automatically.

Upload and install an app

Download checksum-verified onboarding apps with the CLI:

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

runcloud sample download android
runcloud android create --install ./run-cloud-sample-android.apk

Or download the same public fixtures with curl:

curl -fLO https://run.cloud/downloads/run-cloud-sample-ios.app.tar.gz
curl -fLO https://run.cloud/downloads/run-cloud-sample-android.apk

The iOS download is a simulator-compatible .app bundle packaged as .tar.gz. The Android download is a signed APK. Their filenames, sizes, and SHA-256 checksums are published in the sample manifest. To install your own build instead:

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

--install accepts app artifacts for the target platform. iOS Simulator reliability depends on a simulator-compatible build; Android emulator sessions expect an APK or another Android-compatible artifact. You can also upload once and reuse the asset:

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

Clean up

runcloud ios list
runcloud android list
runcloud ios delete <session-id>
runcloud android delete <session-id>

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

const cloud = new Client();
const iosSessionId = process.env.IOS_SESSION_ID;
const androidSessionId = process.env.ANDROID_SESSION_ID;
if (!iosSessionId || !androidSessionId) {
  throw new Error("IOS_SESSION_ID and ANDROID_SESSION_ID are required");
}

await cloud.ios.delete(iosSessionId);
await cloud.android.delete(androidSessionId);

Sessions are metered while active. Explicit release charges the final started minute. 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

Install the CLI

Authenticate

Create a Linux sandbox

Stop reinstalling dependencies on every boot

Create a mobile simulator

Run a bundled demo

Upload and install an app

Clean up

​Install the CLI

​Authenticate

​Create a Linux sandbox

​Stop reinstalling dependencies on every boot

​Create a mobile simulator

​Run a bundled demo

​Upload and install an app

​Clean up

Install the CLI

Authenticate

Create a Linux sandbox

Stop reinstalling dependencies on every boot

Create a mobile simulator

Run a bundled demo

Upload and install an app

Clean up