Documentation/docs/sandbox/pause-resume

#Pause And Resume

Sandbox0 can pause an idle sandbox without deleting it. Pause preserves sandbox state, while resume makes the sandbox runnable again.

Use this page when you need to:

pause a sandbox explicitly
resume a paused sandbox explicitly
understand how ttl, auto_resume, service routes, and SSH interact with pause state
inspect whether a pause or resume request has completed

ℹ

Pause state is separate from status. Use paused for the simple user-facing state, and power_state when you need to inspect desired versus observed transition progress.

Pause A Sandbox#

Pause a sandbox to release compute while keeping its state available for a later resume.

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

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

Resume A Sandbox#

Resume a sandbox that was paused manually or by TTL expiry.

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

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

Inspect Pause State#

After requesting a pause or resume, fetch sandbox details to check whether the transition has completed.

go
sb, err := client.GetSandbox(ctx, sandbox.ID)
if err != nil {
  log.Fatal(err)
}
fmt.Printf("paused=%v
", sb.Paused)
fmt.Printf("power_state=%+v
", sb.PowerState)

TTL And Auto Resume#

ttl and hard_ttl interact with pause differently:

Field	Behavior
`ttl`	Soft timeout. When it expires, Sandbox0 pauses the sandbox.
`hard_ttl`	Hard timeout. When it expires, Sandbox0 deletes the sandbox.

auto_resume controls whether inbound access can wake a paused sandbox:

when auto_resume is true, supported access paths can resume the sandbox automatically
when auto_resume is false, you must call resume explicitly

Common auto-resume entrypoints:

service routes configured with resume: true
SSH access through Sandbox0 SSH Gateway

See Sandbox Services and SSH for the user-facing flows.

Typical Pattern#

For long-running agent workflows, a common pattern is:

claim a sandbox with ttl set
do active work through contexts and files
let idle sandboxes pause automatically
resume on the next user action, SSH session, or service route hit
use hard_ttl to cap the maximum lifetime