#Sandbox

A Sandbox is an isolated execution environment where you can run code, manage files, and control network access. Each sandbox is created from a Template and has a writable root filesystem that is checkpointed across pause/resume for the same sandbox identity.

For shell access and file copy over standard SSH clients, see SSH.

Sandbox Model#

Key Identifiers#

Lifecycle States#

Persistent Root Filesystem#

Sandbox0 persists the sandbox writable root filesystem as part of checkpointed pause/resume:

• when ttl expires or pause is requested, Sandbox0 saves a rootfs checkpoint before releasing the runtime pod
• when the sandbox resumes, Sandbox0 creates or reuses a runtime pod and restores the latest rootfs checkpoint before initializing sandbox processes
• files written outside mounted volumes survive pause/resume for the same sandbox identity after a checkpoint succeeds
• rootfs checkpoints for the sandbox identity are deleted when the sandbox is deleted or hard_ttl expires

Use the root filesystem for transparent same-sandbox continuity. Use Snapshot And Restore for named rootfs snapshots, restore, and fork operations. Use Volumes for storage that must be mounted by multiple sandboxes or accessed directly through Volume APIs.

Claim a Sandbox#

Claim a sandbox from a template. The sandbox is created from a pre-warmed pool for fast startup (<200ms cold start).

Request Body#

Sandbox Configuration#

When the cluster claim/start admission budget is full, the claim API returns 429 with error.code set to claim_start_throttled and a Retry-After header in seconds. Retry after that delay. Team quota failures also return 429, but use error.code set to quota_exceeded.

See Network and Protocol Controls for outbound control, Sandbox Services for public HTTP controls, Sandbox Functions for inline public handlers, and Credential for outbound auth and secret handling.

Sandbox env_vars override template/container environment variables for new contexts, supervised session attempts, command services, and function executions. Per-context, per-session, per-command, service runtime, and function env_vars override sandbox env_vars for that narrower scope. Warm processes start before the sandbox is claimed, so they do not receive claim-time sandbox env_vars.

Sandbox Resources#

Set config.resources.memory when one sandbox needs a different memory limit from its template. The minimum is 128Mi. The platform maximum defaults to 32Gi and can be changed by the operator with services.manager.config.sandboxMaxMemory.

The request only accepts memory. Manager derives CPU from services.manager.config.teamTemplateMemoryPerCpu and applies the larger of that value and the 150m minimum CPU limit to the sandbox runtime container. Existing running sandboxes can update memory with the Update Sandbox API.

SDK helpers expose this as WithSandboxMemory / UpdateSandboxMemory in Go, memory / updateMemory in TypeScript, memory / update_memory in Python, and --memory in the s0 CLI.

TTL vs Hard TTL#

Sandbox0 uses two-tier TTL to balance resource efficiency and flexibility:

Example timeline (sandbox created with ttl=300 and hard_ttl=3600):

• t=0: Sandbox created
• t=300: TTL expires → sandbox auto-pauses
• t=310: User calls refresh → TTL reset to 300, Hard TTL reset to 3600 (new hard deadline at t=3910)
• t=610: TTL expires again → sandbox auto-pauses
• t=3910: Hard TTL expires → sandbox identity and durable state are deleted

go
ctx := context.Background()
client, err := sandbox0.NewClient(
  sandbox0.WithToken(os.Getenv("SANDBOX0_TOKEN")),
  sandbox0.WithBaseURL(os.Getenv("SANDBOX0_BASE_URL")),
)
if err != nil {
  log.Fatal(err)
}

// Claim a sandbox from the "default" template
sandbox, err := client.ClaimSandbox(ctx, "default",
  sandbox0.WithSandboxHardTTL(300),
  sandbox0.WithSandboxMemory("512Mi"),
  sandbox0.WithSandboxEnvVars(map[string]string{
      "APP_ENV": "development",
  }),
)
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Sandbox ID: %s\n", sandbox.ID)
defer client.DeleteSandbox(ctx, sandbox.ID)

Get Sandbox Details#

