镜像与构建

镜像登记、从沙箱保存镜像、Dockerfile 构建作业。 完整参数、请求 / 响应 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

镜像登记、从沙箱保存镜像、Dockerfile 构建作业。

镜像与构建 Operations

• get/agents
• get/images
• post/images
• delete/images/{ref}
• post/builds
• get/builds
• get/builds/{id}
• delete/builds/{id}
• get/builds/{id}/log

可用 agent 镜像列表（平台登记册已上线行 + 本组织用户镜像）

​Copy link

Auth Required

Copy as Markdown

前端创建表单的 Agent Image 选择数据源，两段构成：

• 平台段：登记册 status=published 的行，逐个对盘校验 manifest； 顺序 = 登记册的人工排序（sort_order，管理员可调）—— 第一项即创建页 默认选中的镜像。source 恒为 platform。
• 用户段：调用者本组织的自建镜像（saved / built），按 name/version 升序追加在平台段之后。其他组织的用户镜像不在响应里。

两段的 source 字段供客户端分组展示（官方 / 我的）。

Responses

• 200

  镜像列表（展示名由客户端拼 name@version）

  application/json
• 401

  未认证

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for get/agents

Shell Curl

curl https://api.rayrunos.com/v1/agents \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 200 镜像列表（展示名由客户端拼 name@version）Status: 401 未认证Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "agents": [
    {
      "name": "claude-code",
      "version": "1",
      "source": "platform",
      "description": "string",
      "allow_domains": [
        "mirrors.aliyun.com"
      ],
      "credential_slots": [
        "ANTHROPIC_AUTH_TOKEN"
      ],
      "supports_desktop": true,
      "desktop_port": 6080
    }
  ]
}

JSONCopy

JSONCopy

镜像列表（展示名由客户端拼 name@version）

镜像列表（平台 + 保存 + 构建，带来源与实占）

​Copy link

Auth Required

Copy as Markdown

列表项的 size_bytes 是本镜像自身的实占（不含它引用的基座）： 派生镜像的 rootfs.ext4 是软链，基座共享 —— 算进来会重复计数。

Responses

• 200

  镜像列表（按 name/version 排序；不分页）

  application/json
• 401

  未认证

  application/json
• 500

  内部错误

  application/json

Request Example for get/images

Shell Curl

curl https://api.rayrunos.com/v1/images \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 200 镜像列表（按 name/version 排序；不分页）Status: 401 未认证Status: 500 内部错误

Show Schema

{
  "images": [
    {
      "ref": "string",
      "name": "string",
      "version": "string",
      "source": "platform",
      "description": "string",
      "base": null,
      "base_image": null,
      "size_bytes": 1,
      "created_at": null,
      "owner_user_id": "string"
    }
  ]
}

JSONCopy

JSONCopy

镜像列表（按 name/version 排序；不分页）

从沙箱保存镜像（同步，秒级）

​Copy link

Auth Required

Copy as Markdown

要求源沙箱处于 Stopped（否则 409 sandbox_not_stopped）—— 不静默停掉用户正在跑的 agent 任务。构建沙箱不可保存（409 illegal_state）。

产出 = 一张 overlay.ext4（源沙箱叠加盘的稀疏复制）+ 一条指回基座的 rootfs.ext4 软链 + 派生 manifest + image.json。同名再次保存递增 版本号（myimg@1 → myimg@2），不覆盖。

注意：完整 Dockerfile 构建（POST /v1/builds）不走本端点，产物是独立 rootfs（image.json v2 standalone）。

Body

required

application/json

• name

  Type: string

  required

  Copy link to name

  小写字母数字与 . _ -，≤64 字；同时是镜像目录名

• sandbox_id

  Type: stringFormat: uuid

  required

  Copy link to sandbox_id
• description

  Type: stringCopy link to description

  卡片上的一两行说明，≤200 字（写进 manifest [agent].description）

Responses

• 201

  保存成功

  application/json
• 400

  请求体非法（名字/描述不合法、sandbox_id 非 uuid）

  application/json
• 401

  未认证

  application/json
• 404

  沙箱不存在或不属于本组织

  application/json
• 409

  沙箱未停止（sandbox_not_stopped）、构建沙箱不可保存（illegal_state）或名称冲突（name_conflict）

  application/json
• 500

  内部错误（复制失败等）

  application/json

Request Example for post/images

Shell Curl

curl https://api.rayrunos.com/v1/images \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "sandbox_id": "",
  "name": "",
  "description": ""
}'

cURLCopy

cURLCopy

Status: 201 保存成功Status: 400 请求体非法（名字/描述不合法、sandbox_id 非 uuid）Status: 401 未认证Status: 404 沙箱不存在或不属于本组织Status: 409 沙箱未停止（`sandbox_not_stopped`）、构建沙箱不可保存（`illegal_state`）或名称冲突（`name_conflict`）Status: 500 内部错误（复制失败等）

