执行与终端

非交互命令执行与交互式终端会话。 完整参数、请求 / 响应 schema 见下方（本页只渲染该组）：

Open SearchSearchKeyboard Shortcut:Control⌃ k

v0.1.0

OpenAPI 3.0.3

Rayrun API

Download OpenAPI Document

json

Download OpenAPI Document

yaml

Rayrun REST API —— 控制台与命令行（rayrun CLI）的统一接口，也是自托管部署的 第三方集成的接入点。共 13 组、93 个端点（分组见左侧栏或「介绍」页的接口一览）。 基地址与部署同源：<实例地址>/v1（如 https://rayrun.example.com/v1）。 认证：Bearer Token（控制台「设置 → 我的 API Token」或 rayrun login 创建） 或浏览器会话 Cookie；GET /health 免认证。详见「介绍」页的认证一节。

Server

Server:https://api.rayrunos.com/v1

Rayrun 托管平台

Client Libraries

Shell

Ruby

Node.js

PHP

Python

MoreSelect from all clients

Shell Curl

执行与终端

​Copy link

非交互命令执行与交互式终端会话。

执行与终端 Operations

• post/sandboxes/{id}/exec
• post/sandboxes/{id}/terminals
• get/sandboxes/{id}/terminals/{tid}/stream
• post/sandboxes/{id}/terminals/{tid}/input
• post/sandboxes/{id}/terminals/{tid}/resize
• delete/sandboxes/{id}/terminals/{tid}

执行非交互命令

​Copy link

Auth Required

Copy as Markdown

一次非交互命令。同步：响应即命令结束（最长为 timeout_seconds；预生产 nginx 已配 3600s 读超时）。输出上限 4 MiB （stdout+stderr 合计），触顶截断并置 truncated=true。command 与 argv 二选一：给 command ⇒ /bin/sh -c ；给 argv ⇒ 直接 exec 不过 shell。 不挂 Idempotency-Key（重复 exec 合法，与 prompt 同款）。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Body·ExecRequest

required

application/json

POST /v1/sandboxes/{id}/exec 请求

• argv

  Type: array of stringCopy link to argv

  与 command 二选一；直接 exec、不过 shell。空数组 → 400 invalid_request。

• command

  Type: stringCopy link to command

  与 argv 二选一（两者都给或都不给 → 400 invalid_request）。给 command ⇒ 按 /bin/sh -c <command> 执行。全文不进 journal —— 审计走结构化摘要。

• cwd

  Type: stringCopy link to cwd

  可选；只接受绝对路径（daemon 不解析相对路径：传相对值会按 guestd 自己的进程 cwd 解析，不是 workdir，别依赖）；缺省 = manifest [run].workdir。由 guestd 判（必须是存在目录，否则 invalid_arg → 400）；daemon 不做前缀校验 —— 进程工作目录语义，不是受控文件路径 。

• env

  Type: objectCopy link to env

  可选；增量并入基线 env（PID 1 环境 + manifest [run].env，请求值末者 优先）。值不进 journal（摘要器只记 argv 与命令前 128 字符）。

  Properties: 1
• timeout_seconds

  Type: integer

  max:  

  3600Copy link to timeout_seconds

  可选；缺省 300，上限 3600；越界 400 invalid_request

• user

  Type: stringCopy link to user

  可选；只接受 root，其余 400（明确拒绝好过静默降级）

Responses

• 200

  命令已执行完毕

  application/json
• 400

  invalid_request（command 与 argv 二选一缺失或并存、timeout_seconds 越界、user 非 root、cwd 不是存在目录）

  application/json
• 401

  未认证

  application/json
• 404

  沙箱从未存在（not_found）

  application/json
• 409

  sandbox_not_running（非 Running 且非 Paused 沙箱）或 exec_unsupported（该沙箱的镜像/guestd 不支持 exec —— 拨号 5003 失败）。Paused 走 503（见下）。

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用，或沙箱处于 Paused（sandbox_paused）。

  503 而非 404/409：真挂起时进程与内存全保留、只是 vCPU 冻结， resume 后原样可用 ⇒ 语义是「暂时不可用」。409 会指向 start， 而 start 对 Paused 非法；404 是「永久没了」。 不给 Retry-After：暂停时长由用户决定，时长未知。

  与 ingress / 终端面同码（infra/ingress 的 sandbox_paused、 handlers/terminals.go 的 sandboxTerminalReady）—— 同一语义一个 码族，客户端只需认一处。完整口径见 。

  application/json

Request Example for post/sandboxes/{id}/exec

