SeaCloud Sandbox 概览

SeaCloud Sandbox 可以从模板创建短生命周期的隔离 Linux 运行时。适用于需要运行代码、编辑文件、安装依赖、启动预览服务或执行非可信自动化任务的产品场景。

公开 SDK 连接 SeaCloud Sandbox API。SeaCloud 负责创建和管理沙箱，并返回沙箱级运行时访问能力，用于文件、命令、PTY、代码执行、指标和端口预览。

选择你的路径

运行第一个沙箱 适合首次接入。安装 SDK、创建沙箱、执行命令并删除。

从 E2B 迁移 适合已有沙箱用户。对比包名、环境变量、方法、超时单位和应用 URL。

使用可复用环境 适合生产工作负载。选择官方模板、固定稳定 ID，并理解启动检查。

调试集成 适合 API 级接入。查询路由、鉴权、日志、指标、错误和可观测性接口。

工作原理

你的后端 / Agent runner
  -> SeaCloud Sandbox API
    -> 基于模板创建或重连沙箱
      -> 模板镜像在隔离运行时中启动
        -> SDK 使用沙箱运行时凭据访问文件、命令、指标和端口

请把公开 SDK 返回的 sandbox 对象作为运行时边界。不要在 create/detail/connect 响应流程之外缓存运行时 URL 或运行时 Token。

核心能力

能力	说明
隔离执行	每个沙箱拥有独立运行边界、文件系统、进程树和生命周期超时。
快速创建与重连	从官方模板创建，等待就绪，通过 Sandbox ID 重连，刷新 TTL、暂停或删除。
文件与命令	读写文件、列目录、执行前台命令、启动后台服务。
公网预览	服务绑定到 0.0.0.0 后，通过 https://sandbox-router.cloud.seaart.ai/{port}-{sandboxID}/ 访问。
模板	选择官方模板族，并在生产环境固定具体 tpl-... 或已推广标签。
多语言 SDK	Node、Python、Go SDK 提供一致的生命周期、文件、命令、模板和代码解释器流程。
资源模型	保留基线资源，并支持尽力型 CPU 突发：配置的 CPU 和内存会被完整保留；底层宿主机有空闲 CPU 时，运行中沙箱可在不额外收费的情况下机会性突发。

公开组成

组成	职责
Sandbox API	公开 API 入口、API Key 鉴权、路由和请求上下文。
生命周期管理	创建、查询、重连、暂停、刷新、超时、日志和删除。
运行时访问	文件、进程、PTY、指标、健康检查和公网端口路由。

首个工作流怎么选

目标	推荐第一步
验证基础命令执行	创建 base，写入文件，执行 sh，删除沙箱。
执行生成代码或数据分析	创建 code-interpreter，使用 runCode，读取生成产物。
预览 Web 应用	创建 node 或 web-frontend，绑定 0.0.0.0，打开 getHost(3000)。
运行 Coding Agent	从 codex、claude、opencode 或 base 开始，再固定具体模板。
需要稳定生产环境	固定具体 tpl-... ID 或已推广标签，并确认模板镜像、资源和启动行为。

系统默认契约

项目	当前契约
API Base URL	https://sandbox-service.real-cloud.seaart.ai/api/v1/sandbox
API 鉴权	X-API-Key: <SEACLOUD_API_KEY>
运行时鉴权	创建、查询或重连返回的 X-Access-Token: <envdAccessToken>
首选模板	Shell/文件用 base，runCode 用 code-interpreter
起步资源规格	官方起步模板通常从 1 vCPU / 1024MB 开始；语言、浏览器、桌面和 Agent 模板会保留更多资源。
示例工作目录	/root/workspace
沙箱超时单位	秒
运行时命令超时单位	毫秒
应用预览 URL	https://sandbox-router.cloud.seaart.ai/{port}-{sandboxID}/
计费基础	running 时按配置 vCPU 和内存计费；存储仅在 paused 时计费；数据流量按实际入站/出站计费。

官方模板族

模板族	使用场景
base	通用 shell、文件、git、PTY、指标和轻量服务。
node、python、go、web-frontend	语言相关应用、预览、构建任务和测试。
code-interpreter、code-interpreter-lite	多语言代码执行、数据分析和生成产物。
browser、desktop	浏览器自动化、截图和 Computer Use 类工作负载。
codex、claude、opencode、openclaw、amp、openai-agents	Coding Agent 和 Agent 编排运行时。
api-server、mcp-server、scraper、devops	服务原型、MCP 工具、爬取和运维自动化。
具体 tpl-...	需要稳定镜像和存储行为的生产工作负载。

完整公开模板清单、典型资源规格和适用场景见沙箱模板。生产固定模板前，应先在目标环境列出模板，并优先使用具体 tpl-... ID 或标签。

生产就绪检查

从评估进入生产前，请确认：

1. 工作负载使用具体 tpl-... ID 或已推广标签，而不是会移动的官方别名。
2. 用户可见应用服务绑定 0.0.0.0，并暴露文档中约定的端口。
3. 沙箱生命周期 timeout 和单命令 timeoutMs 都已显式设置。
4. 支持流程中已采集日志、指标、timeline、diagnostic 和 requestID。
5. API Key 和 envdAccessToken 不会进入浏览器代码、模型 Prompt 或用户可见日志。

文档导航

快速开始 创建沙箱、写入文件、执行命令并清理资源。

使用场景 为 Agent、代码解释器、CI 和预览选择合适流程。

生命周期 创建、重连、暂停、刷新、超时和删除沙箱。

模板 选择官方模板并固定可复用沙箱环境。

API Reference 使用原始 HTTP 路由操作生命周期、运行时、模板和用量接口。