Open URLs and Deep Links

Use the same operation to open an ordinary HTTPS URL or hand a custom-scheme deep link to an installed app. It is available on iOS Simulator and Android Emulator through the CLI, TypeScript SDK, and REST API.

Authenticate

For an interactive terminal, sign in once and confirm that the account can use mobile sessions:

runcloud login
runcloud account --json

For CI, the TypeScript SDK, or direct REST calls, create an API key in the dashboard and expose it to the process:

export RUN_CLOUD_API_KEY="rc_live_..."

Do not put the key in source code, a browser bundle, command output, or a committed environment file. CLI commands can use either the saved login or the environment key. The SDK and REST examples below use the environment key. You also need an active session that belongs to the authenticated account. A custom-scheme target needs an installed app that registers that scheme. The maintained iOS proof app and Android proof app register runcloudproof and display the complete URI they receive.

Use the CLI

Pass the complete target as one quoted argument. These examples preserve an encoded path separator, a space, a nested return URL, its query string, and a fragment:

HTTPS_URL='https://example.com/search?q=run%20cloud&return=%2Fdocs%3Ftab%3Dmobile'
DEEP_LINK='runcloudproof://open/items%2F42?message=hello%20world&return=https%3A%2F%2Fexample.com%2Fdone%3Fx%3D1%26y%3Dtwo#proof'

runcloud ios open-url "$HTTPS_URL" --id "$IOS_SESSION_ID" --json
runcloud ios open-url "$DEEP_LINK" --id "$IOS_SESSION_ID" --json

HTTPS_URL='https://example.com/search?q=run%20cloud&return=%2Fdocs%3Ftab%3Dmobile'
DEEP_LINK='runcloudproof://open/items%2F42?message=hello%20world&return=https%3A%2F%2Fexample.com%2Fdone%3Fx%3D1%26y%3Dtwo#proof'

runcloud android open-url "$HTTPS_URL" --id "$ANDROID_SESSION_ID" --json
runcloud android open-url "$DEEP_LINK" --id "$ANDROID_SESSION_ID" --json

Successful JSON identifies the authenticated session, device, and lease that accepted the operation. url is the exact input string, without decoding or normalization:

{
  "ok": true,
  "platform": "ios",
  "sessionId": "sim_example",
  "device": "device_example",
  "leaseId": "lease_example",
  "url": "runcloudproof://open/items%2F42?message=hello%20world&return=https%3A%2F%2Fexample.com%2Fdone%3Fx%3D1%26y%3Dtwo#proof"
}

The acknowledgement confirms that the operation ran against that live lease. When app-specific navigation matters, inspect the signed viewer or capture a screenshot to confirm the visible result.

Use the TypeScript SDK

Install @run-cloud/sdk on Node.js 20 or newer:

npm install @run-cloud/sdk

Platform clients return a typed SimulatorOpenUrlResult:

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

const cloud = new Client();
const target =
  "runcloudproof://open/items%2F42?message=hello%20world&return=" +
  "https%3A%2F%2Fexample.com%2Fdone%3Fx%3D1%26y%3Dtwo#proof";

const iosResult: SimulatorOpenUrlResult = await cloud.ios.openUrl(
  process.env.IOS_SESSION_ID!,
  target,
);
const androidResult: SimulatorOpenUrlResult = await cloud.android.openUrl(
  process.env.ANDROID_SESSION_ID!,
  target,
);

if (iosResult.url !== target || androidResult.url !== target) {
  throw new Error("run.cloud did not preserve the deep link");
}

When the platform is selected at runtime, use the generic simulator client:

const result = await cloud.simulators.openUrl(session.id, target, {
  platform: session.platform,
});

Release every metered session in finally; see the TypeScript SDK guide for a complete create-and-cleanup example.

Call the REST API

The CLI and SDK use the public authenticated endpoint rather than a separate URL-opening contract:

POST /run-cloud/{ios|android}/{sessionId}/open-url

Build the JSON body with jq so quotes and URI delimiters remain data:

TARGET_URL='runcloudproof://open/items%2F42?message=hello%20world&return=https%3A%2F%2Fexample.com%2Fdone%3Fx%3D1%26y%3Dtwo#proof'

jq -n --arg url "$TARGET_URL" '{url: $url}' | \
  curl --fail-with-body --silent --show-error \
    --request POST \
    --header "Authorization: Bearer $RUN_CLOUD_API_KEY" \
    --header 'Content-Type: application/json' \
    --data-binary @- \
    "https://api.run.cloud/run-cloud/ios/$IOS_SESSION_ID/open-url"

