Sandbox Lifecycle

A sandbox moves through creation, readiness, runtime operation, and cleanup. Use the SDK object returned by create/connect as the boundary for all runtime work.

Lifecycle Model

create -> starting -> running -> pause/connect or refresh -> delete

Action	Use it when
create	Allocate a runtime from base, code-interpreter, or tpl-....
waitReady	The next line needs files, commands, or ports to be available immediately.
connect	Recover runtime URL/token for an existing sandbox ID.
pause	Stop runtime resources while keeping metadata for a later connect flow.
refresh	Extend TTL for active work.
setTimeout	Change lifecycle timeout in seconds.
delete	Permanently clean up disposable work.

Public States

API responses expose product-safe states. Internal Atlas states such as new, warming, warm, creating, active, stopped, and destroying are collapsed before they reach public clients.

State/status	Meaning
starting	Runtime is creating or waiting for a healthy heartbeat.
running	Runtime APIs are usable.
paused	Runtime is stopped, but durable metadata remains for connect/resume.
deleted	Sandbox has been removed.
failed / error	Runtime failed to become usable or a lifecycle operation failed.

Sandbox detail, list, and create responses may include timeline and diagnostic. Use those fields for user-facing progress and troubleshooting instead of parsing raw logs.

Create Options

Option	Unit	Purpose
templateID	string	Required template reference.
timeout	seconds	Sandbox lifecycle TTL.
waitReady	boolean	Wait for usable runtime state.
envVars	map	Runtime environment overrides.
metadata	map	User metadata for search and debugging.
autoPause	boolean	When supported, timeout maps to pause instead of kill.

Do not send stale compatibility fields such as timeoutMs, autoResume, secure, allow_internet_access, network, mcp, volume_mounts, or request-level volumeMounts. They are rejected instead of silently ignored.

Create And Reconnect

Node

const sandbox = await Sandbox.create("base", {
  timeout: 1800,
  waitReady: true,
  envVars: { FOO: "bar" },
  metadata: { purpose: "demo" },
});

const sandboxId = sandbox.sandboxId;

await sandbox.connect({ timeout: 1800 });
// Or from a different process:
const reconnected = await Sandbox.connect(sandboxId, { timeout: 1800 });

Python

sandbox = Sandbox.create(
    "base",
    timeout=1800,
    waitReady=True,
    envVars={"FOO": "bar"},
    metadata={"purpose": "demo"},
)

sandbox_id = sandbox.sandbox_id
sandbox.connect(timeout=1800)
reconnected = Sandbox.connect(sandbox_id, timeout=1800)

Timeout And Cleanup

Node

await sandbox.setTimeout(3600);
await sandbox.refresh();
await sandbox.pause();
await sandbox.delete();

Python

sandbox.set_timeout(3600)
sandbox.refresh()
sandbox.pause()
sandbox.delete()

Runtime credentials

Create, detail, and connect responses return runtime fields such as envdUrl and envdAccessToken. SDKs should hide these values. Application code should not cache nano-executor URLs or log runtime tokens.

Raw Control-Plane Routes

Method	Path	Purpose
POST	/api/v1/sandboxes	Create a sandbox.
GET	/api/v1/sandboxes/:sandboxID	Fetch detail and runtime connection data.
POST	/api/v1/sandboxes/:sandboxID/connect	Reconnect and refresh runtime access.
POST	/api/v1/sandboxes/:sandboxID/pause	Pause runtime.
POST	/api/v1/sandboxes/:sandboxID/refreshes	Refresh TTL.
POST	/api/v1/sandboxes/:sandboxID/timeout	Change timeout in seconds.
DELETE	/api/v1/sandboxes/:sandboxID	Delete sandbox.

Logs, Metrics, And Diagnostics

Signal	Route	Use it for
Sandbox detail	GET /api/v1/sandboxes/:sandboxID	State, runtime URL/token, lifecycle timestamps, timeline, and diagnostic.
Sandbox logs	GET /api/v1/sandboxes/:sandboxID/logs	Startup output, readiness failures, application logs, and image pull issues.
Sandbox metrics	GET /api/v1/sandboxes/:sandboxID/metrics	Current CPU, memory, disk, network, and task counters.
Observability summary	GET /api/v1/observability/summary	User/project usage, quota checks, endpoint availability, and suggested next actions.