Skip to content

docs(specs): update README for current specs #71

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hittyt merged 1 commit into from
Jan 6, 2026
Merged

docs(specs): update README for current specs #71

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 32 additions & 27 deletions specs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,34 @@

English | [中文](README_zh.md)

This directory contains OpenAPI specification documents for the OpenSandbox project, defining the complete API interfaces and data models.
This directory contains OpenAPI specification documents for the OpenSandbox project, defining the complete API interfaces and data models. Use the server base URLs defined in each spec (for example, `http://localhost:8080/v1` for the lifecycle API and `http://localhost:8080` for execd) when constructing requests.

## Specification Files

### 1. sandbox-lifecycle.yml

**Sandbox Lifecycle Management API**

Defines the complete lifecycle interfaces for creating, managing, and destroying sandbox environments.
Defines the complete lifecycle interfaces for creating, managing, and destroying sandbox environments directly from container images.

**Core Features:**
- **Sandbox Management**: Create, list, query, and delete sandbox instances
- **Sandbox Management**: Create, list, query, and delete sandbox instances with metadata filters and pagination
- **State Control**: Pause and resume sandbox execution
- **Lifecycle States**: Support multiple state transitions (Pending → Running → Pausing → Paused → Stopping → Terminated)
- **Resource Configuration**: CPU, memory, GPU, and other resource limit configurations
- **Image Support**: Create sandboxes directly from container images, supporting both public and private registries
- **Timeout Management**: Automatic expiration and manual renewal capabilities
- **Lifecycle States**: Supports transitions across Pending → Running → Pausing → Paused → Stopping → Terminated, and error handling with `Failed`
- **Resource & Runtime Configuration**: Specify CPU/memory/GPU resource limits, required `entrypoint`, environment variables, and opaque `extensions`
- **Image Support**: Create sandboxes from public or private registries, including registry auth
- **Timeout Management**: Mandatory `timeout` on creation with explicit renewal via API
- **Endpoint Access**: Retrieve public access endpoints for services running inside sandboxes

**Main Endpoints:**
- `POST /v1/sandboxes` - Create sandbox
- `GET /v1/sandboxes` - List sandboxes (with filtering and pagination)
- `GET /v1/sandboxes/{sandboxId}` - Get sandbox details
- `DELETE /v1/sandboxes/{sandboxId}` - Delete sandbox
- `POST /v1/sandboxes/{sandboxId}/pause` - Pause sandbox
- `POST /v1/sandboxes/{sandboxId}/resume` - Resume sandbox
- `POST /v1/sandboxes/{sandboxId}/renew-expiration` - Renew sandbox expiration
- `GET /v1/sandboxes/{sandboxId}/endpoints/{port}` - Get access endpoint
**Main Endpoints (base path `/v1`):**
- `POST /sandboxes` - Create a sandbox from an image with timeout and resource limits
- `GET /sandboxes` - List sandboxes with state/metadata filters and pagination
- `GET /sandboxes/{sandboxId}` - Get full sandbox details (including image and entrypoint)
- `DELETE /sandboxes/{sandboxId}` - Delete a sandbox
- `POST /sandboxes/{sandboxId}/pause` - Pause a sandbox (asynchronous)
- `POST /sandboxes/{sandboxId}/resume` - Resume a paused sandbox
- `POST /sandboxes/{sandboxId}/renew-expiration` - Renew sandbox expiration (TTL)
- `GET /sandboxes/{sandboxId}/endpoints/{port}` - Get an access endpoint for a service port

**Authentication:**
- HTTP Header: `OPEN-SANDBOX-API-KEY: your-api-key`
Expand All @@ -39,43 +39,48 @@ Defines the complete lifecycle interfaces for creating, managing, and destroying

**Code Execution API Inside Sandbox**

Defines interfaces for executing code, commands, and file operations within sandbox environments, providing complete code interpreter and filesystem management capabilities.
Defines interfaces for executing code, commands, and file operations within sandbox environments, providing complete code interpreter and filesystem management capabilities. All endpoints require the `X-EXECD-ACCESS-TOKEN` header.

