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 gateway. The gateway creates and manages sandboxes through the control plane, 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.

Build reusable environments Best for production workloads. Package dependencies, source code, startup commands, and readiness 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 Gateway
    -> Atlas control plane creates or reconnects a sandbox
      -> Template image starts inside an isolated runtime
        -> SDK uses envdUrl + sandbox token 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://{port}-{sandboxID}.{domain}/` after binding the service to `0.0.0.0`.
Templates	Build reusable `tpl-...` environments with pinned dependencies, startup commands, readiness checks, and storage policy.
Multi-language SDKs	Node, Python, and Go SDKs expose aligned lifecycle, file, command, template, and code-interpreter flows.

Architecture Planes

Plane	Service	Responsibility
Gateway	Hermes	Public API entrypoint, API key auth, routing, and request context.
Control plane	Atlas	Create, inspect, connect, pause, refresh, timeout, logs, and delete.
Build plane	sandbox-builder	Template metadata, build context upload, image builds, build logs, and rollback.
Runtime plane	nano-executor	Runtime 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.
Keep user work between sessions	Use `nfs`, `cloud`, `block`, or a custom template with explicit `volumeMounts`.
Reduce cold setup time	Build a custom `tpl-...` with dependencies and startup commands baked in.

System Defaults

Item	Current contract
Gateway base URL	`https://sandbox-gateway.cloud.seaart.ai`
Control-plane 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
Workspace path in examples	`/root/workspace`
Sandbox timeout unit	Seconds
Runtime command timeout unit	Milliseconds
App preview URL	`https://{port}-{sandboxID}.{envdBaseDomain}/`

Official Template Families

Template family	Use it for
`base`	General shell, files, git, PTY, metrics, and lightweight services.
`code-interpreter`	Python, JavaScript, TypeScript, Bash, R, and Java code execution.
`node`, `python`, `go`	Language-specific app and build/test workflows.
`browser`, `desktop`	Browser automation and computer-use style workloads.
`nfs`, `cloud`, `block`	Persistent workspace behavior, depending on the mounted storage type.
Concrete `tpl-...`	Production workloads that need stable image and storage behavior.

Current Official Template Shape

Official template availability can differ by environment. In the current production matrix, managed templates expose runtime APIs on port 9000 and use /root/workspace as the default workdir.

Template	Typical CPU / memory	Storage
`base`	`1 / 1024MB`	`ephemeral` at `/root/workspace`
`cloud`	`1 / 1024MB`	`object` at `/root/workspace`
`nfs`	`1 / 1024MB`	`nfs` at `/root/workspace`
`block`	`1 / 1024MB`	`block` at `/root/workspace`
`python`, `node`	`2 / 2048MB`	`ephemeral`
`go`, `web-frontend`, `browser`, `code-interpreter`	`2 / 4096MB`	`ephemeral`
`desktop`, `claude`, `openclaw`	`4 / 8192MB`	`ephemeral`

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:

The workload uses a concrete tpl-... ID or a promoted tag instead of a moving official alias.
All user-visible app servers bind to 0.0.0.0 and expose the documented port.
Sandbox lifecycle timeout and per-command timeoutMs are both explicitly set.
Persistent data is written only under template volumeMounts.
Logs, metrics, timeline, diagnostic, and requestID are captured in your support flow.
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 Move repeated setup into reusable sandbox templates.