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. If no template is specified, the default is base.
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 a small set of public states. Intermediate creation and cleanup phases 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 log text.

Readiness is based on the runtime health heartbeat. A sandbox should be treated as usable after the API reports running or the SDK waitReady call resolves.

Create, detail, and list responses use the same public field meanings. Resource fields such as memoryMB, lifecycle timestamps such as startedAt, and expiration fields such as endAt should be displayed from the API response without substituting unrelated update timestamps.

Create Options

Option	Unit	Purpose
templateID	string	Optional template reference; omitted or empty uses base.
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.
autoResume	boolean	Allow router-triggered resume for paused sandboxes when supported.
network	object	Public preview and egress policy, including allowPublicTraffic, allowInternetAccess, allowOut, and denyOut.
volumeMounts	array	Optional request-level mounts using camelCase only.

Do not send removed create/lifecycle compatibility fields such as timeoutMs, secure, mcp, or snake_case volume_mounts. They are rejected instead of silently ignored. Sandbox lifecycle timeout is seconds; runtime command timeoutMs remains supported and is milliseconds.

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 runtime URLs or log runtime tokens.

Raw HTTP Routes

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

Logs, Metrics, And Diagnostics

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