沙箱

沙箱的创建、查看与生命周期（停止 / 启动 / 暂停 / 恢复）。 完整参数、请求 / 响应 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
• get/sandboxes
• get/sandboxes/{id}
• delete/sandboxes/{id}
• put/sandboxes/{id}/labels
• put/sandboxes/{id}/name
• put/sandboxes/{id}/egress
• post/sandboxes/{id}/stop
• post/sandboxes/{id}/start
• post/sandboxes/{id}/pause
• post/sandboxes/{id}/resume
• get/sandboxes/{id}/log

创建沙箱（同步，含 boot 探测，端到端最长 ~15s）

​Copy link

Auth Required

Copy as Markdown

Headers

• Idempotency-Key

  Type: string

  max length:  

  128Copy link to Idempotency-Key

  幂等键；≤ 128 字符；命中则原样重放缓存响应

Body·SandboxCreate

required

application/json

• agent

  Type: string

  required

  Example

  claude-code@1

  Copy link to agent

  "@"，引用 images/ 目录

• cpu_cores

  Type: integer

  min:  

  1

  required

  Copy link to cpu_cores

  Integer numbers.

• memory_mb

  Type: integer

  min:  

  512

  required

  Copy link to memory_mb

  Integer numbers.

• name

  Type: string | null

  max length:  

  64

  required

  Copy link to name

  客户自定义沙箱名，必填非空；同客户内活跃沙箱唯一（重复 → 409 name_conflict）

• budget_cents

  Type: integer | nullFormat: int64Copy link to budget_cents

  单沙箱金额预算（分）。缺省 / 0 = 不设；>0 = 在累计花费估算 达到 50% / 80% / 100% 时各提醒一次（只提醒，不停止沙箱）。 估算含已结算账本与未结算运行/出向，最终以账本为准。

• credentials

  Type: array of stringCopy link to credentials

  凭证名（必须已存在）；永不含值。校验三条，任一不过 400 details.field = credentials：

  1. 每条凭证必须能注入该镜像声明的某个槽位：先按规范槽位， 否则按同厂商的原生槽位（见 ModelProvider.native_credential_names）；
  2. 同一槽位不得选两条（两条模型连接都注入 ANTHROPIC_AUTH_TOKEN， 谁赢取决于注入顺序 —— 显式拒绝，不静默取其一）；
  3. 凭证 config 的键必须 ⊆ 该槽位声明的 config_env； 跨槽位复用只复用密钥，config 不下发。
• egress

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

  Type: "pause" or "stop"enumCopy link to idle_action

  空闲到点动作；缺省 = 跟随平台默认（pause）。

• idle_timeout_seconds

  Type: integer | nullCopy link to idle_timeout_seconds

  空闲自动动作阈值（秒）。缺省 = 跟随平台默认（默认关闭）； 0 = 显式关闭；>0 必须 >= 60。到期默认 pause（保留进程）， 可按 idle_action 改为 stop（冷停）。创建后不可改。

• labels

  Type: objectCopy link to labels

  沙箱标签（key-value）的创建初始值；之后可经 PUT /sandboxes/{id}/labels 全量替换。最多 16 对；键为 1..63 个 字母/数字/_/./-；值非空、最多 255 字符、不含控制字符。任一不合法 → 400 details.field = labels。用于列表展示与 label=key=value 筛选。

  Properties: 1
• max_lifetime_seconds

  Type: integer | nullCopy link to max_lifetime_seconds

  缺省 = 不限制。设置后是单次连续运行的秒数上限：到点冷停 （保留磁盘与数据、不自动重启），手动 start 会开启新一轮；本轮 已超上限的暂停沙箱不能 resume。

• remote_desktop

  Type: booleanCopy link to remote_desktop

  启用镜像预装的远程桌面（仅支持声明了该能力的镜像）。启用后服务端 会启动图形桌面，并把镜像声明的桌面端口自动发布为公开访问地址； 缺省关闭。至少需要 2048 MB 内存。

Show 2 more properties for Request Body

Responses

• 201

  创建成功，status = "Running"

  application/json
• 400

  参数校验失败（agent 镜像不存在、name 格式错、cpu/memory 下限）

  application/json
• 401

  未认证

  application/json
