#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 provides a secure, ephemeral workspace.

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

Sandbox Model#

Key Identifiers#

Lifecycle States#

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.

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 → runtime pod cleaned, sandbox status becomes cleaned

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.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.UpdateSandbox(ctx, sandbox.ID, apispec.SandboxUpdateRequest{
  Config: apispec.NewOptSandboxUpdateConfig(apispec.SandboxUpdateConfig{
      TTL:        apispec.NewOptInt32(600),
      AutoResume: apispec.NewOptBool(false),
  }),
})
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.

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#