跳转到内容
SeaCloud 文档
返回主页

沙箱模板

模板定义沙箱启动时使用的镜像、资源、环境变量、启动行为和就绪检查。

首次接入优先使用官方模板。生产流量前，应固定具体模板 ID 或已推广标签。

什么时候固定或申请模板

Section titled “什么时候固定或申请模板”

以下情况适合从通用官方别名迁移到具体模板：

  • 依赖只安装一次，而不是每次沙箱启动都安装
  • 复用源码或预构建应用资产
  • 固定 OS 包和语言包版本
  • 定义启动行为和就绪检查
  • 通过具体 tpl-... ID 或标签固定已验证的运行时行为

官方模板选择

Section titled “官方模板选择”
目标建议起点
Shell 命令和文件操作base
代码解释器和数据分析code-interpreter 或 code-interpreter-lite
Node 前端或 API 服务node 或 web-frontend
Python 服务或脚本python
浏览器自动化browser
Coding Agentcodex、claude、opencode、openclaw、amp 或 openai-agents
API、MCP、爬取或 DevOps 任务api-server、mcp-server、scraper 或 devops
生产可复现具体 tpl-...

公开官方模板

Section titled “公开官方模板”

公开文档暴露以下 official template type。不同环境的可用模板可能不同，生产固定前应先在目标环境列出模板。API 返回但未出现在本表中的模板应视为环境专用或内部模板，不建议在公开集成中引用。

分类Official type典型 CPU / memory适用场景
基础运行时base1 / 1024MB通用 shell 命令、文件 API、PTY、git 操作和轻量服务。
语言运行时node2 / 2048MBNode.js 脚本、包安装、API 服务，以及 JavaScript/TypeScript 构建或测试任务。
语言运行时python2 / 2048MBPython 脚本、小型服务、数据预处理、依赖检查和测试任务。
语言运行时go2 / 4096MBGo 构建、测试、CLI 和服务工作流，需要预置 Go 工具链时使用。
Web 应用web-frontend2 / 4096MB前端预览、Vite/Next 类开发服务，以及可在浏览器打开的 Web 应用。
代码执行code-interpreter2 / 4096MB多语言 runCode、数据分析、生成代码执行和产物生成。
代码执行code-interpreter-lite2 / 2048MB更轻量的代码执行任务，适合更关注启动成本和较小资源占用的场景。
浏览器与桌面browser2 / 4096MB浏览器自动化、网页检查、截图和需要浏览器依赖的 UI 流程。
浏览器与桌面desktop4 / 8192MBComputer Use 类任务、GUI 工具和更重的交互式桌面流程。
Agent 运行时codex2 / 4096MBCodex 类 Coding Agent，需要预置命令、文件和开发环境。
Agent 运行时claude4 / 8192MBClaude Coding Agent 工作流，需要更高内存余量时使用。
Agent 运行时opencode2 / 4096MBOpenCode 类 Coding Agent 和仓库自动化。
Agent 运行时openclaw4 / 8192MB更重的 OpenClaw Agent 工作流。
Agent 运行时amp2 / 4096MBAMP 类编码或自动化 Agent。
Agent 运行时openai-agents2 / 4096MB基于 OpenAI Agents SDK 或 Agent 工具编排的工作流。
服务运行时api-server2 / 2048MB小型 HTTP API、回调服务和需要暴露端口的服务原型。
服务运行时mcp-server2 / 2048MBMCP Server 开发、工具服务和 Agent 集成端点。
自动化运行时scraper2 / 2048MB爬取、抽取和内容采集任务，需要预置自动化栈时使用。
自动化运行时devops2 / 2048MBShell 较重的自动化、部署检查、基础设施脚本和运维探针。

列出和使用模板

Section titled “列出和使用模板”
GET /api/v1/templates?visibility=official&limit=200
X-API-Key: <token>

创建沙箱时可以使用返回的 templateID、别名或已推广标签：

const sandbox = await Sandbox.create("base", {
  waitReady: true,
  timeout: 1800,
});

官方别名可能随模板修复而移动。生产工作负载建议使用具体 tpl-... ID 或显式推广的标签。

自定义模板构建

Section titled “自定义模板构建”

具备模板构建权限的项目，可以使用 CLI 或模板 API 从 Dockerfile、已有镜像或已有模板构建可复用模板：

Terminal window
seacloud template build my-template --dockerfile Dockerfile --cpu-count 2 --memory-mb 2048 --tag v1
seacloud template status <template_id> <build_id>
seacloud template logs <template_id> <build_id> --limit 100

构建 ready 后，可以使用返回的 templateID、模板名称或已推广标签创建沙箱。若当前账号没有构建权限，应使用公开官方模板或申请平台准备模板。构建状态和日志分别通过 /api/v1/templates/:templateID/builds/:buildID/status 和 /api/v1/templates/:templateID/builds/:buildID/logs 暴露。

运行时模式

Section titled “运行时模式”
Mode含义
managed运行时 API 可在运行时端口访问，通常是 9000。
plain镜像自己拥有前台应用进程；平台健康检查仍可运行。

workdir 控制默认进程和文件根目录。生产模板应显式设置 workdir，避免命令、文件 API 和应用启动目录不一致。

startCmd 与 readyCmd

Section titled “startCmd 与 readyCmd”

使用 startCmd 为未来从该模板创建的沙箱启动长运行应用进程。使用 readyCmd 判断沙箱是否已经可用。

好的就绪检查应该是本地、有限时长，并且和用户会打开的端口一致：

Terminal window
wget -q -O- http://127.0.0.1:3000/ >/dev/null

避免只证明进程存在、但不能证明应用可用的检查：

Terminal window
ps aux | grep node

startCmd 和 readyCmd 使用 shell 语义。镜像应包含 /bin/sh，或命令应按该镜像可用的 shell 编写。

模式建议
HTTP 应用startCmd 启动服务；readyCmd curl 本地应用端口。
后台 WorkerreadyCmd 检查健康文件、PID、队列连接或 worker 心跳。
前端预览绑定 0.0.0.0；readyCmd 检查 127.0.0.1:<port>；用户打开 getHost(port)。
重依赖安装把安装步骤放入构建 RUN，不要放在沙箱启动阶段。

常见模板问题

Section titled “常见模板问题”
现象检查项
沙箱一直无法进入 running检查运行时模式、镜像 entrypoint、就绪端口和健康检查配置。
沙箱启动但预览返回 502startCmd 退出、端口错误，或应用只绑定 localhost。
readyCmd 超时沙箱内部目标 localhost 端口没有响应。