• 403

  欠费停机（insufficient_balance）：创建前检查余额，低于信用额度 即拒绝（不是 409 —— 账户状态拒绝，可充值后重试）。余额越界期间， 该组织运行中 / 已暂停的沙箱先被冷停（磁盘与 IP 保留），宽限期 （默认 3 天，试用更短）内补足余额即可 start 恢复；宽限到点仍欠费 才释放磁盘（arrears_grace_expired）。

  application/json
• 409

  单机资源不足（resource_exhausted）或沙箱名重复（name_conflict）

  application/json
• 500

  创建步骤失败已回滚（journal 落 sandbox.create_failed）

  application/json
• 503

  依赖（MariaDB / Redis）运行时不可用

  application/json

Request Example for post/sandboxes

Shell Curl

curl https://api.rayrunos.com/v1/sandboxes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": null,
  "agent": "claude-code@1",
  "cpu_cores": 1,
  "memory_mb": 512,
  "workspace_mb": 32768,
  "max_lifetime_seconds": null,
  "idle_timeout_seconds": null,
  "idle_action": "pause",
  "budget_cents": null,
  "credentials": [
    ""
  ],
  "ssh_keys": [
    ""
  ],
  "remote_desktop": true,
  "labels": {
    "additionalProperty": ""
  },
  "egress": {
    "allow": [
      ""
    ],
    "deny": [
      ""
    ],
    "allow_all": false,
    "bandwidth_mbps": 0
  }
}'

cURLCopy

cURLCopy

Status: 201 创建成功，status = "Running"Status: 400 参数校验失败（agent 镜像不存在、name 格式错、cpu/memory 下限）Status: 401 未认证Status: 403 欠费停机（`insufficient_balance`）：创建前检查余额，低于信用额度 即拒绝（不是 409 —— 账户状态拒绝，可充值后重试）。余额越界期间， 该组织运行中 / 已暂停的沙箱先被冷停（磁盘与 IP 保留），宽限期 （默认 3 天，试用更短）内补足余额即可 start 恢复；宽限到点仍欠费 才释放磁盘（`arrears_grace_expired`）。 Status: 409 单机资源不足（resource_exhausted）或沙箱名重复（name_conflict）Status: 500 创建步骤失败已回滚（journal 落 sandbox.create_failed）Status: 503 依赖（MariaDB / Redis）运行时不可用

Show Schema

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "build_id": null,
  "name": null,
  "labels": {
    "additionalProperty": "string"
  },
  "agent": "string",
  "cpu_cores": 1,
  "memory_mb": 1,
  "workspace_mb": 1,
  "max_lifetime_seconds": null,
  "idle_timeout_seconds": null,
  "idle_action": "pause",
  "budget_cents": null,
  "ip": null,
  "egress": {
    "allow": [
      "string"
    ],
    "deny": [
      "string"
    ],
    "allow_all": false,
    "bandwidth_mbps": 0
  },
  "ingress": [
    {
      "port": 1,
      "visibility": "public",
      "protocol": "http",
      "url": "string"
    }
  ],
  "credentials": [
    "string"
  ],
  "ssh_keys": [
    "string"
  ],
  "remote_desktop": true,
  "desktop_port": 6080,
  "ssh_connect": "string",
  "status": "Creating",
  "agent_state": {
    "state": "idle",
    "class": "success"
  },
  "usage": {
    "vm_hours": 1,
    "egress_bytes": 1,
    "tokens": {
      "input_tokens": 1,
      "output_tokens": 1,
      "cost_usd": null
    }
  },
  "created_at": "2026-11-11T06:00:17.727Z",
  "destroyed_at": null,
  "destroy_reason": null,
  "stopped_reason": null,
  "pricing": {
    "currency": "string",
    "vm_cents_per_hour": 1,
    "egress_cents_per_gb": 1,
    "storage": {
      "cents_per_gib_month": 1,
      "free_bytes": 1
    }
  }
}

JSONCopy

JSONCopy

创建成功，status = "Running"

列出沙箱（limit 存在时按页码分页，省略则全量）

​Copy link

Auth Required

Copy as Markdown

Query Parameters

• limit

  Type: integer

  min:  

  1

  max:  

  100Copy link to limit

  每页条数（1..100）。省略 = 全量返回（向后兼容 CLI / 外部集成）， 此时 total = 返回条数。提供时按 UUIDv7 倒序（创建时间倒序）分页， 配 page 使用。