Replace ios and IOS_SESSION_ID with android and the Android session id for an emulator. The response has the same six fields as SDK and CLI JSON output.

Platform behavior

Target	iOS Simulator	Android Emulator
`https://...`	Opens the system handler, normally Safari. A configured universal link can open its app instead.	Resolves an Android `VIEW` target, normally the browser. A configured App Link can open its app instead.
Custom scheme	Opens the installed app that registered the scheme.	Resolves the exported activity whose intent filter registered the scheme.

Opening a URL does not install an app or register its scheme. If no application can handle a custom scheme, the request fails instead of reporting success. On iOS, the first custom-scheme handoff can show an Open in “App”? system confirmation after the URL acknowledgement succeeds. Confirm Open in the viewer before asserting app state. Automated visual proof can wait for the prompt and send an authenticated normalized tap to its button. The maintained iOS proof waits at least five seconds for the prompt, taps once, then allows at least five seconds for the app to render before capture. Its HTTPS proof also allows five seconds for the browser to reach its final state. Android does not receive that iOS-only tap.

Preserve encoding safely

Supply one absolute URI with a standard scheme. Relative paths and blank values are rejected.
Percent-encode individual path, query, and fragment values. Do not percent-encode the entire URI, because that also hides its : and / delimiters.
Keep the CLI argument quoted. Characters such as &, #, ?, ;, and command-substitution text remain URL data. The URL is passed as one inert argument; Android’s platform bridge quotes shell metacharacters so they are not evaluated as commands.
The API accepts targets from 1 to 4,096 characters and rejects raw ASCII whitespace, control characters, malformed schemes or percent escapes, and HTTP(S) URLs without a hostname. It also rejects about:, data:, file:, javascript:, and vbscript: targets.
Compare the returned url with the input when an automation run must prove transport fidelity. If they match but the app displays a different route, inspect the app’s own link parser.

Troubleshooting

Public errors include ok: false, outer action: "open-url", platform, available session/device/lease scope, and a nested error object with code, message, retryable, and sometimes action with a concrete next step.

Code	HTTP	Retry?	What to do
`invalid_url`	400	No	Use an allowed absolute URI, remove raw whitespace/control characters, correct malformed percent escapes, percent-encode spaces, and keep it within 4,096 characters.
`open_url_scope_required`	403	No	Transport only: the authenticated lease scope does not permit URL opening for that device. Use the public session operation through the CLI or SDK; recreate the session if it persists.
`active_session_not_found`	404	No	The session is inactive, belongs to another account, or is under the other platform. Run `runcloud ios get <id>` or `runcloud android get <id>` with the same credential.
`simulator_session_ended`	410	No	The authenticated simulator lease has ended. Create a new session and use its new session id.
`ios_url_handler_not_found`	422	No	Install a simulator-compatible app whose `CFBundleURLSchemes` contains the custom scheme.
`android_url_handler_not_found`	422	No	Install an APK with an exported activity whose `VIEW`, `DEFAULT`, and `BROWSABLE` intent filter registers the scheme.
`simulator_unavailable`	503	Yes	Confirm that the session is still active, then retry with a bounded backoff.
`open_url_timeout`	504	Yes	The platform did not finish before the deadline. Check session state before retrying.
`ios_open_url_failed` or `android_open_url_failed`	502	Yes	Read `message` and `action`, inspect the signed viewer and platform logs, then retry only after correcting the reported condition.
`open_url_transport_error`, `open_url_invalid_response`, or `open_url_failed`	502	Yes	The gateway could not complete or verify the platform request. Check session health before a bounded retry.

If a link is truncated in a terminal, quote the entire URI. An unquoted & backgrounds a shell command, and an unquoted # can start a shell comment. If the request succeeds but the expected screen is missing, inspect the viewer or take a screenshot and check the app’s own route configuration. SDK failures throw RunCloudError. Inspect status, code, detail, retryable, platform, and sessionId rather than matching a complete error sentence. action identifies the failed SDK operation ("open-url"); suggestedAction contains the human-readable remediation returned as error.action by the API.

Getting Started

Linux Sandboxes

CI

Integrations

Platform

iOS

Android

Billing

Agents

Open URLs and Deep Links

Authenticate

Use the CLI

Use the TypeScript SDK

Call the REST API

Platform behavior

Preserve encoding safely

Troubleshooting

​Authenticate

​Use the CLI

​Use the TypeScript SDK

​Call the REST API

​Platform behavior

​Preserve encoding safely

​Troubleshooting

Authenticate

Use the CLI

Use the TypeScript SDK

Call the REST API

Platform behavior

Preserve encoding safely

Troubleshooting