run-cloud-ios-simulator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Operate run.cloud Mobile Sessions

操作run.cloud移动会话

Use the

runcloud

CLI for terminal workflows,

@run-cloud/sdk

for TypeScript, and

@runcloud/ui

for React embeds.

使用

runcloud

CLI进行终端工作流，

@run-cloud/sdk

用于TypeScript开发，

@runcloud/ui

用于React嵌入。

Authenticate

身份验证

Install the CLI with
```
npm install -g runcloud
```
.
Use
```
runcloud login
```
; add
```
--manual
```
when a local callback cannot open.
In CI, set
```
RUN_CLOUD_API_KEY
```
.
```
RUN_CLOUD_API_TOKEN
```
is an equivalent alias.
Set
```
RUN_CLOUD_API_URL
```
only to override
```
https://api.run.cloud
```
.
Require Node.js 20 or newer.
Never print, commit, or place credentials in a skill file. Treat signed session and tunnel URLs as bearer secrets.

Check access and credit before starting metered work:

bash

runcloud account --json

The SDK equivalents are

cloud.account()

and

cloud.usage({ orgId? })

使用
```
npm install -g runcloud
```
安装CLI。
执行
```
runcloud login
```
进行登录；当本地回调无法打开时，添加
```
--manual
```
参数。
在CI环境中，设置
```
RUN_CLOUD_API_KEY
```
。
```
RUN_CLOUD_API_TOKEN
```
是其等效别名。
仅在需要覆盖默认地址
```
https://api.run.cloud
```
时，设置
```
RUN_CLOUD_API_URL
```
。
需要Node.js 20或更高版本。
切勿打印、提交凭证或将其放入skill文件中。已签名的会话和隧道URL需视为Bearer密钥妥善保管。

在开始计量工作前，检查访问权限和可用额度：

bash

runcloud account --json

对应的SDK方法为

cloud.account()

和

cloud.usage({ orgId? })

。

Create and Release Sessions

创建与释放会话

bash

SESSION_ID=$(runcloud ios create \
  --install ./build/MyApp.tar.gz \
  --inactivity-timeout 60s \
  --hard-timeout 10m \
  --json | jq -r '.id')

trap 'runcloud ios delete "$SESSION_ID" >/dev/null 2>&1 || true' EXIT
runcloud ios get "$SESSION_ID" --json

Replace

ios

with

android

for an Android artifact. The shared lifecycle is

create

list

get

open-url

logs

, and

delete

. Use

--json

whenever another program consumes output, and inspect

runcloud ios|android --help

for create and log options.

iOS needs an Apple Silicon simulator-compatible

.app

.zip

.tar.gz

, or

.ipa

; a device-signed App Store IPA is not a substitute. Android needs an emulator-compatible APK.

bash

SESSION_ID=$(runcloud ios create \
  --install ./build/MyApp.tar.gz \
  --inactivity-timeout 60s \
  --hard-timeout 10m \
  --json | jq -r '.id')

trap 'runcloud ios delete "$SESSION_ID" >/dev/null 2>&1 || true' EXIT
runcloud ios get "$SESSION_ID" --json

若操作Android产物，将

ios

替换为

android

。通用生命周期操作包括

create

、

list

、

get

、

open-url

、

logs

和

delete

。当输出需要被其他程序消费时，使用

--json

参数；可查看

runcloud ios|android --help

获取创建和日志相关的选项。

iOS需要兼容Apple Silicon模拟器的

.app

、

.zip

、

.tar.gz

或

.ipa

文件；经过设备签名的App Store IPA无法替代。Android需要兼容模拟器的APK文件。

Control a Session

控制会话

Both platform groups expose acknowledged controls:

bash

runcloud ios tap "$SESSION_ID" 0.5 0.3 --json
runcloud ios swipe "$SESSION_ID" 0.5 0.8 0.5 0.2 --duration 300 --json
runcloud ios type-text "$SESSION_ID" 'hello' --json
runcloud ios press-key "$SESSION_ID" enter --json
runcloud ios press-button "$SESSION_ID" home --json
runcloud ios screenshot "$SESSION_ID" --output ios.png --json

The full control set is

tap

swipe

gesture

type-text

press-key

press-button

rotate

reload

scroll

toggle-software-keyboard

simulate-memory-warning

rotate-digital-crown

set-render-debug

, and

screenshot

. Every interaction accepts

--request-id

--timeout

, and

--json

; use

runcloud <platform> <control> --help

for its typed arguments.

Coordinates use the current display orientation:

(0, 0)

is top-left and

(1, 1)

is bottom-right. Gesture steps use one or two points with

begin

move

, and

end

phases. Each

delayMs

is the pause before the next step, so the final

end

step must use

. Key names are semantic US-keyboard names; modifiers are

shift

control

alt

, and

meta