• page

  Type: integer

  min:  

  1

  max:  

  1000000

  Default

  1

  Copy link to page

  页码（1 起，默认 1）。只在提供 limit 时生效；只给 page 不给 limit 会 400。

• label

  Type: array of string …16Copy link to label

  标签筛选，可重复，多个条件按 AND 组合：label=key=value。 键 1..63 个字母/数字/_/./-；值 1..255 字符。键重复、格式非法或 超过 16 条 → 400（details.field = label）。省略 = 不筛选； 分页时 total 按筛选后的集合计数。

Responses

• 200

  沙箱列表（列表响应包一层对象；分页时 total 为匹配总数）

  application/json
• 400

  limit / page / label 参数非法（details.field 指向出错参数）

  application/json
• 401

  未认证

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for get/sandboxes

Shell Curl

curl 'https://api.rayrunos.com/v1/sandboxes?page=1' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 200 沙箱列表（列表响应包一层对象；分页时 total 为匹配总数）Status: 400 limit / page / label 参数非法（details.field 指向出错参数）Status: 401 未认证Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "sandboxes": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "build_id": null,
      "name": null,
      "labels": {
        "additionalProperty": "string"
      },
      "agent": "string",
      "cpu_cores": 1,
      "memory_mb": 1,
      "workspace_mb": 1,
      "max_lifetime_seconds": null,
      "idle_timeout_seconds": null,
      "idle_action": "pause",
      "budget_cents": null,
      "ip": null,
      "egress": {
        "allow": [
          "string"
        ],
        "deny": [
          "string"
        ],
        "allow_all": false,
        "bandwidth_mbps": 0
      },
      "ingress": [
        {
          "port": 1,
          "visibility": "public",
          "protocol": "http",
          "url": "string"
        }
      ],
      "credentials": [
        "string"
      ],
      "ssh_keys": [
        "string"
      ],
      "remote_desktop": true,
      "desktop_port": 6080,
      "ssh_connect": "string",
      "status": "Creating",
      "agent_state": {
        "state": "idle",
        "class": "success"
      },
      "usage": {
        "vm_hours": 1,
        "egress_bytes": 1,
        "tokens": {
          "input_tokens": 1,
          "output_tokens": 1,
          "cost_usd": null
        }
      },
      "created_at": "2026-11-11T06:00:17.727Z",
      "destroyed_at": null,
      "destroy_reason": null,
      "stopped_reason": null,
      "pricing": {
        "currency": "string",
        "vm_cents_per_hour": 1,
        "egress_cents_per_gb": 1,
        "storage": {
          "cents_per_gib_month": 1,
          "free_bytes": 1
        }
      }
    }
  ],
  "total": 304
}

JSONCopy

JSONCopy

沙箱列表（列表响应包一层对象；分页时 total 为匹配总数）

查询单个沙箱详情

​Copy link

Auth Required

Copy as Markdown

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Responses

• 200

  沙箱详情

  application/json
• 401

  未认证

  application/json
• 404

  沙箱从未创建

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for get/sandboxes/{id}

Shell Curl

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

cURLCopy

cURLCopy

Status: 200 沙箱详情Status: 401 未认证Status: 404 沙箱从未创建Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "build_id": null,
  "name": null,
  "labels": {
    "additionalProperty": "string"
  },
  "agent": "string",
  "cpu_cores": 1,
  "memory_mb": 1,
  "workspace_mb": 1,
  "max_lifetime_seconds": null,
  "idle_timeout_seconds": null,
  "idle_action": "pause",
  "budget_cents": null,
  "ip": null,
  "egress": {
    "allow": [
      "string"
    ],
    "deny": [
      "string"
    ],
    "allow_all": false,
    "bandwidth_mbps": 0
  },
  "ingress": [
    {
      "port": 1,
      "visibility": "public",
      "protocol": "http",
      "url": "string"
    }
  ],
  "credentials": [
    "string"
  ],
  "ssh_keys": [
    "string"
  ],
  "remote_desktop": true,
  "desktop_port": 6080,
  "ssh_connect": "string",
  "status": "Creating",
  "agent_state": {
    "state": "idle",
    "class": "success"
  },
  "usage": {
    "vm_hours": 1,
    "egress_bytes": 1,
    "tokens": {
      "input_tokens": 1,
      "output_tokens": 1,
      "cost_usd": null
    }
  },
  "created_at": "2026-11-11T06:00:17.727Z",
  "destroyed_at": null,
  "destroy_reason": null,
  "stopped_reason": null,
  "pricing": {
    "currency": "string",
    "vm_cents_per_hour": 1,
    "egress_cents_per_gb": 1,
    "storage": {
      "cents_per_gib_month": 1,
      "free_bytes": 1
    }
  }
}

