Pause And Resume

Sandbox0 can pause an idle sandbox without deleting it. Pause checkpoints the writable root filesystem, releases the runtime pod, and keeps the sandbox identity and durable state. Resume creates a new runtime generation and restores the latest rootfs checkpoint.

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 sandbox is running or paused

What Persists#

The rootfs checkpoint covers files written inside the sandbox filesystem. It is tied to the sandbox lifecycle. For named rootfs snapshots, restore, and fork operations, see Snapshot And Restore.

On nodes using the containerd overlayfs snapshotter, ctld checkpoints only the active snapshot upperdir and stores it as a standard OCI layer diff. Other snapshotters, or nodes where the overlayfs upperdir is not readable by ctld, fall back to containerd's built-in diff path.

Pause A Sandbox#

Pause a sandbox to release compute while keeping its identity, configuration, services, and latest writable rootfs checkpoint available for a later resume.

The pause request is asynchronous. Poll sandbox details until status is paused and paused is true before treating the checkpoint as resume-ready.

pausing and resuming are not caller-visible states. A lifecycle transaction in progress is not a 409 Conflict; that status is reserved for actual policy or state conflicts such as disabled auto-resume, non-restartable routes, quota limits, deletion, or paused-only operations.

Runtime Failure Recovery#

Sandbox0 uses the durable pause flow to replace a failed runtime.

Recovery is independent of the sandbox auto_resume access policy. A supported runtime request waits for recovery to commit, then resumes when auto-resume is allowed.

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.

Persistent And Ephemeral Paths#

The writable rootfs persists across pause and resume except for runtime-owned ephemeral paths:

• /tmp is recreated from the clean carrier or template state. Files written there do not survive pause and resume.
• /var/tmp remains part of the persistent rootfs.
• Other writable rootfs paths, such as /root and workspace directories, remain persistent.

This policy is applied while saving checkpoints, restoring checkpoint layers, and capturing incremental baselines. Sandbox0 also filters /tmp from older checkpoint layers during restore. The first restore of a large older checkpoint can still take time because the layer must be read once; the next pause writes a checkpoint without those /tmp contents.

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 the lifecycle status.

During asynchronous pause, paused remains false and status continues to reflect the cached runtime Pod state, usually running. It becomes true only after checkpoint upload has completed, the runtime pod has been released, and the sandbox is safe to resume from durable state.

During resume, callers may wait while Sandbox0 creates and initializes a new runtime generation. After the resume transaction commits, status is running, paused is false, and runtime_generation has advanced. If an automatic pause is canceled before commit, status remains running, paused remains false, and runtime_generation does not change.

go
sb, err := client.GetSandbox(ctx, sandbox.ID)
if err != nil {
  log.Fatal(err)
}
fmt.Printf("paused=%v
", sb.Paused)
fmt.Printf("status=%s
", sb.Status)
fmt.Printf("runtime_generation=%d
", sb.RuntimeGeneration)

TTL And Auto Resume#

ttl and hard_ttl interact with pause differently:

auto_resume is the sandbox-level gate for 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:

• sandbox runtime APIs such as files, contexts, and supervised sessions
• service routes configured with resume: true; public service requests require sandbox auto_resume: true, route resume: true, and a restartable service runtime (cmd or function)
• SSH access through Sandbox0 SSH Gateway

For a paused sandbox, auto-resume creates a new runtime pod for the same sandbox identity and restores the saved rootfs checkpoint before the sandbox is used. Public service URLs remain stable until the sandbox is explicitly deleted or hard_ttl expires.

Supported runtime access distinguishes an accepted resume from a failed attempt:

• 503 unavailable with sandbox is waking up means the accepted lifecycle transition has not committed yet; poll sandbox details before retrying the runtime request
• 503 sandbox_resume_failed with sandbox resume failed means that resume attempt ended unsuccessfully; clients may perform a bounded retry, but should not treat the failed attempt as still in progress

Running PIDs, memory, sockets, and client attachments do not survive pause. A supervised session keeps its logical identity and retained journal, then follows its runtime_recovery policy in the new runtime generation.

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

Typical Pattern#

For long-running workflows, a common pattern is:

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

Next Steps#