**Core Features:**
- **Code Execution**: Stateful code execution supporting Python, JavaScript, and other languages
- **Command Execution**: Shell command execution with foreground/background modes
- **Code Execution**: Stateful code execution supporting Python, JavaScript, and other languages with context lifecycle management
- **Command Execution**: Shell command execution with foreground/background modes and polling endpoints for status/output
- **File Operations**: Complete CRUD operations for files and directories
- **Real-time Streaming**: Real-time output streaming via SSE (Server-Sent Events)
- **System Monitoring**: Real-time monitoring of CPU and memory metrics
- **Access Control**: Token-based API authentication
- **Access Control**: Token-based API authentication via `X-EXECD-ACCESS-TOKEN`

**Main Endpoint Categories:**

**Health Check:**
- `GET /ping` - Service health check

**Code Interpreter:**
- `POST /code/context` - Create code execution context
- `POST /code` - Execute code in context (streaming output)
- `GET /code/contexts` - List active code execution contexts (filterable by language)
- `DELETE /code/contexts` - Delete all contexts for a language
- `DELETE /code/contexts/{context_id}` - Delete a specific context
- `POST /code/context` - Create a code execution context
- `POST /code` - Execute code in a context (streaming output)
- `DELETE /code` - Interrupt code execution

**Command Execution:**
- `POST /command` - Execute shell command (streaming output)
- `DELETE /command` - Interrupt command execution
- `GET /command/status/{session}` - Get foreground/background command status
- `GET /command/output/{session}` - Fetch accumulated stdout/stderr for a command

**Filesystem:**
- `GET /files/info` - Get file metadata
- `DELETE /files` - Delete files
- `GET /files/info` - Get metadata for files
- `DELETE /files` - Delete files (not directories)
- `POST /files/permissions` - Change file permissions
- `POST /files/mv` - Move/rename files
- `GET /files/search` - Search files (supports glob patterns)
- `POST /files/replace` - Batch replace file content
- `POST /files/upload` - Upload files
- `POST /files/upload` - Upload files (multipart)
- `GET /files/download` - Download files (supports range requests)

**Directory Operations:**
- `POST /directories` - Create directories
- `DELETE /directories` - Delete directories
- `POST /directories` - Create directories with permissions (mkdir -p semantics)
- `DELETE /directories` - Recursively delete directories

**System Metrics:**
- `GET /metrics` - Get system resource metrics
Expand Down
53 changes: 29 additions & 24 deletions specs/README_zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,34 @@

中文 | [English](README.md)

本目录包含 OpenSandbox 项目的 OpenAPI 规范文档，定义了完整的 API 接口和数据模型。
本目录包含 OpenSandbox 项目的 OpenAPI 规范文档，定义了完整的 API 接口和数据模型。发起请求时请使用各规范中定义的服务器地址（例如生命周期 API 的 `http://localhost:8080/v1`，execd 的 `http://localhost:8080`）。

## 规范文件

### 1. sandbox-lifecycle.yml

**沙箱生命周期管理 API**

定义了沙箱环境的创建、管理和销毁的完整生命周期接口。
定义了沙箱环境的创建、管理和销毁的完整生命周期接口，并可直接从容器镜像启动。

**核心功能：**
- **沙箱管理**：创建、列表、查询、删除沙箱实例
- **沙箱管理**：创建、列表、查询、删除沙箱实例，支持元数据过滤与分页
- **状态控制**：暂停 (Pause)、恢复 (Resume) 沙箱执行
- **生命周期**：支持多种状态转换（Pending → Running → Pausing → Paused → Stopping → Terminated）
- **资源配置**：CPU、内存、GPU 等资源限制配置
- **镜像支持**：从容器镜像直接创建沙箱，支持公共和私有镜像仓库
- **超时管理**：自动过期和手动续期功能
- **生命周期**：支持 Pending → Running → Pausing → Paused → Stopping → Terminated，并包含错误态 `Failed`
- **资源与运行时配置**：指定 CPU/内存/GPU 资源限制、必填 `entrypoint`、环境变量，以及自定义 `extensions`
- **镜像支持**：从公共或私有镜像仓库创建沙箱，支持私有仓库认证
- **超时管理**：创建时必填 `timeout`，并可通过 API 续期
- **端点访问**：获取沙箱内服务的公共访问端点

