#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#

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, command services, and function executions. Per-context, 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.

Sandbox0 keeps CPU and memory in the platform-defined ratio. The request only accepts memory; manager derives CPU from services.manager.config.teamTemplateMemoryPerCpu and applies the result 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)

Get Sandbox Logs#

Read sandbox process output. Procd service logs are filtered out of this API and remain available from Kubernetes pod logs. Snapshot and streaming requests return text/plain.

Query Parameters#

go
tailLines := int64(200)
logs, err := sandbox.GetLogs(ctx, &sandbox0.SandboxLogsOptions{
  TailLines: &tailLines,
})
if err != nil {
  log.Fatal(err)
}
fmt.Print(logs.Logs)

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 that require a paused 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#