Shell Curl

curl https://api.rayrunos.com/v1/sandboxes/123e4567-e89b-12d3-a456-426614174000/exec \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "command": "",
  "argv": [
    ""
  ],
  "cwd": "",
  "env": {
    "additionalProperty": ""
  },
  "timeout_seconds": 1,
  "user": ""
}'

cURLCopy

cURLCopy

Status: 200 命令已执行完毕Status: 400 invalid_request（command 与 argv 二选一缺失或并存、timeout_seconds 越界、user 非 root、cwd 不是存在目录）Status: 401 未认证Status: 404 沙箱从未存在（not_found）Status: 409 `sandbox_not_running`（非 Running 且非 `Paused` 沙箱）或 `exec_unsupported`（该沙箱的镜像/guestd 不支持 exec —— 拨号 5003 失败）。`Paused` 走 503（见下）。 Status: 500 内部错误Status: 503 依赖不可用，或沙箱处于 `Paused`（`sandbox_paused`）。 **503 而非 404/409**：真挂起时进程与内存全保留、只是 vCPU 冻结， `resume` 后原样可用 ⇒ 语义是「暂时不可用」。409 会指向 `start`， 而 `start` 对 `Paused` 非法；404 是「永久没了」。 **不给 `Retry-After`**：暂停时长由用户决定，时长未知。 与 ingress / 终端面同码（`infra/ingress` 的 `sandbox_paused`、 `handlers/terminals.go` 的 `sandboxTerminalReady`）—— 同一语义一个 码族，客户端只需认一处。完整口径见 。

Show Schema

{
  "exec_id": "123e4567-e89b-12d3-a456-426614174000",
  "exit_code": null,
  "stdout": "string",
  "stderr": "string",
  "duration_ms": 1,
  "timed_out": true,
  "truncated": true,
  "pid": null
}

JSONCopy

JSONCopy

命令已执行完毕

开一条终端会话（起 shell）

​Copy link

Auth Required

Copy as Markdown

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Body

required

application/json

• cols

  Type: integer

  min:  

  1

  max:  

  1000

  required

  Copy link to cols

  终端列数

• rows

  Type: integer

  min:  

  1

  max:  

  1000

  required

  Copy link to rows

  终端行数

Responses

• 201

  会话已建立

  application/json
• 400

  invalid_request（body 非法 / rows/cols 非正）

  application/json
• 404

  沙箱不存在或不属于当前组织（not_found）

  application/json
• 409

  sandbox_not_running（无活跃 guest 会话）或 resource_exhausted （超出每沙箱/全局终端上限）

  application/json
• 503

  sandbox_paused（沙箱已暂停）：会话与 PTY 进程仍在，resume 后可 继续，所以不是 404/409（那两者分别意味着「永久没了」与「没在跑」）。

  application/json

Request Example for post/sandboxes/{id}/terminals

Shell Curl

curl https://api.rayrunos.com/v1/sandboxes/123e4567-e89b-12d3-a456-426614174000/terminals \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "rows": 1,
  "cols": 1
}'

cURLCopy

cURLCopy

Status: 201 会话已建立Status: 400 invalid_request（body 非法 / rows/cols 非正）Status: 404 沙箱不存在或不属于当前组织（not_found）Status: 409 sandbox_not_running（无活跃 guest 会话）或 resource_exhausted （超出每沙箱/全局终端上限） Status: 503 sandbox_paused（沙箱已暂停）：会话与 PTY 进程仍在，**resume 后可 继续**，所以不是 404/409（那两者分别意味着「永久没了」与「没在跑」）。

Show Schema

{
  "terminal_id": "123e4567-e89b-12d3-a456-426614174000",
  "rows": 1,
  "cols": 1
}

JSONCopy

JSONCopy

会话已建立

流式读终端输出

​Copy link

Auth Required

Copy as Markdown

响应体是 guest 侧 PTY 的原始输出字节（含 ANSI 转义序列），不做任何 解释或包装。流结束 = 会话结束（用户敲 exit / 连接断开 / 沙箱销毁）。 不可重放：PTY 是会话态，断线后只能新建会话，没有"续上"这回事。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id
• tid

  Type: stringFormat: uuid

  required

  Copy link to tid

  terminal_id

Responses

• 200

  分块输出流

  application/octet-stream
• 404

  沙箱或终端会话不存在（not_found；两者不可区分）

  application/json
• 503

  sandbox_paused（沙箱已暂停）：会话与 PTY 进程仍在，resume 后可 继续，所以不是 404/409（那两者分别意味着「永久没了」与「没在跑」）。

  application/json

