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 to the writable rootfs 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 across sandbox identities.

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#

Team quota failures return 429 with error.code set to quota_exceeded. The sandbox_claims policy controls sustained claim rate and immediate burst and includes a Retry-After header when exhausted; active_sandboxes controls the team's running sandbox capacity.

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 16Gi and can be changed by the operator with services.manager.config.sandboxMaxMemory. Sandbox0 enforces that maximum on template defaults and on sandbox claim, update, resume, and fork operations.

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:

When an expiration path is disabled or unset, Sandbox responses return null for the corresponding expires_at or hard_expires_at field. A disabled expiration is never represented as a sentinel date.

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 runtime metrics, historical logs, and signed audit events without waking a paused sandbox.

Audit ingestion and audit queries require the enterprise sandbox_audit feature. Logs, runtime metrics, and the metric catalog do not.

See Observability for metric names, query filters, watch streams, audit integrity, delivery modes, and coverage limits.

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#