JSONCopy

JSONCopy

沙箱详情

销毁沙箱（同步完成；已 Terminated → 204 幂等，从未存在 → 404）

​Copy link

Auth Required

Copy as Markdown

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Responses

• 204

  Copy link to 204

  已销毁（或已 Terminated 的幂等重删）

• 401

  未认证

  application/json
• 404

  沙箱从未创建

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for delete/sandboxes/{id}

Shell Curl

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

cURLCopy

cURLCopy

Status: 204 已销毁（或已 Terminated 的幂等重删）Status: 401 未认证Status: 404 沙箱从未创建Status: 500 内部错误Status: 503 依赖不可用

No Body

已销毁（或已 Terminated 的幂等重删）

全量替换沙箱标签

​Copy link

Auth Required

Copy as Markdown

labels 全量替换（不是合并）：{} = 清空全部标签。目标态与当前一致时 不写新的审计记录（PUT 幂等）。标签是元数据，不影响运行状态、网络或计费； 已终止的沙箱也允许更新（归档/检索）。并发写为 last-write-wins。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Body·SandboxLabelsUpdate

required

application/json

• labels

  Type: object

  required

  Copy link to labels

  完整标签表（全量替换，不是合并）；{} = 清空全部标签。约束与 创建时一致：最多 16 对；键为 1..63 个字母/数字/_/./-；值非空、 最多 255 字符、不含控制字符。任一不合法 → 400 details.field = labels。

  Properties: 1

Responses

• 200

  更新后的沙箱（labels 为当前完整标签表）

  application/json
• 400

  labels 缺失、非法或 body 不是合法 JSON（details.field 指向出错字段）

  application/json
• 401

  未认证

  application/json
• 404

  沙箱从未创建或不属于当前组织

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for put/sandboxes/{id}/labels

Shell Curl

curl https://api.rayrunos.com/v1/sandboxes/123e4567-e89b-12d3-a456-426614174000/labels \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "labels": {
    "additionalProperty": ""
  }
}'

cURLCopy

cURLCopy

Status: 200 更新后的沙箱（labels 为当前完整标签表）Status: 400 labels 缺失、非法或 body 不是合法 JSON（details.field 指向出错字段）Status: 401 未认证Status: 404 沙箱从未创建或不属于当前组织Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "build_id": null,
  "name": null,
  "labels": {
    "additionalProperty": "string"
  },
  "agent": "string",
  "cpu_cores": 1,
  "memory_mb": 1,
  "workspace_mb": 1,
  "max_lifetime_seconds": null,
  "idle_timeout_seconds": null,
  "idle_action": "pause",
  "budget_cents": null,
  "ip": null,
  "egress": {
    "allow": [
      "string"
    ],
    "deny": [
      "string"
    ],
    "allow_all": false,
    "bandwidth_mbps": 0
  },
  "ingress": [
    {
      "port": 1,
      "visibility": "public",
      "protocol": "http",
      "url": "string"
    }
  ],
  "credentials": [
    "string"
  ],
  "ssh_keys": [
    "string"
  ],
  "remote_desktop": true,
  "desktop_port": 6080,
  "ssh_connect": "string",
  "status": "Creating",
  "agent_state": {
    "state": "idle",
    "class": "success"
  },
  "usage": {
    "vm_hours": 1,
    "egress_bytes": 1,
    "tokens": {
      "input_tokens": 1,
      "output_tokens": 1,
      "cost_usd": null
    }
  },
  "created_at": "2026-11-11T06:00:17.727Z",
  "destroyed_at": null,
  "destroy_reason": null,
  "stopped_reason": null,
  "pricing": {
    "currency": "string",
    "vm_cents_per_hour": 1,
    "egress_cents_per_gb": 1,
    "storage": {
      "cents_per_gib_month": 1,
      "free_bytes": 1
    }
  }
}

JSONCopy

JSONCopy

更新后的沙箱（labels 为当前完整标签表）

