文件

工作区内的列目录 / 下载 / 上传。 完整参数、请求 / 响应 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

• get/sandboxes/{id}/files
• get/sandboxes/{id}/files/{path}
• put/sandboxes/{id}/files/{path}

列目录

​Copy link

Auth Required

Copy as Markdown

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Query Parameters

• path

  Type: stringCopy link to path

  workdir 相对路径；空串/缺省 = workdir 根

Responses

• 200

  目录条目列表

  application/json
• 400

  invalid_request（目标不是目录，目录用本端点）或 invalid_path（规范化 / 前缀校验失败）

  application/json
• 401

  未认证

  application/json
• 404

  沙箱从未存在（not_found）

  application/json
• 409

  沙箱非 Running 且非 Paused（sandbox_not_running：Creating / Stopped / Terminated）。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 get/sandboxes/{id}/files

Shell Curl

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

cURLCopy

cURLCopy

Status: 200 目录条目列表Status: 400 invalid_request（目标不是目录，目录用本端点）或 invalid_path（规范化 / 前缀校验失败）Status: 401 未认证Status: 404 沙箱从未存在（not_found）Status: 409 沙箱非 Running 且非 `Paused`（`sandbox_not_running`：Creating / Stopped / Terminated）。`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

{
  "entries": [
    {
      "name": "string",
      "type": "file",
      "size": null
    }
  ]
}

JSONCopy

JSONCopy

目录条目列表

下载文件

​Copy link

Auth Required

Copy as Markdown

文件字节流。Content-Disposition: attachment; filename=""。 走 vsock read_file（workspace 块设备被 VM 独占挂载，host 不能直读）。 前端用 直连下载。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

• path

  Type: string

  required

  Copy link to path

  workdir 相对路径（Gin 通配 *path；经规范化与前缀校验，失败 → 400 invalid_path）

Responses

• 200

  文件字节流

  application/octet-stream
• 400

  invalid_request（目标是目录，用 list 端点）或 invalid_path（穿越 / 越界 workdir）

  application/json
• 401

  未认证

  application/json
• 404

  沙箱或文件不存在（not_found）

  application/json
• 409

  沙箱非 Running 且非 Paused（sandbox_not_running：Creating / Stopped / Terminated）。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 get/sandboxes/{id}/files/{path}

Shell Curl

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

cURLCopy

cURLCopy

Status: 200 文件字节流Status: 400 invalid_request（目标是目录，用 list 端点）或 invalid_path（穿越 / 越界 workdir）Status: 401 未认证Status: 404 沙箱或文件不存在（not_found）Status: 409 沙箱非 Running 且非 `Paused`（`sandbox_not_running`：Creating / Stopped / Terminated）。`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

null

文件字节流

上传文件

​Copy link

Auth Required

Copy as Markdown

Content-Type: application/octet-stream。daemon 边读边按 512 KiB 分块发往 guestd（vsock 单帧 1 MiB 上限），不设总体上限 —— 唯一边界是 guest workspace 容量，写满 → 500 internal_error（io_error）。 前端（Dashboard）另有 100 MiB 预检，那是 UX 拦截，不是服务端契约。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

• path

  Type: string

  required

  Copy link to path

  workdir 相对路径（Gin 通配 *path；经规范化与前缀校验，失败 → 400 invalid_path）

Body

required

application/json

Responses

• 201

  上传成功

  application/json
• 400

  invalid_path（穿越 / 越界 workdir）

  application/json
• 401

  未认证

  application/json
• 404

  沙箱从未存在（not_found）

  application/json
• 409

  沙箱非 Running 且非 Paused（sandbox_not_running：Creating / Stopped / Terminated）。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 put/sandboxes/{id}/files/{path}

Shell Curl

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

cURLCopy

cURLCopy

Status: 201 上传成功Status: 400 invalid_path（穿越 / 越界 workdir）Status: 401 未认证Status: 404 沙箱从未存在（not_found）Status: 409 沙箱非 Running 且非 `Paused`（`sandbox_not_running`：Creating / Stopped / Terminated）。`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

{
  "path": "string",
  "size": 1
}

JSONCopy

JSONCopy

上传成功

Models

Show More