Sandboxes

Use sandbox lifecycle APIs to create an isolated runtime, reconnect to it, pause it, extend its TTL, and delete it.

Create Sandbox

POST /sandboxes

Request body:

Field	Type	Required	Description
templateID	string	no	Template ID or official type such as base, code-interpreter, node, codex, or api-server. Empty uses the default base template. See the template guide for the public official list.
timeout	integer	no	Lifecycle TTL in seconds.
waitReady	boolean	no	Wait until the sandbox is ready before returning.
metadata	object	no	Key/value metadata persisted as sandbox labels.
envVars	object	no	Environment variables injected at creation.
autoPause	boolean	no	Pause instead of kill when timeout expires.
autoResume	boolean	no	Allow router-triggered resume for paused sandboxes.
allowInternetAccess	boolean	no	E2B-style egress control.
network.allowPublicTraffic	boolean	no	Require a preview traffic token when set to false.
network.allowInternetAccess	boolean	no	Egress control inside the network object.
network.allowOut	string[]	no	IPv4/CIDR egress allowlist.
network.denyOut	string[]	no	IPv4/CIDR egress denylist.
volumeMounts	object[]	no	Request-level volume mounts, each as { "name": "...", "path": "/..." }.

Do not send timeoutMs, secure, mcp, or snake_case volume_mounts in the create request. timeout is seconds. Runtime command requests still use timeoutMs in milliseconds.

export SEACLOUD_API_BASE_URL="https://sandbox-service.real-cloud.seaart.ai/api/v1/sandbox"

curl -sS -X POST "$SEACLOUD_API_BASE_URL/sandboxes" \
  -H "X-API-Key: $SEACLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "timeout": 1800,
    "waitReady": true,
    "metadata": { "app": "agent" }
  }'

Response:

{
  "templateID": "tpl-base-...",
  "sandboxID": "sandbox_...",
  "envdAccessToken": "<opaque-token>",
  "envdUrl": "https://sandbox-router.example/9000-sandbox_...",
  "status": "running",
  "state": "running",
  "startedAt": "2026-06-10T08:55:50Z",
  "activatedAt": "2026-06-10T08:55:50Z",
  "endAt": "2026-06-10T09:25:50Z",
  "timeline": []
}

List Sandboxes

GET /sandboxes

Common query parameters:

Query	Description
state	Optional lifecycle state filter. Can be repeated or comma-separated.
metadata[key]	Optional metadata filter.
limit	Page size.
nextToken	Pagination token from the previous response.

Get Sandbox

GET /sandboxes/:sandboxID

Returns detail, lifecycle timestamps, runtime access information, timeline, and optional diagnostic fields.

Connect Sandbox

POST /sandboxes/:sandboxID/connect

Request body:

{
  "timeout": 1800
}

The body and timeout field are required. timeout=0 keeps the existing TTL. A positive timeout resets the TTL from the connect time. timeoutMs is rejected on this control-plane route.

Pause, Refresh, Timeout, Delete

Method	Path	Description
POST	/sandboxes/:sandboxID/pause	Pause runtime while preserving resumable state.
POST	/sandboxes/:sandboxID/refreshes	Extend lifetime using the platform default or duration.
POST	/sandboxes/:sandboxID/timeout	Set TTL in seconds using { "timeout": 3600 }.
DELETE	/sandboxes/:sandboxID	Delete the sandbox.

POST /sandboxes/:sandboxID/timeout also requires a JSON body with timeout; timeoutMs is rejected.

Logs And Metrics

Method	Path	Description
GET	/sandboxes/:sandboxID/logs	Logs with limit, cursor, direction, level, and search.
GET	/sandboxes/:sandboxID/metrics	Latest metric snapshot for one sandbox.
GET	/sandboxes/metrics	Batch metric snapshots.