Request Example for get/sandboxes/{id}/terminals/{tid}/stream

Shell Curl

curl https://api.rayrunos.com/v1/sandboxes/123e4567-e89b-12d3-a456-426614174000/terminals/123e4567-e89b-12d3-a456-426614174000/stream \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 200 分块输出流Status: 404 沙箱或终端会话不存在（not_found；两者不可区分）Status: 503 sandbox_paused（沙箱已暂停）：会话与 PTY 进程仍在，**resume 后可 继续**，所以不是 404/409（那两者分别意味着「永久没了」与「没在跑」）。

Show Schema

null

分块输出流

发送按键字节

​Copy link

Auth Required

Copy as Markdown

body 是原始按键字节（不是 JSON）：Enter=\r、Ctrl-C=\x03、 方向键=\x1b[A —— 由前端的终端模拟器直接产出，服务端原样透传。 不落 journal（审计口径）。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id
• tid

  Type: stringFormat: uuid

  required

  Copy link to tid

Body

required

application/json

Responses

• 204

  Copy link to 204

  已写入

• 404

  会话不存在（含"刚因写失败被注销"）

  application/json
• 413

  payload_too_large（单次 ≤ 64 KiB；前端按 32 KiB 分片）

  application/json
• 503

  sandbox_paused（沙箱已暂停）：会话与 PTY 进程仍在，resume 后可 继续，所以不是 404/409（那两者分别意味着「永久没了」与「没在跑」）。

  application/json

Request Example for post/sandboxes/{id}/terminals/{tid}/input

Shell Curl

curl https://api.rayrunos.com/v1/sandboxes/123e4567-e89b-12d3-a456-426614174000/terminals/123e4567-e89b-12d3-a456-426614174000/input \
  --request POST \
  --header 'Content-Type: application/octet-stream' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data-binary 'null'

cURLCopy

cURLCopy

Status: 204 已写入Status: 404 会话不存在（含"刚因写失败被注销"）Status: 413 payload_too_large（单次 ≤ 64 KiB；前端按 32 KiB 分片）Status: 503 sandbox_paused（沙箱已暂停）：会话与 PTY 进程仍在，**resume 后可 继续**，所以不是 404/409（那两者分别意味着「永久没了」与「没在跑」）。

No Body

已写入

改窗口尺寸

​Copy link

Auth Required

Copy as Markdown

走独立的短连接（不是数据连接上加帧）：数据路径因此保持字节透明， input 与 resize 零共享。内核随即向会话投 SIGWINCH。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id
• tid

  Type: stringFormat: uuid

  required

  Copy link to tid

Body

required

application/json

• cols

  Type: integer

  min:  

  1

  max:  

  1000

  required

  Copy link to cols

  Integer numbers.

• rows

  Type: integer

  min:  

  1

  max:  

  1000

  required

  Copy link to rows

  Integer numbers.

Responses

• 204

  Copy link to 204

  已生效

• 404

  会话不存在（not_found）

  application/json
• 503

  sandbox_paused（沙箱已暂停）：会话与 PTY 进程仍在，resume 后可 继续，所以不是 404/409（那两者分别意味着「永久没了」与「没在跑」）。

  application/json

Request Example for post/sandboxes/{id}/terminals/{tid}/resize

Shell Curl

curl https://api.rayrunos.com/v1/sandboxes/123e4567-e89b-12d3-a456-426614174000/terminals/123e4567-e89b-12d3-a456-426614174000/resize \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "rows": 1,
  "cols": 1
}'

cURLCopy

cURLCopy

Status: 204 已生效Status: 404 会话不存在（not_found）Status: 503 sandbox_paused（沙箱已暂停）：会话与 PTY 进程仍在，**resume 后可 继续**，所以不是 404/409（那两者分别意味着「永久没了」与「没在跑」）。

No Body

已生效

关闭终端会话（杀 shell）

​Copy link

Auth Required

Copy as Markdown

204 幂等：会话已不存在也返回 204。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id
• tid

  Type: stringFormat: uuid

  required

  Copy link to tid

Responses

• 204

  Copy link to 204

  已关闭（幂等）

Request Example for delete/sandboxes/{id}/terminals/{tid}

Shell Curl

curl https://api.rayrunos.com/v1/sandboxes/123e4567-e89b-12d3-a456-426614174000/terminals/123e4567-e89b-12d3-a456-426614174000 \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 204 已关闭（幂等）

No Body

已关闭（幂等）

Models

Show More