重命名沙箱

​Copy link

Auth Required

Copy as Markdown

重命名沙箱。名称是元数据：不影响运行状态、网络或计费；已终止的沙箱也 允许重命名（归档/检索）。同一组织内活跃沙箱名称唯一（重名 → 409 name_conflict）；目标名称与当前一致时返回 200 且不写新的审计记录 （PUT 幂等）。并发写为 last-write-wins。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Body·SandboxNameUpdate

required

application/json

• name

  Type: string

  min length:  

  1

  max length:  

  64

  required

  Copy link to name

  新的沙箱名称。去首尾空白后必须非空、≤64 字符（按 rune）、不含控制 字符；同一组织内活跃沙箱名称唯一（Terminated 释放名字）。不合法 → 400 details.field = name；重名 → 409 name_conflict。

Responses

• 200

  重命名后的沙箱（name 为当前完整名称）

  application/json
• 400

  name 缺失、空白、超过 64 字符或含控制字符（details.field 指向出错字段）；body 不是合法 JSON

  application/json
• 401

  未认证

  application/json
• 404

  沙箱从未创建或不属于当前组织

  application/json
• 409

  同一组织内已有其他活跃沙箱使用该名称（name_conflict）

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for put/sandboxes/{id}/name

Shell Curl

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

cURLCopy

cURLCopy

Status: 200 重命名后的沙箱（name 为当前完整名称）Status: 400 name 缺失、空白、超过 64 字符或含控制字符（details.field 指向出错字段）；body 不是合法 JSONStatus: 401 未认证Status: 404 沙箱从未创建或不属于当前组织Status: 409 同一组织内已有其他活跃沙箱使用该名称（name_conflict）Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "build_id": null,
  "name": null,
  "labels": {
    "additionalProperty": "string"
  },
  "agent": "string",
  "cpu_cores": 1,
  "memory_mb": 1,
  "workspace_mb": 1,
  "max_lifetime_seconds": null,
  "idle_timeout_seconds": null,
  "idle_action": "pause",
  "budget_cents": null,
  "ip": null,
  "egress": {
    "allow": [
      "string"
    ],
    "deny": [
      "string"
    ],
    "allow_all": false,
    "bandwidth_mbps": 0
  },
  "ingress": [
    {
      "port": 1,
      "visibility": "public",
      "protocol": "http",
      "url": "string"
    }
  ],
  "credentials": [
    "string"
  ],
  "ssh_keys": [
    "string"
  ],
  "remote_desktop": true,
  "desktop_port": 6080,
  "ssh_connect": "string",
  "status": "Creating",
  "agent_state": {
    "state": "idle",
    "class": "success"
  },
  "usage": {
    "vm_hours": 1,
    "egress_bytes": 1,
    "tokens": {
      "input_tokens": 1,
      "output_tokens": 1,
      "cost_usd": null
    }
  },
  "created_at": "2026-11-11T06:00:17.727Z",
  "destroyed_at": null,
  "destroy_reason": null,
  "stopped_reason": null,
  "pricing": {
    "currency": "string",
    "vm_cents_per_hour": 1,
    "egress_cents_per_gb": 1,
    "storage": {
      "cents_per_gib_month": 1,
      "free_bytes": 1
    }
  }
}

JSONCopy

JSONCopy

重命名后的沙箱（name 为当前完整名称）

全量替换沙箱出网策略

​Copy link

Auth Required

Copy as Markdown

全量替换运行期出网策略：提交的 allow / deny / allow_all 就是新的生效值 （三个字段都必须显式出现；省略不会保留旧值）。目标态与当前一致时返回 200 且不写新的审计记录（PUT 幂等）。

黑白名单冲突时 allow 优先：同一目标同时命中两边时放行。deny 中的 域名只在 DNS 层拦截（allow_all 下），域名直连 IP、DoH 或缓存可能绕过； deny 中的 IPv4 CIDR 才是网络层边界。allow_all=false 时默认拒绝已覆盖 deny（deny 不改变结果，但仍完整保存）。

与创建不同，运行期更新不会重新并入镜像推荐白名单 —— 否则用户无法 撤销镜像推荐的域名。带宽在创建时固化，运行期不可修改。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Body·SandboxEgressUpdate

required

application/json

• egress

  Type: object

  required

  { allow, allow_all, deny, +1 }Copy link to egress
  Properties: 4

