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 move repeated setup into a custom template 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 custom tpl-...	Commands, logs, artifacts, timeout control
Persistent workspaces	nfs, cloud, block, or custom tpl-...	Files, pause/connect, mounted storage

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.

Persistent Workspaces

Use persistent templates when files must survive pause/resume or recreation:

Template	Typical behavior
nfs	Shared NFS-backed workspace path.
cloud	Object-storage sync through cloudsink/nano-daemon.
block	PVC/block-backed isolated volume.
cloud-drive	PVC-backed cloud-drive style mount, environment-dependent.

Always write durable data under a path declared in template volumeMounts. workdir is only the default directory; it does not make a path persistent.

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. Build a custom template for repeated dependencies and startup commands.
4. Pin production workloads to a concrete tpl-... ID or tag.
5. Choose persistent storage before promising resumable user workspaces.