Show Schema

{
  "ref": "string",
  "name": "string",
  "version": "string",
  "source": "platform",
  "description": "string",
  "base": null,
  "base_image": null,
  "size_bytes": 1,
  "created_at": null,
  "owner_user_id": "string"
}

JSONCopy

JSONCopy

保存成功

删除用户自建镜像

​Copy link

Auth Required

Copy as Markdown

平台镜像（无 image.json）不可删（403）。被沙箱引用（存在非 Terminated 且 agent == ref 的沙箱）或被派生镜像引用（另一张镜像的 rootfs.ext4 软链指向它）时 409 image_in_use —— 后者是「断链」：不挡的话删除当时 不报错、下次创建才炸。

Path Parameters

• ref

  Type: string

  required

  Copy link to ref

  @

Responses

• 204

  Copy link to 204

  已删除

• 400

  ref 形态非法

  application/json
• 401

  未认证

  application/json
• 403

  平台镜像 / 他组织的镜像不可删

  application/json
• 404

  镜像不存在

  application/json
• 409

  镜像被引用（image_in_use）

  application/json
• 500

  内部错误

  application/json

Request Example for delete/images/{ref}

Shell Curl

curl 'https://api.rayrunos.com/v1/images/{ref}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 204 已删除Status: 400 ref 形态非法Status: 401 未认证Status: 403 平台镜像 / 他组织的镜像不可删Status: 404 镜像不存在Status: 409 镜像被引用（`image_in_use`）Status: 500 内部错误

No Body

已删除

提交 Dockerfile 构建（异步，202）

​Copy link

Auth Required

Copy as Markdown

在隔离的构建沙箱里用 buildah 执行完整 Dockerfile（多阶段、COPY/ADD、 ARG、USER、SHELL、heredoc 等）。FROM 支持公共 registry 镜像；V1 不支持 FROM <rayrun-ref>（返回 400 unsupported_base）。

两种提交方式：

• application/json：只有 Dockerfile 文本，没有构建上下文（兼容旧客户端）；
• multipart/form-data：Dockerfile + 可选 context.tar.gz（COPY 需要）， egress / build_args 以 JSON 字符串字段传递。

副作用在 202 之前发生：校验、FROM 预处理、egress 合并、context 落盘 全部先做完 —— 配方错了不会有半个沙箱留下。

Body

required

Selected Content Type: application/json

• dockerfile

  Type: string

  required

  Copy link to dockerfile

  Dockerfile 原文，≤256 KiB

• name

  Type: string

  required

  Copy link to name

  产出的镜像名（小写字母数字与 . _ -，≤64 字）

• build_args

  Type: objectCopy link to build_args

  构建参数（最多 100 项；值不会写入审计日志）

  Properties: 1
• description

  Type: stringCopy link to description

  镜像说明，≤200 字

• egress

  Type: Egress{ allow, allow_all, bandwidth_mbps, +1 }Copy link to egress
  Properties: 4

Responses

• 202

  已受理（status=pending，排队或正在跑）

  application/json
• 400

  Dockerfile 非法、FROM <rayrun-ref>（unsupported_base）、名称非法、egress 非法、context 不是 gzip

  application/json
• 401

  未认证

  application/json
• 409

  名称冲突（name_conflict）或构建队列已满 （resource_exhausted）

  application/json
• 413

  Dockerfile 超过 256 KiB 或 context 超过上传上限（payload_too_large）

  application/json
• 500

  内部错误

  application/json
• 503

  依赖（MariaDB / Redis）运行时不可用，或构建器镜像缺失（builder_image_missing）

  application/json

Request Example for post/builds

Shell Curl

curl https://api.rayrunos.com/v1/builds \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "",
  "description": "",
  "dockerfile": "",
  "egress": {
    "allow": [
      ""
    ],
    "deny": [
      ""
    ],
    "allow_all": false,
    "bandwidth_mbps": 0
  },
  "build_args": {
    "additionalProperty": ""
  }
}'

cURLCopy

cURLCopy

Status: 202 已受理（status=pending，排队或正在跑）Status: 400 Dockerfile 非法、`FROM <rayrun-ref>`（`unsupported_base`）、名称非法、egress 非法、context 不是 gzipStatus: 401 未认证Status: 409 名称冲突（`name_conflict`）或构建队列已满 （`resource_exhausted`） Status: 413 Dockerfile 超过 256 KiB 或 context 超过上传上限（`payload_too_large`）Status: 500 内部错误Status: 503 依赖（MariaDB / Redis）运行时不可用，或构建器镜像缺失（`builder_image_missing`）