Responses

• 200

  更新后的沙箱（egress 为新的完整策略）

  application/json
• 400

  egress 缺失、条目非法或包含 bandwidth_mbps（details.field 指向出错字段）

  application/json
• 401

  未认证

  application/json
• 404

  沙箱从未创建或不属于当前组织

  application/json
• 409

  当前状态不允许修改（Creating / Terminated）

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for put/sandboxes/{id}/egress

Shell Curl

curl https://api.rayrunos.com/v1/sandboxes/123e4567-e89b-12d3-a456-426614174000/egress \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "egress": {
    "allow": [
      ""
    ],
    "deny": [
      ""
    ],
    "allow_all": true,
    "bandwidth_mbps": 1
  }
}'

cURLCopy

cURLCopy

Status: 200 更新后的沙箱（egress 为新的完整策略）Status: 400 egress 缺失、条目非法或包含 bandwidth_mbps（details.field 指向出错字段）Status: 401 未认证Status: 404 沙箱从未创建或不属于当前组织Status: 409 当前状态不允许修改（Creating / Terminated）Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "build_id": null,
  "name": null,
  "labels": {
    "additionalProperty": "string"
  },
  "agent": "string",
  "cpu_cores": 1,
  "memory_mb": 1,
  "workspace_mb": 1,
  "max_lifetime_seconds": null,
  "idle_timeout_seconds": null,
  "idle_action": "pause",
  "budget_cents": null,
  "ip": null,
  "egress": {
    "allow": [
      "string"
    ],
    "deny": [
      "string"
    ],
    "allow_all": false,
    "bandwidth_mbps": 0
  },
  "ingress": [
    {
      "port": 1,
      "visibility": "public",
      "protocol": "http",
      "url": "string"
    }
  ],
  "credentials": [
    "string"
  ],
  "ssh_keys": [
    "string"
  ],
  "remote_desktop": true,
  "desktop_port": 6080,
  "ssh_connect": "string",
  "status": "Creating",
  "agent_state": {
    "state": "idle",
    "class": "success"
  },
  "usage": {
    "vm_hours": 1,
    "egress_bytes": 1,
    "tokens": {
      "input_tokens": 1,
      "output_tokens": 1,
      "cost_usd": null
    }
  },
  "created_at": "2026-11-11T06:00:17.727Z",
  "destroyed_at": null,
  "destroy_reason": null,
  "stopped_reason": null,
  "pricing": {
    "currency": "string",
    "vm_cents_per_hour": 1,
    "egress_cents_per_gb": 1,
    "storage": {
      "cents_per_gib_month": 1,
      "free_bytes": 1
    }
  }
}

JSONCopy

JSONCopy

更新后的沙箱（egress 为新的完整策略）

冷停沙箱（杀 VM、保留 workspace 与 IP，可再 start）

​Copy link

Auth Required

Copy as Markdown

与 DELETE 的区别是数据留不留：停止保留 workspace.ext4、tap 与 /30 IP，之后可以 start 用同一个工作区盘冷启动。已 Stopped → 204 幂等（不写第二条 journal）。停止期间不计 VM 小时、不消耗寿命。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Responses

• 204

  Copy link to 204

  已停止（本就 Stopped → 幂等无操作）

• 401

  未认证

  application/json
• 404

  沙箱从未存在（not_found）

  application/json
• 409

  状态不允许该操作（sandbox_not_running；如对 Creating/Terminated 调 stop）

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

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

Shell Curl

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

cURLCopy

cURLCopy

Status: 204 已停止（本就 Stopped → 幂等无操作）Status: 401 未认证Status: 404 沙箱从未存在（not_found）Status: 409 状态不允许该操作（sandbox_not_running；如对 Creating/Terminated 调 stop）Status: 500 内部错误Status: 503 依赖不可用

No Body

已停止（本就 Stopped → 幂等无操作）

启动已停止的沙箱

​Copy link

Auth Required

Copy as Markdown

凭证按当前配置重新解析（停止期间换了凭证会生效；删了则 400）。IP 不变 —— 网络在停止时保留。已 Running → 204 幂等。余额不足（欠费停机）时返回 403 insufficient_balance，补足余额后即可恢复。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Responses

• 204

  Copy link to 204

  已启动（本就 Running → 幂等无操作）