. Current mobile sessions do not support Digital Crown input, and Android does not support iOS render-debug controls or the

capsLock

numLock

, and

scrollLock

keys. Handle structured

unsupported_action

errors instead of retrying them.

An acknowledgement means input dispatch completed. Confirm visible app effects with a screenshot or the signed viewer when the outcome matters.

两个平台组均支持以下确认式控制操作：

bash

runcloud ios tap "$SESSION_ID" 0.5 0.3 --json
runcloud ios swipe "$SESSION_ID" 0.5 0.8 0.5 0.2 --duration 300 --json
runcloud ios type-text "$SESSION_ID" 'hello' --json
runcloud ios press-key "$SESSION_ID" enter --json
runcloud ios press-button "$SESSION_ID" home --json
runcloud ios screenshot "$SESSION_ID" --output ios.png --json

完整的控制操作集包括

tap

、

swipe

、

gesture

、

type-text

、

press-key

、

press-button

、

rotate

、

reload

、

scroll

、

toggle-software-keyboard

、

simulate-memory-warning

、

rotate-digital-crown

、

set-render-debug

和

screenshot

。每个交互操作都支持

--request-id

、

--timeout

和

--json

参数；可使用

runcloud <platform> <control> --help

查看其类型化参数。

坐标基于当前显示方向：

(0, 0)

为左上角，

(1, 1)

为右下角。手势步骤包含一个或两个点的

begin

、

move

和

end

阶段。每个

delayMs

是下一步操作前的暂停时间，因此最终的

end

步骤必须设置为

。按键名称为语义化美式键盘名称；修饰键包括

shift

、

control

、

alt

和

meta

。当前移动会话不支持Digital Crown输入，Android不支持iOS的渲染调试控制以及

capsLock

、

numLock

和

scrollLock

按键。遇到结构化的

unsupported_action

错误时，应进行处理而非重试。

确认表示输入调度已完成。当结果至关重要时，可通过截图或已签名的查看器确认应用的可见效果。

Use the TypeScript SDK

使用TypeScript SDK

bash

npm install @run-cloud/sdk

Always release metered sessions in

finally

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

const cloud = new Client();
const session = await cloud.android.create({
  inactivityTimeout: "60s",
  hardTimeout: "10m",
  tags: { owner: "agent" },
});

try {
  await cloud.android.tap(session.id, { x: 0.5, y: 0.3 });
  await cloud.android.typeText(session.id, "hello");
  await cloud.android.pressKey(session.id, "enter");
  const screenshot = await cloud.android.screenshot(session.id);
  await writeFile("android.png", screenshot);
} finally {
  await cloud.android.delete(session.id);
}

cloud.ios

cloud.android

, and the platform-selectable

cloud.simulators

expose

interact

plus convenience methods matching every CLI control above. Interaction options accept

requestId

timeoutMs

, and

signal

; results are typed acknowledgements. Use

RunCloudError

fields such as

code

retryable

requestId

, and

action

when reporting API failures.

The lifecycle surface also includes

create

list

get

openUrl

logs

followLogs

, and

delete

. Both platforms expose

screenshot

; iOS additionally supports

uploadVideo

and

uploadMicrophoneAudio

. Inspect the installed types for complete create, asset, log, and media options.

In compact form,

cloud.ios

create

list

get

openUrl

logs

followLogs

screenshot

cloud.android

provides the same shared lifecycle and control operations.

bash

npm install @run-cloud/sdk

务必在

finally

块中释放计量会话：

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

const cloud = new Client();
const session = await cloud.android.create({
  inactivityTimeout: "60s",
  hardTimeout: "10m",
  tags: { owner: "agent" },
});

try {
  await cloud.android.tap(session.id, { x: 0.5, y: 0.3 });
  await cloud.android.typeText(session.id, "hello");
  await cloud.android.pressKey(session.id, "enter");
  const screenshot = await cloud.android.screenshot(session.id);
  await writeFile("android.png", screenshot);
} finally {
  await cloud.android.delete(session.id);
}

cloud.ios

、

cloud.android

以及支持平台选择的

cloud.simulators

均提供

interact

方法，以及与上述所有CLI控制操作对应的便捷方法。交互选项支持

requestId

、

timeoutMs

和

signal

；返回结果为类型化的确认信息。报告API失败时，可使用

RunCloudError

的字段，如

code

、

retryable

、

requestId

和

action

。

生命周期接口还包括

create

、

list

、

get

、

openUrl

、

logs

、

followLogs

和

delete

。两个平台均支持

screenshot

；iOS额外支持

uploadVideo

和

uploadMicrophoneAudio

。可查看已安装的类型定义获取完整的创建、资源、日志和媒体相关选项。

简洁来说，

cloud.ios

包含：

create

、

list

、

get

、

openUrl

、

logs

、

followLogs

、

screenshot

。

cloud.android

