SeaCloud Sandbox Use Cases

SeaCloud Sandbox is useful whenever a product needs isolated compute with a clear lifecycle. Start from an official template for the first version, then pin a concrete official template or promoted tpl-... when the workflow becomes stable.

Common Workloads

Workload	Typical template	Main APIs
Coding agents	codex, claude, opencode, openai-agents, or base	Files, commands, git, PTY, lifecycle, public previews
Code interpreter	code-interpreter	runCode, files, commands, artifacts
Web automation and previews	browser, node, web-frontend, or code-interpreter	Commands, public ports, files
CI/CD evaluation	node, python, go, or concrete tpl-...	Commands, logs, artifacts, timeout control

Coding Agents

Use sandboxes to isolate repository edits, installs, test runs, generated code, and preview servers. The orchestrator can clone a repo, run package manager commands, inspect git diff, and delete the sandbox when the task is done.

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

Use code-interpreter when a product needs notebook-like execution, data analysis, chart generation, or artifacts from generated Python/JS/Bash/R/Java code.

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);

Code execution returns structured results, captured logs.stdout, captured logs.stderr, optional error, and a convenience text getter. Python contexts can preserve variables and imports across calls; other languages typically use contexts as reusable execution profiles.

Web Automation And Preview

Start a browser or web app inside the sandbox, bind the process to 0.0.0.0, then open the public port URL. Use this for frontend previews, screenshot services, browser checks, and temporary demo apps.

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 And Script Evaluation

Sandboxes are a practical boundary for evaluating pull requests, scripts, model-generated commands, and dependency-heavy jobs. Keep sandbox lifecycle timeout large enough for the job, but keep each command timeoutMs bounded so a single process cannot block the entire run.

Production Pattern

1. Pick an official template for the first end-to-end workflow.
2. Verify files, commands, ports, and cleanup with one sandbox.
3. Pin production workloads to a concrete official tpl-... ID or promoted tag.
4. Request a prepared template when repeated dependencies or startup commands are required.