• 401

  未认证

  application/json
• 403

  欠费停机（insufficient_balance）；补足余额后即可恢复

  application/json
• 404

  沙箱从未存在（not_found）

  application/json
• 409

  状态不允许该操作（sandbox_not_running；如对 Creating/Terminated 调 stop）

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

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

Shell Curl

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

cURLCopy

cURLCopy

Status: 204 已启动（本就 Running → 幂等无操作）Status: 401 未认证Status: 403 欠费停机（insufficient_balance）；补足余额后即可恢复Status: 404 沙箱从未存在（not_found）Status: 409 状态不允许该操作（sandbox_not_running；如对 Creating/Terminated 调 stop）Status: 500 内部错误Status: 503 依赖不可用

No Body

已启动（本就 Running → 幂等无操作）

暂停沙箱（真挂起，进程与内存保留，resume 7ms）

​Copy link

Auth Required

Copy as Markdown

把 microVM 挂起（PATCH /vm {"state":"Paused"}），进程与打开的文件 全保留；不释放宿主内存。已 Paused → 204 幂等，不写第二条 journal。停止期间不计 VM 小时、不消耗寿命（与 Stopped 同口径）。 配额防线 RAYRUN_MAX_PAUSED_PER_TENANT（默认 4）超限返 409 paused_quota_exhausted。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Responses

• 204

  Copy link to 204

  已暂停（本就 Paused → 幂等无操作）。

  本原生面服从 Rayrun 房规：与 stop 对 Stopped 幂等同型 （app/stop.go:87），重试/双击是常态，204 不写第二条 journal。

• 401

  未认证

  application/json
• 404

  沙箱从未存在（not_found）

  application/json
• 409

  状态不允许该操作（sandbox_not_running）或配额已满 （paused_quota_exhausted：同租户同时暂停数达上限）。

  Paused 状态不在 409 范围 —— 重试/双击是常态，幂等返 204 不写第二条 journal（与 stop 对 Stopped 幂等同型，见 app/stop.go:87 的既有房规）。

  仅下列状态返 409：

  • Creating —— 还在建，没有可挂起的现场
  • Stopped —— 冷停后进程都没了，挂什么（语义拒绝，不是状态不对）
  • Terminated —— 终态不可复活
  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

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

Shell Curl

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

cURLCopy

cURLCopy

Status: 204 已暂停（本就 `Paused` → 幂等无操作）。 本原生面服从 Rayrun 房规：与 `stop` 对 `Stopped` 幂等同型 （`app/stop.go:87`），重试/双击是常态，204 不写第二条 journal。 Status: 401 未认证Status: 404 沙箱从未存在（not_found）Status: 409 状态不允许该操作（`sandbox_not_running`）或配额已满 （`paused_quota_exhausted`：同租户同时暂停数达上限）。 **`Paused` 状态不在 409 范围** —— 重试/双击是常态，幂等返 204 不写第二条 journal（与 `stop` 对 `Stopped` 幂等同型，见 `app/stop.go:87` 的既有房规）。 仅下列状态返 409： - `Creating` —— 还在建，没有可挂起的现场 - `Stopped` —— **冷停后进程都没了**，挂什么（语义拒绝，不是状态不对） - `Terminated` —— 终态不可复活 Status: 500 内部错误Status: 503 依赖不可用

No Body

已暂停（本就 Paused → 幂等无操作）。

本原生面服从 Rayrun 房规：与 stop 对 Stopped 幂等同型 （app/stop.go:87），重试/双击是常态，204 不写第二条 journal。

恢复挂起的沙箱

​Copy link

Auth Required

Copy as Markdown

恢复挂起的 microVM（PATCH /vm {"state":"Resumed"}）。已 Running → 204 幂等，不写第二条 journal。不接 timeout 字段（E2B 面有， 本原生面无）。余额不足（欠费停机）时返回 403 insufficient_balance； 补足余额后即可恢复。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Responses

• 204

  Copy link to 204

  已运行（本就 Running → 幂等无操作）。

  ⚠️ 与 /sandboxes/{id}/pause 的 204 措辞对称 —— 两个端点 对「已在目标态」都是 204 幂等不写第二条 journal（app/pause.go:176-185 与 app/stop.go:166 Start 同型房规）。

• 401

  未认证

  application/json