Retrieve full details about a sandbox.

go
sb, err := client.GetSandbox(ctx, sandbox.ID)
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Status: %s\n", sb.Status)
fmt.Printf("Template: %s\n", sb.TemplateID)
fmt.Printf("Expires at: %s\n", sb.ExpiresAt)

Get Sandbox Status#

Get the current status of a sandbox (lighter weight than full details).

go
status, err := client.StatusSandbox(ctx, sandbox.ID)
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Status: %s\n", status.Status.Value)

Observability#

Sandbox0 exposes chart-ready runtime metrics, historical logs, and a canonical per-sandbox audit ledger. Audit is stored directly in ClickHouse and never wakes a paused sandbox. It is separate from platform service telemetry and the metering usage ledger. Audit ingestion and the observability-event query and watch API require the enterprise sandbox_audit feature; logs, runtime metrics, and the metric catalog do not.

Runtime metrics#

The metrics endpoint returns bounded, server-downsampled series ready for charts. The default query covers the last hour and requests CPU utilization, memory utilization, and network I/O. A query cannot span more than 30 days.

The built-in catalog is intentionally bounded:

Each series contains zero or more continuous segments. Runtime resets and collection gaps start a new segment, so clients must not connect lines across segments. The response also reports typed gaps, freshness relative to the requested end_time, the effective step_seconds, and whether the result is partial. Missing or unsupported observations are omitted and never synthesized as zero.

typescript
import { Client, SandboxRuntimeMetricName } from "sandbox0";

const client = new Client({ token: process.env.SANDBOX0_TOKEN! });
const metrics = await client.sandbox("sb_abc123").getMetrics({
    startTime: new Date(Date.now() - 60 * 60 * 1000),
    metrics: [
        SandboxRuntimeMetricName.SandboxCpuUtilization,
        SandboxRuntimeMetricName.SandboxMemoryWorkingSet,
        SandboxRuntimeMetricName.SandboxNetworkIo,
    ],
    maxPoints: 120,
});

Logs and audit events#

The upgraded /observability/events endpoint is the only public audit-event read API. It returns 403 feature_not_licensed unless audit is explicitly enabled and cluster-gateway has a valid enterprise license containing sandbox_audit. The caller also needs the independent sandboxaudit:read permission.

Every audit fact includes a stable event_id, schema version, trusted actor, action, resource, producer, operation correlation, outcome, and bounded request metadata. Pagination cursors and watch watermarks are response transport metadata and are not repeated inside each signed event. integrity contains the canonical SHA-256 payload digest, Ed25519 signature, signing key ID, and query-time signature_status. List and watch responses recompute each returned row's digest and verify its signature. An exact event_id lookup fetches enough rows to set event_id_conflict=true when the same stable ID appears with multiple payload hashes; this marker does not overwrite signature_status, so callers can distinguish payload collisions from signature failures.

Gateway operations produce an attempt before authorization or execution and a result after either the downstream response or a failed admission decision. ClickHouse is the only audit read source: the fsync-backed delivery buffer holds pending events for retry, but list and watch reads cannot see an event until ClickHouse acknowledges it. With the default durable_async mode, non-mutating and public-exposure operations may proceed after local durable enqueue, and healthy canonical visibility is normally delayed by the asynchronous delivery path and its default one-second flush/replay cycles. canonical_sync instead requires ClickHouse acknowledgement before admission and adds that round trip to the critical path.

State-changing Sandbox API operations are always strict, regardless of the configured delivery mode. Cluster-gateway requires ClickHouse to acknowledge the attempt before execution, buffers the HTTP response, and requires ClickHouse acknowledgement for the signed result before returning that response. If canonical admission fails after the attempt is durably buffered, the downstream operation is not executed and cluster-gateway attempts to append a correlated signed failed result with HTTP 503, execution_started=false, operation_executed=false, failure_stage=canonical_audit_admission, and failure_code=canonical_ack_unavailable for replay. If terminal-result custody also fails, the response reports audit_result=unrecorded; the orphan attempt is an audit-completeness incident, not evidence that the operation ran. If a result from an operation that did execute is only buffered for retry, the caller receives 503 rather than a false success. A 5xx or panic result after execution is recorded as unknown, because the downstream operation may have completed even if the gateway did not receive a definitive response.