提供相同的通用生命周期和控制操作。

Diagnose App Failures

诊断应用故障

bash

runcloud ios logs "$SESSION_ID" --tail 1000
runcloud android logs "$SESSION_ID" --tail 1000

Use

--follow

while reproducing an issue. Before releasing a failed session, capture a bounded retained snapshot; a follow stream contains only new entries.

bash

runcloud ios logs "$SESSION_ID" --tail 1000
runcloud android logs "$SESSION_ID" --tail 1000

重现问题时可使用

--follow

参数。释放故障会话前，捕获有限的保留快照；实时流仅包含新条目。

Connect Local Development

连接本地开发环境

Connect a local Metro or mock server through the supported sidecar flow:

bash

runcloud ios tunnel "$SESSION_ID" --local-port 8081 --service metro --json
runcloud ios tunnel-status --json

Do not expose an unauthenticated third-party tunnel. If the sidecar is unavailable, report that requirement instead of guessing a public URL.

通过支持的sidecar流程连接本地Metro或模拟服务器：

bash

runcloud ios tunnel "$SESSION_ID" --local-port 8081 --service metro --json
runcloud ios tunnel-status --json

请勿暴露未认证的第三方隧道。若sidecar不可用，应报告该需求而非猜测公共URL。

Embed a Session

嵌入会话

Use
```
RemoteControl
```
from
```
@runcloud/ui
```
with the signed session URL.
Its ref exposes promise-based
```
interact
```
and convenience methods matching the SDK controls. Handle
```
onInteractionResult
```
for inspectable acknowledgements.
Add
```
embed=1
```
to raw iframe URLs. Add
```
loadingGuard=1
```
when interaction should wait for streaming and app readiness.
Raw iframe requests use
```
run-cloud:interaction
```
; acknowledgements use
```
run-cloud:interaction-result
```
. Correlate them by
```
requestId
```
. To stop a pending request, post
```
run-cloud:interaction-cancel
```
with the same
```
requestId
```
and
```
action
```
.
Verify
```
event.source
```
and the exact signed-URL origin, and use that origin as the
```
postMessage
```
target.
Legacy
```
ios-simulator:command
```
messages remain compatibility-only. Prefer the generic acknowledged interaction channel for new code.
Create a new session after an
```
ios-simulator:session-restart-requested
```
message; never reuse an ended URL.

使用
```
@runcloud/ui
```
中的
```
RemoteControl
```
组件，传入已签名的会话URL。
其ref对象提供基于Promise的
```
interact
```
方法，以及与SDK控制操作对应的便捷方法。可通过
```
onInteractionResult
```
处理可检查的确认信息。
在原始iframe URL中添加
```
embed=1
```
参数。当交互需等待流传输和应用就绪时，添加
```
loadingGuard=1
```
参数。
原始iframe请求使用
```
run-cloud:interaction
```
；确认信息使用
```
run-cloud:interaction-result
```
。可通过
```
requestId
```
关联两者。要取消待处理请求，发送带有相同
```
requestId
```
和
```
action
```
的
```
run-cloud:interaction-cancel
```
消息。
验证
```
event.source
```
和确切的已签名URL源，并将该源作为
```
postMessage
```
的目标。
旧版
```
ios-simulator:command
```
消息仅保留兼容性。新代码建议使用通用的确认式交互通道。
收到
```
ios-simulator:session-restart-requested
```
消息后，创建新会话；切勿重用已结束的URL。

Assets, Samples, and Demos

资源、示例与演示

bash

runcloud sample download ios
runcloud asset push ./build/MyApp.tar.gz --name my-app --json
runcloud asset pull <asset-id>
runcloud ios create --install-asset my-app --json
runcloud demo run eight-device-mosaic --open
runcloud demo run live-camera-relay --open

Delete uploaded assets when no longer needed. Bundled demos release their sessions automatically.

bash

runcloud sample download ios
runcloud asset push ./build/MyApp.tar.gz --name my-app --json
runcloud asset pull <asset-id>
runcloud ios create --install-asset my-app --json
runcloud demo run eight-device-mosaic --open
runcloud demo run live-camera-relay --open

不再需要时删除已上传的资源。捆绑的演示会自动释放其会话。

Guardrails

防护准则

Release every session created during a task unless asked to keep it open.
Use inactivity and hard timeouts for unattended work.
Verify artifact/platform compatibility before changing app code after an install failure.
Do not expose credentials, signed viewer URLs, tunnel URLs, or simulator tokens in logs, screenshots, PR comments, or chat output.

除非要求保持会话开启，否则任务中创建的每个会话都需释放。
无人值守工作时使用闲置超时和硬超时设置。
安装失败后，在修改应用代码前验证产物与平台的兼容性。
切勿在日志、截图、PR评论或聊天输出中暴露凭证、已签名的查看器URL、隧道URL或模拟器令牌。