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

Sandbox Model#

Key Identifiers#

Field	Description
`id`	Unique sandbox identifier (e.g., `sb_abc123`)
`template_id`	Template used to create this sandbox
`team_id`	Team that owns this sandbox
`user_id`	User who claimed this sandbox
`pod_name`	Kubernetes pod name (internal)
`cluster_id`	Cluster where sandbox runs (multi-cluster only)

Lifecycle States#

Status	Description
`starting`	Sandbox is being initialized
`running`	Sandbox is active and ready to use
`paused`	Sandbox is paused (resources preserved)
`failed`	Sandbox encountered an error
`completed`	Sandbox has finished execution

Claim a Sandbox#

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

POST/api/v1/sandboxes

Request Body#

Field	Type	Description
`template`	string	Template ID to use
`config`	object	Optional sandbox configuration

Sandbox Configuration#

Field	Type	Description
`env_vars`	object	Environment variables
`ttl`	integer	Time to live in seconds (soft limit, triggers auto-pause; default: `0`, disabled)
`hard_ttl`	integer	Maximum lifetime in seconds (hard limit, triggers deletion; default: `0`, disabled)
`network`	object	Network policy configuration
`webhook`	object	Webhook configuration
`auto_resume`	boolean	Auto-resume when accessed (default: true)
`exposed_ports`	array	Ports to expose publicly

TTL vs Hard TTL#

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

Field	Behavior	Use Case
`ttl`	Soft pause: When expired, sandbox is automatically paused. Processes stop but state is preserved. Can be extended via refresh API.	Keep sandboxes alive during active use while freeing compute resources during idle periods.
`hard_ttl`	Hard delete: When expired, sandbox is permanently deleted regardless of pause state. Can also be extended via refresh API.	Enforce maximum lifetime for security or cost control. The difference from `ttl` is the expiration behavior (delete vs pause).

ℹ

The relationship: ttl <= hard_ttl. When ttl expires first, sandbox pauses but can be resumed. When hard_ttl expires, sandbox is deleted immediately. Both can be extended via the refresh API.

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

GET/api/v1/sandboxes/{id}

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).

GET/api/v1/sandboxes/{id}/status

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

List Sandboxes#

List all sandboxes with optional filters.

GET/api/v1/sandboxes

Query Parameters#

Parameter	Type	Description
`status`	string	Filter by status (starting, running, paused, failed, completed)
`template_id`	string	Filter by template ID
`paused`	boolean	Filter by paused state
`limit`	integer	Max results per page (default: 50, max: 200)
`offset`	integer	Pagination offset (default: 0)

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.

PUT/api/v1/sandboxes/{id}

Updatable Fields#

Only the following fields can be updated at runtime:

Field	Type	Description
`ttl`	integer	Time to live in seconds (soft limit)
`hard_ttl`	integer	Maximum lifetime in seconds (hard limit)
`network`	object	Network policy configuration
`auto_resume`	boolean	Auto-resume when accessed
`exposed_ports`	array	Ports to expose publicly

ℹ

env_vars and webhook cannot be updated at runtime. These fields only take effect when the sandbox is created. To use different environment variables, create a new sandbox.

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

Pause a sandbox to save resources. The sandbox state is preserved.

POST/api/v1/sandboxes/{id}/pause

ℹ

When a sandbox is paused, all processes are stopped but memory state is preserved. Use auto_resume to automatically resume when accessed.

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

Resume Sandbox#

Resume a paused sandbox.

POST/api/v1/sandboxes/{id}/resume

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

Refresh Sandbox TTL#

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

POST/api/v1/sandboxes/{id}/refresh

Request Body#

Field	Type	Description
`duration`	integer	Duration to extend TTL in seconds (optional, defaults to original TTL)

ℹ

If duration is not specified, both ttl and hard_ttl are reset to their original configured values. Use this to keep a sandbox alive as long as the user is actively using it.

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 minutes)
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.

DELETE/api/v1/sandboxes/{id}

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

Next Steps#

Contexts

Run commands and manage processes (REPL and Cmd)

Files

Read, write, and manage files in sandboxes

Network Policy

Control network access and egress rules