SeaCloud Sandbox Overview

SeaCloud Sandbox creates short-lived isolated Linux runtimes from templates. Use it when an application or agent needs to run code, edit files, install dependencies, start preview servers, or execute untrusted automation without touching the host machine.

The public SDKs talk to the SeaCloud Sandbox API. SeaCloud creates and manages sandboxes, then returns sandbox-scoped runtime access for files, commands, PTY, code execution, metrics, and port previews.

Choose Your Path

Run the first sandbox Best for first-time setup. Install an SDK, create a sandbox, run one command, and delete it.

Move from E2B Best for existing sandbox users. Compare packages, env vars, methods, timeout units, and app URLs.

Use reusable environments Best for production workloads. Choose official templates, pin stable IDs, and understand startup checks.

Debug an integration Best for API-level work. Find routes, auth headers, logs, metrics, errors, and observability endpoints.

How It Works

Your backend / agent runner
  -> SeaCloud Sandbox API
    -> Sandbox is created or reconnected from a template
      -> Template image starts inside an isolated runtime
        -> SDK uses sandbox runtime credentials for files, commands, metrics, and ports

Use the public SDK object as the boundary. Do not cache runtime URLs or runtime tokens outside the create/detail/connect response flow.

Core Capabilities

Capability	What it gives you
Isolated execution	Each sandbox has its own runtime boundary, filesystem, process tree, and lifecycle timeout.
Fast create/connect loop	Create from official templates, wait for readiness, reconnect by sandbox ID, refresh TTL, pause, or delete.
Files and commands	Read/write files, list directories, run foreground commands, and start background services.
Public previews	Open apps with https://sandbox-router.cloud.seaart.ai/{port}-{sandboxID}/ after binding the service to 0.0.0.0.
Templates	Select official template families and pin a concrete tpl-... or promoted tag for production.
Multi-language SDKs	Node, Python, and Go SDKs expose aligned lifecycle, file, command, template, and code-interpreter flows.
Resource model	Reserved baseline, plus best-effort burst: configured CPU and memory are reserved, while spare host CPU may be used opportunistically at no extra cost.

Public Building Blocks

Block	Responsibility
Sandbox API	Public API entrypoint, API key auth, routing, and request context.
Lifecycle management	Create, inspect, connect, pause, refresh, timeout, logs, and delete.
Runtime access	Files, processes, PTY, metrics, health checks, and public port routing.

What You Should Build First

Goal	Recommended first step
Evaluate basic command execution	Create base, write a file, run sh, delete the sandbox.
Execute generated code or data analysis	Create code-interpreter, use runCode, read generated artifacts.
Preview a web app	Create node or web-frontend, bind the app to 0.0.0.0, open getHost(3000).
Run a coding agent	Start with codex, claude, opencode, or base, then pin a concrete template.
Stabilize a production environment	Pin a concrete tpl-... ID or promoted tag, then verify image, resources, and startup behavior.

System Defaults

Item	Current contract
API base URL	https://sandbox-service.real-cloud.seaart.ai/api/v1/sandbox
API auth	X-API-Key: <SEACLOUD_API_KEY>
Runtime auth	X-Access-Token: <envdAccessToken> returned by create/detail/connect
First template	base for shell/files, code-interpreter for runCode workflows
Starter resource shape	Official starter templates commonly begin at 1 vCPU / 1024MB; larger language, browser, desktop, and agent templates reserve more.
Workspace path in examples	/root/workspace
Sandbox timeout unit	Seconds
Runtime command timeout unit	Milliseconds
App preview URL	https://sandbox-router.cloud.seaart.ai/{port}-{sandboxID}/
Billing basis	Configured vCPU and memory while running; storage only while paused; data transfer when traffic is sent or received.

Official Template Families

Template family	Use it for
base	General shell, files, git, PTY, metrics, and lightweight services.
node, python, go, web-frontend	Language-specific apps, previews, build jobs, and tests.
code-interpreter, code-interpreter-lite	Multi-language code execution, data analysis, and generated artifacts.
browser, desktop	Browser automation, screenshot capture, and computer-use style workloads.
codex, claude, opencode, openclaw, amp, openai-agents	Coding-agent and agent-orchestration runtimes.
api-server, mcp-server, scraper, devops	Service prototypes, MCP tools, scraping, and operational automation.
Concrete tpl-...	Production workloads that need stable image and storage behavior.

For the full public template list, typical resources, and use cases, see Sandbox Templates. List templates in the target environment before pinning one in production, then prefer a concrete tpl-... ID or tag.

Production Readiness Checklist

Before moving from evaluation to production, confirm:

1. The workload uses a concrete tpl-... ID or a promoted tag instead of a moving official alias.
2. All user-visible app servers bind to 0.0.0.0 and expose the documented port.
3. Sandbox lifecycle timeout and per-command timeoutMs are both explicitly set.
4. Logs, metrics, timeline, diagnostic, and requestID are captured in your support flow.
5. API keys and envdAccessToken never reach browser code, model prompts, or user-visible logs.

Docs

Quickstart Create a sandbox, write a file, run a command, and clean up.

Use cases Choose a sandbox workflow for agents, code interpreter, CI, and previews.

Lifecycle Create, connect, pause, refresh, timeout, and delete sandboxes.

Templates Choose official templates and pin reusable sandbox environments.

API Reference Use raw HTTP routes for lifecycle, runtime, templates, and usage.