run-cloud-sandboxes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Operate run.cloud Sandboxes

操作run.cloud沙箱

Use the

runcloud

CLI for terminal and interactive workflows. Use

@run-cloud/sdk

for TypeScript applications, CI, and agent code.

对于终端和交互式工作流，使用

runcloud

CLI。对于TypeScript应用、CI和Agent代码，使用

@run-cloud/sdk

。

Authenticate

身份验证

Install the CLI with
```
npm install -g runcloud
```
.
Use
```
runcloud login
```
for an interactive browser handoff. Use
```
runcloud login --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 the production default
```
https://api.run.cloud
```
.
Never print, commit, or place credentials in a skill file.
Treat signed desktop and tunnel URLs as bearer secrets.
Require Node.js 20 or newer for the CLI and TypeScript SDK.

Inspect account and organization usage before starting metered work:

bash

runcloud account --json

使用
```
npm install -g runcloud
```
安装CLI。
使用
```
runcloud login
```
进行交互式浏览器授权。当无法打开本地回调时，使用
```
runcloud login --manual
```
。
在CI环境中，设置
```
RUN_CLOUD_API_KEY
```
。
```
RUN_CLOUD_API_TOKEN
```
是其等效别名。
仅当需要覆盖生产环境默认地址
```
https://api.run.cloud
```
时，设置
```
RUN_CLOUD_API_URL
```
。
绝不要打印、提交或在技能文件中放置凭证。
将已签名的桌面和隧道URL视为Bearer密钥。
CLI和TypeScript SDK要求Node.js 20或更高版本。

在开始计量工作前，检查账户和组织使用情况：

bash

runcloud account --json

Choose the Interface

选择交互方式

Prefer CLI commands with
```
--json
```
for shell automation.
Prefer the TypeScript SDK when code needs streaming command output, binary file transfer, retry-safe creation, or short-lived public tunnels.
Inspect
```
runcloud sandbox --help
```
, a subcommand's
```
--help
```
, or installed SDK types before using a method not documented here.
Use the
```
sandbox
```
noun. The older
```
box
```
commands are deprecated aliases.

对于Shell自动化，优先使用带
```
--json
```
参数的CLI命令。
当代码需要流式命令输出、二进制文件传输、可重试创建或短期公共隧道时，优先使用TypeScript SDK。
在使用本文档未记录的方法前，查看
```
runcloud sandbox --help
```
、子命令的
```
--help
```
或已安装SDK的类型定义。
使用
```
sandbox
```
名词。旧版
```
box
```
命令已废弃，仅作为别名存在。

Run a CLI Lifecycle

执行CLI生命周期流程

Create a sandbox, capture its ID, run a command, and destroy it:

bash

SANDBOX_ID=$(runcloud sandbox create \
  --image runcloud/agent-base \
  --timeout 900 \
  --json | jq -r '.id')

trap 'runcloud sandbox rm "$SANDBOX_ID" >/dev/null 2>&1 || true' EXIT

runcloud sandbox get "$SANDBOX_ID" --json
runcloud sandbox exec "$SANDBOX_ID" "npm install && npm test"

The main lifecycle commands are:

```
runcloud sandbox create
```
```
runcloud sandbox list [--state <state>]
```
```
runcloud sandbox get <id>
```
```
runcloud sandbox exec <id> <cmd...>
```
```
runcloud sandbox shell <id>
```
```
runcloud sandbox pause|resume <id>
```

runcloud sandbox logs <id> [--lines <n>]

runcloud sandbox metrics <id> [--range <range>] [--watch]

```
runcloud sandbox rm <id>
```

Create accepts

--image

--region

--name

--org

--cpu

--memory

--disk

--idle-pause

--timeout

--persistent

--expose

, secret selectors,

--no-wait

, and

--json

The default reservation is 0.125 vCPU and 128 MiB when CPU and memory are omitted. Set finite timeouts for unattended work. Use

--timeout 0

only when a persistent workload is intentional.

CLI

exec

runs through

/bin/sh -c

and returns the guest command's exit code. A paused sandbox must be resumed before

exec

;

shell

resumes it automatically.

创建沙箱、捕获其ID、运行命令并销毁它：

bash

SANDBOX_ID=$(runcloud sandbox create \
  --image runcloud/agent-base \
  --timeout 900 \
  --json | jq -r '.id')

trap 'runcloud sandbox rm "$SANDBOX_ID" >/dev/null 2>&1 || true' EXIT

runcloud sandbox get "$SANDBOX_ID" --json
runcloud sandbox exec "$SANDBOX_ID" "npm install && npm test"

主要的生命周期命令包括：

```
runcloud sandbox create
```
```
runcloud sandbox list [--state <state>]
```
```
runcloud sandbox get <id>
```
```
runcloud sandbox exec <id> <cmd...>
```
```
runcloud sandbox shell <id>
```
```
runcloud sandbox pause|resume <id>
```

runcloud sandbox logs <id> [--lines <n>]

runcloud sandbox metrics <id> [--range <range>] [--watch]

```
runcloud sandbox rm <id>
```

create

命令支持

--image

、

--region

、

--name

、

--org

、

--cpu

、

--memory

、

--disk

、

--idle-pause

、

--timeout

、

--persistent

、

--expose

、密钥选择器、

--no-wait

和

--json

参数。

当省略CPU和内存参数时，默认预留0.125 vCPU和128 MiB内存。对于无人值守的工作，设置有限的超时时间。仅当需要持久化工作负载时，才使用

--timeout 0

。

CLI的

exec

命令通过

/bin/sh -c

执行，并返回客端命令的退出码。暂停的沙箱必须先恢复才能执行

exec

；

shell

命令会自动恢复沙箱。

Use the TypeScript SDK

使用TypeScript SDK

Install the SDK:

bash

npm install @run-cloud/sdk

Use an idempotency key when a job runner may retry creation, check non-zero exit codes explicitly, and always destroy metered resources:

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

const cloud = new Client();
const sandbox = await cloud.sandboxes.create({
  image: "runcloud/agent-base",
  cpu: 1,
  memory: 1024,
  timeoutSeconds: 900,
  idempotencyKey: process.env.CI_JOB_ID,
});

try {
  const result = await cloud.sandboxes.exec(
    sandbox.id,
    ["npm", "test"],
    {
      onStdout: (chunk) => process.stdout.write(chunk),
      onStderr: (chunk) => process.stderr.write(chunk),
    },
  );
  if (result.exitCode !== 0) {
    throw new Error(`tests failed with exit code ${result.exitCode}`);
  }
} finally {
  await cloud.sandboxes.destroy(sandbox.id);
}

The TypeScript sandbox surface is:

cloud.sandboxes

create

list

get

exec

readFile

writeFile

openTunnel

closeTunnel

setTimeout

snapshot

destroy

, and the

delete

alias

```
cloud.snapshots
```
:
```
list
```
,
```
restore
```
,
```
delete
```
```
cloud.account()
```
and
```
cloud.usage({ orgId? })
```

A string passed to SDK

exec

runs through

/bin/sh -c

; an argv array executes directly. A non-zero guest exit code is returned rather than thrown. Use

cwd

env

timeoutSeconds

onStdout

onStderr

, and

signal

as needed.

Use

readFile

and

writeFile

for binary-safe SDK file transfer. For interactive terminal workflows, configure SSH with

runcloud sandbox setup-ssh

and inspect

runcloud sandbox ssh

cp

, and

code

help before use.

安装SDK：

bash

npm install @run-cloud/sdk

当作业运行器可能重试创建操作时，使用幂等键；显式检查非零退出码；并始终销毁计量资源：

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

const cloud = new Client();
const sandbox = await cloud.sandboxes.create({
  image: "runcloud/agent-base",
  cpu: 1,
  memory: 1024,
  timeoutSeconds: 900,
  idempotencyKey: process.env.CI_JOB_ID,
});

try {
  const result = await cloud.sandboxes.exec(
    sandbox.id,
    ["npm", "test"],
    {
      onStdout: (chunk) => process.stdout.write(chunk),
      onStderr: (chunk) => process.stderr.write(chunk),
    },
  );
  if (result.exitCode !== 0) {
    throw new Error(`tests failed with exit code ${result.exitCode}`);
  }
} finally {
  await cloud.sandboxes.destroy(sandbox.id);
}

TypeScript沙箱的核心接口包括：

cloud.sandboxes

：

create

、

list

、

get

、

exec

、

readFile

、

writeFile

、

openTunnel

、

closeTunnel

、

setTimeout

、

snapshot

、

destroy

，以及别名

delete

```
cloud.snapshots
```
：
```
list
```
、
```
restore
```
、
```
delete
```
```
cloud.account()
```
和
```
cloud.usage({ orgId? })
```

传递给SDK

exec

的字符串会通过

/bin/sh -c

执行；参数数组则会直接执行。客端返回的非零退出码会被返回而非抛出异常。可根据需要使用

cwd

、

env

、

timeoutSeconds

、

onStdout

、

onStderr

和

signal

参数。

使用

readFile

和

writeFile

进行二进制安全的SDK文件传输。对于交互式终端工作流，使用

runcloud sandbox setup-ssh

配置SSH，并在使用前查看

runcloud sandbox ssh

、

cp

和

code

命令的帮助文档。

Snapshot and Restore

快照与恢复

Snapshot a prepared filesystem and restore it into fresh sandboxes:

bash

runcloud sandbox snapshot create "$SANDBOX_ID" --label deps-installed --json
runcloud sandbox snapshot list --json
runcloud sandbox restore <snapshot-id> --json
runcloud sandbox snapshot rm <snapshot-id>

The SDK equivalents are

cloud.sandboxes.snapshot

cloud.snapshots.restore

cloud.snapshots.list

, and

cloud.snapshots.delete

A restore creates a new billed sandbox with a new ID. One snapshot can fan out to parallel workers, but every restored sandbox counts toward concurrency and must be destroyed. A restored sandbox inherits no secrets; attach only the secrets it needs.

为已准备好的文件系统创建快照，并将其恢复到新沙箱中：

bash

runcloud sandbox snapshot create "$SANDBOX_ID" --label deps-installed --json
runcloud sandbox snapshot list --json
runcloud sandbox restore <snapshot-id> --json
runcloud sandbox snapshot rm <snapshot-id>

对应的SDK方法为

cloud.sandboxes.snapshot

、

cloud.snapshots.restore

、

cloud.snapshots.list

和

cloud.snapshots.delete

。

恢复操作会创建一个新的计费沙箱并生成新ID。一个快照可以扩展到多个并行工作器，但每个恢复的沙箱都会占用并发资源，必须被销毁。恢复后的沙箱不会继承任何密钥；仅附加它所需的密钥即可。

Use Images

使用镜像

Use reusable images when every sandbox needs the same base tools:

bash

runcloud image create my-agent --dockerfile ./Dockerfile
runcloud image list --json
runcloud sandbox create --image my-agent --json
runcloud image refresh my-agent

Inspect

runcloud image --help

for current build-source options. Do not invent image methods on the TypeScript SDK.

当每个沙箱都需要相同的基础工具时，使用可复用镜像：

bash

runcloud image create my-agent --dockerfile ./Dockerfile
runcloud image list --json
runcloud sandbox create --image my-agent --json
runcloud image refresh my-agent

查看

runcloud image --help

获取当前的构建源选项。不要在TypeScript SDK中自行实现镜像相关方法。

Expose a Service

暴露服务

Choose one exposure model deliberately:

For a stable hostname, create with

runcloud sandbox create --name <name> --expose <port> --persistent

, or use

runcloud sandbox expose <id> --port <port>

For a short-lived random URL in TypeScript, call

cloud.sandboxes.openTunnel(id, port, { ttlSeconds })

, then

closeTunnel(id, tunnel.id)

An SDK tunnel does not make the sandbox persistent or disable idle pause. Do not log its URL. Revocation can take effect shortly after

closeTunnel

returns; stop the guest service or destroy the sandbox when access must end immediately.

谨慎选择一种暴露模式：

若需要稳定的主机名，使用

runcloud sandbox create --name <name> --expose <port> --persistent

创建沙箱，或使用

runcloud sandbox expose <id> --port <port>

。

若需要TypeScript中的短期随机URL，调用

cloud.sandboxes.openTunnel(id, port, { ttlSeconds })

，之后调用

closeTunnel(id, tunnel.id)

。

SDK隧道不会使沙箱持久化或禁用空闲暂停功能。不要记录其URL。调用

closeTunnel

后，撤销操作会立即生效；当必须立即终止访问时，请停止客端服务或销毁沙箱。

Handle Secrets Safely

安全处理密钥

Create secret groups from
```
--from-dotenv
```
,
```
--from-json
```
,
```
--stdin
```
, a file, or a hidden prompt. Never pass a secret value as a command argument.
Attach only the required groups or names with repeatable
```
--secret-group
```
and
```
--secret
```
. Later selectors win on name collisions;
```
--env
```
is applied last.
Use
```
--no-secrets
```
to state explicitly that a new sandbox needs none.
Treat
```
runcloud sandbox secrets <id> ...
```
as full replacement, not a merge.
Remember that values cannot be read back and snapshots do not contain secrets.

Inspect

runcloud secret-group --help

and

runcloud secrets --help

for the current non-plaintext input forms.

通过
```
--from-dotenv
```
、
```
--from-json
```
、
```
--stdin
```
、文件或隐藏提示创建密钥组。绝不要将密钥值作为命令参数传递。
仅使用可重复的
```
--secret-group
```
和
```
--secret
```
参数附加所需的组或名称。当名称冲突时，后续的选择器优先级更高；
```
--env
```
会最后应用。
使用
```
--no-secrets
```
明确表示新沙箱不需要任何密钥。
将
```
runcloud sandbox secrets <id> ...
```
视为完全替换操作，而非合并操作。
请注意，密钥值无法被回读，且快照中不包含密钥。

查看

runcloud secret-group --help

和

runcloud secrets --help

获取当前的非明文输入形式。

Operate Desktop Sandboxes

操作桌面沙箱

For a compatible desktop image, use

runcloud sandbox desktop <id>

to open its signed browser desktop. The CLI also provides

screenshot

click

type

, and

key

subcommands for explicit pixel-coordinate automation. Keep signed desktop URLs private and inspect each subcommand's help before automation.

对于兼容的桌面镜像，使用

runcloud sandbox desktop <id>

打开其已签名的浏览器桌面。CLI还提供

screenshot

、

click

、

type

和

key

子命令，用于基于像素坐标的显式自动化。请保持已签名的桌面URL私密，并在自动化前查看每个子命令的帮助文档。

Guardrails

防护准则

Destroy every sandbox created during a task unless the user explicitly asks to keep it. Also remove unused snapshots, tunnels, and public hostnames.
Use
```
try/finally
```
or a shell trap around every metered lifecycle.
Check
```
exitCode
```
; do not treat a completed SDK
```
exec
```
call as success by itself.
Do not expose API credentials, secret values, signed desktop URLs, or tunnel URLs in logs, screenshots, PR comments, or chat output.
Do not claim that CLI-only lifecycle, image, secret-group, desktop, or stable hostname commands are TypeScript SDK methods.

除非用户明确要求保留，否则销毁任务期间创建的所有沙箱。同时删除未使用的快照、隧道和公共主机名。
在每个计量生命周期流程周围使用
```
try/finally
```
或Shell陷阱。
检查
```
exitCode
```
；不要仅将SDK
```
exec
```
调用完成视为成功。
不要在日志、截图、PR评论或聊天输出中暴露API凭证、密钥值、已签名的桌面URL或隧道URL。
不要声称仅CLI支持的生命周期、镜像、密钥组、桌面或稳定主机名命令是TypeScript SDK的方法。