• 403

  欠费停机（insufficient_balance）；补足余额后即可恢复

  application/json
• 404

  沙箱从未存在（not_found）

  application/json
• 409

  状态不允许该操作（sandbox_not_paused 或 lifetime_exhausted）。

  Running 状态不在 409 范围 —— 重试/双击是常态，幂等返 204 不写第二条 journal（与 pause 对 Paused 幂等同型，见 app/pause.go:176-185 的既有房规）。

  仅下列状态/条件返 409：

  • Creating —— 还在建，没有可恢复的现场
  • Stopped —— 冷停后进程都没了，恢复要走 start（不是 resume）
  • Terminated —— 终态不可复活
  • 本轮已超出 max_lifetime_seconds —— lifetime_exhausted； 先 stop 结束本轮，再 start 开新一轮
  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

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

Shell Curl

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

cURLCopy

cURLCopy

Status: 204 已运行（本就 `Running` → 幂等无操作）。 ⚠️ **与 `/sandboxes/{id}/pause` 的 204 措辞对称** —— 两个端点 对「已在目标态」都是 204 幂等不写第二条 journal（`app/pause.go:176-185` 与 `app/stop.go:166` `Start` 同型房规）。 Status: 401 未认证Status: 403 欠费停机（insufficient_balance）；补足余额后即可恢复Status: 404 沙箱从未存在（not_found）Status: 409 状态不允许该操作（`sandbox_not_paused` 或 `lifetime_exhausted`）。 **`Running` 状态不在 409 范围** —— 重试/双击是常态，幂等返 204 不写第二条 journal（与 `pause` 对 `Paused` 幂等同型，见 `app/pause.go:176-185` 的既有房规）。 仅下列状态/条件返 409： - `Creating` —— 还在建，没有可恢复的现场 - `Stopped` —— 冷停后进程都没了，恢复要走 `start`（**不是 resume**） - `Terminated` —— 终态不可复活 - 本轮已超出 `max_lifetime_seconds` —— `lifetime_exhausted`； 先 `stop` 结束本轮，再 `start` 开新一轮 Status: 500 内部错误Status: 503 依赖不可用

No Body

已运行（本就 Running → 幂等无操作）。

⚠️ 与 /sandboxes/{id}/pause 的 204 措辞对称 —— 两个端点 对「已在目标态」都是 204 幂等不写第二条 journal（app/pause.go:176-185 与 app/stop.go:166 Start 同型房规）。

沙箱日志（纯文本，增量轮询）

​Copy link

Auth Required

Copy as Markdown

返回沙箱的串口日志（text/plain）：沙箱内系统日志、内核控制台输出与 服务写入控制台的输出。日志带 X-Next-Offset 响应头：客户端下一次 带上 ?offset=<该值> 取增量。单次最多 256 KiB。

单轮日志有保留上限（32 MiB），超出后较早的部分会被逐出：

• 首次请求省略 offset = 返回最新一段；
• 若带上的 offset 已落在被逐出区间（或来自另一轮运行），响应带 X-Log-Reset: 1，正文是最新一段，客户端应替换本地缓冲；
• X-Log-Truncated: 1 表示文件曾超过上限，当前只能看到尾部；
• X-Log-Has-Previous: 1 表示存在「停止」时归档的上一轮日志。

offset 只在同一轮运行内有效：沙箱停止再启动后，新一轮从 0 开始。

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Query Parameters

• round

  Type: "current" or "previous"enum

  Default

  current

  Copy link to round

  读取哪一轮：current = 本轮运行；previous = 停止时归档的上一轮 （只在沙箱停止过之后存在）。

• offset

  Type: integerFormat: int64

  min:  

  0Copy link to offset

  起始字节偏移；省略 = 返回最新一段

Responses

• 200

  日志片段（该轮还没有日志时返回空串，不是 404）

  text/plain
• 400

  参数非法（offset / round）

  application/json
• 401

  未认证

  application/json
• 404

  沙箱不存在（not_found）

  application/json

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

Shell Curl

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

cURLCopy

cURLCopy

Status: 200 日志片段（该轮还没有日志时返回空串，不是 404）Status: 400 参数非法（offset / round）Status: 401 未认证Status: 404 沙箱不存在（not_found）

Show Schema

string

Copy

Copy

日志片段（该轮还没有日志时返回空串，不是 404）

Models

Show More