SeaCloud Sandbox 使用场景

SeaCloud Sandbox 适合任何需要隔离计算和明确生命周期的产品场景。第一版优先使用官方模板，流程稳定后再把重复安装和启动逻辑沉淀为自定义模板。

常见工作负载

工作负载	常用模板	主要 API
Coding Agents	codex、claude、opencode、openai-agents 或 base	文件、命令、git、PTY、生命周期、公网预览
Code Interpreter	code-interpreter	runCode、文件、命令、产物
Web 自动化与预览	browser、node、web-frontend 或 code-interpreter	命令、公网端口、文件
CI/CD 评估	node、python、go 或自定义 tpl-...	命令、日志、产物、超时控制
持久工作区	nfs、cloud、block 或自定义 tpl-...	文件、暂停/重连、挂载存储

Coding Agents

沙箱可以隔离仓库编辑、依赖安装、测试执行、代码生成和预览服务。编排方可以克隆仓库、运行包管理命令、检查 git diff，任务结束后删除沙箱。

import { Sandbox } from "@seacloudai/sandbox";

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

try {
  await sandbox.commands.run("git", {
    args: ["clone", "https://github.com/example/repo.git", "/root/workspace/repo"],
    timeoutMs: 120_000,
  });

  await sandbox.commands.run("sh", {
    cwd: "/root/workspace/repo",
    args: ["-lc", "npm install && npm test"],
    timeoutMs: 600_000,
  });

  const diff = await sandbox.commands.run("sh", {
    cwd: "/root/workspace/repo",
    args: ["-lc", "git diff -- ."],
  });

  console.log(diff.stdout);
} finally {
  await sandbox.delete();
}

Code Interpreter

当产品需要 notebook 式执行、数据分析、图表生成，或从 Python/JS/Bash/R/Java 代码生成产物时，使用 code-interpreter。

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

await sandbox.files.write("/root/workspace/input.csv", "name,value\na,1\nb,2\n");

const result = await sandbox.runCode(`
import pandas as pd
df = pd.read_csv("/root/workspace/input.csv")
df["double"] = df["value"] * 2
df.to_csv("/root/workspace/output.csv", index=False)
df
`);

console.log(result.text);

代码执行会返回结构化 results、捕获的 logs.stdout、捕获的 logs.stderr、可选 error，以及便捷的 text getter。Python context 可以跨调用保留变量和 import；其他语言通常把 context 作为可复用执行 profile。

Web 自动化与预览

在沙箱内启动浏览器或 Web 应用，把服务绑定到 0.0.0.0，然后打开公网端口 URL。适用于前端预览、截图服务、浏览器检查和临时演示应用。

await sandbox.commands.run("python3", {
  args: ["-m", "http.server", "3000", "--bind", "0.0.0.0", "--directory", "/root/workspace/site"],
  background: true,
});

console.log(sandbox.getHost(3000));

CI/CD 与脚本评估

沙箱可作为 PR 校验、脚本执行、模型生成命令和依赖较重任务的隔离边界。沙箱生命周期 timeout 要覆盖作业总时长，每个命令的 timeoutMs 仍应保持有限，避免单个进程卡住整轮执行。

持久工作区

文件需要在 pause/resume 或重新创建后保留时，使用持久模板：

模板	典型行为
nfs	共享 NFS 后端工作区路径。
cloud	通过 cloudsink/nano-daemon 同步对象存储。
block	PVC/block 后端独立卷。
cloud-drive	PVC 后端 cloud-drive 式挂载，依赖环境。

所有持久数据都应写入模板 volumeMounts 声明的路径。workdir 只是默认目录，不会让路径持久化。

生产接入模式

1. 用官方模板跑通第一个端到端流程。
2. 验证文件、命令、端口和清理流程。
3. 将重复依赖和启动命令构建为自定义模板。
4. 生产环境固定到具体 tpl-... ID 或发布标签。
5. 承诺可恢复用户工作区前，先确认持久存储策略。