Show Schema

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "kind": "save",
  "status": "pending",
  "image_name": "string",
  "dockerfile": "string",
  "image_ref": null,
  "base_agent": "string",
  "base_image": null,
  "has_context": true,
  "context_bytes": 1,
  "image_size_bytes": null,
  "failure_reason": null,
  "sandbox_id": null,
  "created_at": "2026-11-11T06:00:17.727Z",
  "started_at": null,
  "finished_at": null
}

JSONCopy

JSONCopy

已受理（status=pending，排队或正在跑）

构建作业历史（Builds tab 的数据源）

​Copy link

Auth Required

Copy as Markdown

作业状态是 journal 的物化视图（不新开表）。保存也产生一条历史记录 （kind=save，瞬时完成）——「创建镜像就产生一条记录」，两条来源口径一致。 最新在前。

Query Parameters

• limit

  Type: integer

  min:  

  1

  max:  

  200Copy link to limit

  省略 = 全量（单机作业规模是几十到几百）

Responses

• 200

  作业列表（最新在前）

  application/json
• 401

  未认证

  application/json
• 500

  内部错误

  application/json

Request Example for get/builds

Shell Curl

curl https://api.rayrunos.com/v1/builds \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 200 作业列表（最新在前）Status: 401 未认证Status: 500 内部错误

Show Schema

{
  "builds": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "kind": "save",
      "status": "pending",
      "image_name": "string",
      "dockerfile": "string",
      "image_ref": null,
      "base_agent": "string",
      "base_image": null,
      "has_context": true,
      "context_bytes": 1,
      "image_size_bytes": null,
      "failure_reason": null,
      "sandbox_id": null,
      "created_at": "2026-11-11T06:00:17.727Z",
      "started_at": null,
      "finished_at": null
    }
  ]
}

JSONCopy

JSONCopy

作业列表（最新在前）

单个构建作业（状态 + 失败原因）

​Copy link

Auth Required

Copy as Markdown

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

Responses

• 200

  作业详情

  application/json
• 400

  id 非 uuid

  application/json
• 401

  未认证

  application/json
• 404

  作业不存在或不属于本组织

  application/json

Request Example for get/builds/{id}

Shell Curl

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

cURLCopy

cURLCopy

Status: 200 作业详情Status: 400 id 非 uuidStatus: 401 未认证Status: 404 作业不存在或不属于本组织

Show Schema

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "kind": "save",
  "status": "pending",
  "image_name": "string",
  "dockerfile": "string",
  "image_ref": null,
  "base_agent": "string",
  "base_image": null,
  "has_context": true,
  "context_bytes": 1,
  "image_size_bytes": null,
  "failure_reason": null,
  "sandbox_id": null,
  "created_at": "2026-11-11T06:00:17.727Z",
  "started_at": null,
  "finished_at": null
}

JSONCopy

JSONCopy

作业详情

取消构建作业

​Copy link

Auth Required

Copy as Markdown

幂等：已终态 → 204（不写第二条终态记录），不存在 → 404。

取消是免费的：cancel 驱动 ctx → 关掉 exec 的 5003 连接 → guestd 杀整个进程组。构建沙箱随后被销毁。

另一个入口：删掉构建沙箱（DELETE /v1/sandboxes/{id}）等价于取消 （—— 两个入口同一个后果，不留「沙箱没了但作业还在跑」）。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

Responses

• 204

  Copy link to 204

  已取消（或本就是终态）

• 401

  未认证

  application/json
• 404

  作业不存在

  application/json

Request Example for delete/builds/{id}

Shell Curl

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

cURLCopy

cURLCopy

Status: 204 已取消（或本就是终态）Status: 401 未认证Status: 404 作业不存在

No Body

已取消（或本就是终态）

构建日志（纯文本，增量轮询）

​Copy link

Auth Required

Copy as Markdown

返回 text/plain，并带 X-Next-Offset 响应头：客户端下一次带上 ?offset=<该值> 取增量。单次最多 256 KiB。

日志是追加文件（<DataDir>/builds/<id>/log），不是流式通道 —— 少一个长连接要管。单条 RUN 的输出超过 4 MiB（exec 契约上限） 时写 [truncated] 标记并继续构建（不因日志丢而失败）。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

Query Parameters

• offset

  Type: integerFormat: int64

  min:  

  0Copy link to offset

  起始字节偏移；省略 = 从头读

Responses

• 200

  日志片段（作业存在但还没写日志时返回空串，不是 404）

  text/plain
• 400

  参数非法

  application/json
• 401

  未认证

  application/json
• 404

  作业不存在

  application/json

Request Example for get/builds/{id}/log

Shell Curl

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

cURLCopy

cURLCopy

Status: 200 日志片段（作业存在但还没写日志时返回空串，不是 404）Status: 400 参数非法Status: 401 未认证Status: 404 作业不存在

Show Schema

string

Copy

Copy

日志片段（作业存在但还没写日志时返回空串，不是 404）

Models

Show More