**主要端点：**
- `POST /v1/sandboxes` - 创建沙箱
- `GET /v1/sandboxes` - 列出沙箱（支持过滤和分页）
- `GET /v1/sandboxes/{sandboxId}` - 获取沙箱详情
- `DELETE /v1/sandboxes/{sandboxId}` - 删除沙箱
- `POST /v1/sandboxes/{sandboxId}/pause` - 暂停沙箱
- `POST /v1/sandboxes/{sandboxId}/resume` - 恢复沙箱
- `POST /v1/sandboxes/{sandboxId}/renew-expiration` - 续期沙箱
- `GET /v1/sandboxes/{sandboxId}/endpoints/{port}` - 获取访问端点
**主要端点（基础路径 `/v1`）：**
- `POST /sandboxes` - 从镜像创建沙箱，设置超时与资源限制
- `GET /sandboxes` - 列出沙箱，支持状态/元数据过滤与分页
- `GET /sandboxes/{sandboxId}` - 获取完整沙箱详情（包含镜像与 entrypoint）
- `DELETE /sandboxes/{sandboxId}` - 删除沙箱
- `POST /sandboxes/{sandboxId}/pause` - 异步暂停沙箱
- `POST /sandboxes/{sandboxId}/resume` - 恢复已暂停的沙箱
- `POST /sandboxes/{sandboxId}/renew-expiration` - 续期沙箱 TTL
- `GET /sandboxes/{sandboxId}/endpoints/{port}` - 获取指定端口的访问端点

**认证方式：**
- HTTP Header: `OPEN-SANDBOX-API-KEY: your-api-key`
Expand All @@ -39,43 +39,48 @@

**沙箱内代码执行 API**

定义了在沙箱环境内执行代码、命令和文件操作的接口，提供完整的代码解释器和文件系统管理能力。
定义了在沙箱环境内执行代码、命令和文件操作的接口，提供完整的代码解释器和文件系统管理能力。所有端点需要 `X-EXECD-ACCESS-TOKEN` 认证头。

**核心功能：**
- **代码执行**：支持 Python、JavaScript 等多语言的有状态代码执行
- **命令执行**：Shell 命令执行，支持前台/后台模式
- **代码执行**：支持 Python、JavaScript 等多语言的有状态代码执行，并提供上下文生命周期管理
- **命令执行**：Shell 命令执行，支持前台/后台模式，并可通过轮询端点查看状态和输出
- **文件操作**：完整的文件和目录 CRUD 操作（创建、读取、更新、删除）
- **实时流式输出**：基于 SSE (Server-Sent Events) 的实时输出流
- **系统监控**：CPU 和内存指标的实时监控
- **访问控制**：基于 Token 的 API 认证
- **访问控制**：通过 `X-EXECD-ACCESS-TOKEN` 进行 Token 认证

**主要端点分类：**

**健康检查：**
- `GET /ping` - 服务健康检查

**代码解释器：**
- `GET /code/contexts` - 列出活跃的代码执行上下文（可按语言过滤）
- `DELETE /code/contexts` - 按语言批量删除上下文
- `DELETE /code/contexts/{context_id}` - 删除指定上下文
- `POST /code/context` - 创建代码执行上下文
- `POST /code` - 在上下文中执行代码（流式输出）
- `DELETE /code` - 中断代码执行

**命令执行：**
- `POST /command` - 执行 Shell 命令（流式输出）
- `DELETE /command` - 中断命令执行
- `GET /command/status/{session}` - 查询前台/后台命令状态
- `GET /command/output/{session}` - 获取命令的累积 stdout/stderr

**文件系统：**
- `GET /files/info` - 获取文件元数据
- `DELETE /files` - 删除文件
- `DELETE /files` - 删除文件（不包含目录）
- `POST /files/permissions` - 修改文件权限
- `POST /files/mv` - 移动/重命名文件
- `GET /files/search` - 搜索文件（支持 glob 模式）
- `POST /files/replace` - 批量替换文件内容
- `POST /files/upload` - 上传文件
- `POST /files/upload` - 上传文件（multipart）
- `GET /files/download` - 下载文件（支持断点续传）

**目录操作：**
- `POST /directories` - 创建目录
- `DELETE /directories` - 删除目录
- `POST /directories` - 按权限配置创建目录（mkdir -p 语义）
- `DELETE /directories` - 递归删除目录

**系统指标：**
- `GET /metrics` - 获取系统资源指标
Expand Down