Network allow decisions are fsynced to a node-local spool before netd opens the upstream connection. In durable_async, canonical delivery follows asynchronously; in canonical_sync, ClickHouse must acknowledge the allow attempt first, including for server-first SSH probes. A ClickHouse outage therefore delays audit-query visibility in durable_async but denies new flows in canonical_sync; an unwritable local buffer also fails closed unless synchronous canonical fallback succeeds. The result is appended when the flow closes. Consequently a long-lived keep-alive connection has one allow attempt and one eventual flow result; parsed HTTP or MCP operations may appear inside its bounded protocol details rather than as separate connections. Raw proxy and credential-resolution error strings remain local diagnostics and are not copied into the canonical ledger because they may contain upstream or credential details.

Set watch=true to stream matching log or event records as NDJSON in ingestion order. Without cursor or start_time, a watch stream starts at request time and does not replay historical rows. When watch=true, end_time is not supported. A watch stream emits event or log lines, watermark lines with a resume cursor, periodic heartbeat lines, and an error line before termination if the backend fails after the stream starts. Runtime metrics are queried as bounded time series and do not expose a watch mode.

ClickHouse-backed deployments store canonical audit facts in sandbox_audit_events; logs and wide runtime samples remain separate historical projections with independent retention TTLs. Cluster-gateway records authenticated Sandbox API access (including regional detail requests), netd records network attempts and results, manager publishes logs, and node-local ctld instances collect sandbox-wide CRI runtime samples every 15 seconds with jitter.

Historical data query endpoints return 503 when the backend is disabled or unavailable. The static metric catalog remains available so clients can build selectors without probing storage.

List Sandboxes#

List all sandboxes with optional filters.

Query Parameters#

go
limit := 10
sandboxes, err := client.ListSandboxes(ctx, &sandbox0.ListSandboxesOptions{
  Status:     "running",
  TemplateID: "default",
  Limit:      &limit,
})
if err != nil {
  log.Fatal(err)
}
for _, sb := range sandboxes.Sandboxes {
  fmt.Printf("- %s (status: %s)\n", sb.ID, sb.Status)
}

Update Sandbox#

Update sandbox configuration at runtime without restarting the sandbox.

Updatable Fields#

Only the following fields can be updated at runtime:

go
_, err = client.UpdateSandboxMemory(ctx, sandbox.ID, "2Gi")
if err != nil {
  log.Fatal(err)
}

Pause And Resume#

Pause and resume is covered in a dedicated page because it affects TTL, auto_resume, service routes, SSH, and webhook behavior.

See Pause And Resume for explicit pause, state inspection, resume, and auto-resume behavior.

See Snapshot And Restore for named rootfs snapshots, restore, and fork operations. Snapshot and fork accept a running or paused source sandbox; restore requires a paused target sandbox.

Refresh Sandbox TTL#

Extend the sandbox time-to-live. This resets both ttl and hard_ttl (if configured) from the current time while the sandbox has a runtime.

Request Body#

go
// Refresh with default duration (original TTL)
resp, err := client.RefreshSandbox(ctx, sandbox.ID, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Printf("New expires at: %s\n", resp.ExpiresAt)

// Refresh with custom duration (e.g., 1 minute)
resp, err = client.RefreshSandbox(ctx, sandbox.ID, &apispec.SandboxRefreshRequest{
  Duration: apispec.NewOptInt32(60),
})
if err != nil {
  log.Fatal(err)
}
fmt.Printf("New expires at: %s\n", resp.ExpiresAt)

Delete Sandbox#

Terminate and delete a sandbox. This action is irreversible.

go
_, err = client.DeleteSandbox(ctx, sandbox.ID)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Sandbox deleted")

Next Steps#