Pause & Resume Sandboxes

This guide shows how to pause (suspend) and resume (restart) Agent Sandboxes. This is especially useful for persistent sandboxes where state needs to survive across sessions.

How Pause & Resume Works

Pause:

• Pod is deleted → compute resources are freed
• PVC (persistent volume) is retained → files in /workspace are preserved
• Billing stops for compute resources

Resume:

• New pod is created with the same configuration
• Same PVC is remounted → /workspace files are restored
• Agent continues from where it left off (if persistent)

Pause a Sandbox

curl -X POST {API_ENDPOINT}/sandboxes/{sandbox_id}/pause \
  -H "OPEN-SANDBOX-API-KEY: YOUR_API_KEY"

The pause operation is instant. The sandbox status will change to Paused.

Resume a Sandbox

curl -X POST {API_ENDPOINT}/sandboxes/{sandbox_id}/resume \
  -H "OPEN-SANDBOX-API-KEY: YOUR_API_KEY"

The resume operation is instant and starts the pod creation process.

Check Status

curl {API_ENDPOINT}/sandboxes/{sandbox_id} \
  -H "OPEN-SANDBOX-API-KEY: YOUR_API_KEY" | jq '.status.state'

States:

• Running — Sandbox is active and ready
• Paused — Pod deleted, PVC retained
• Pending — Creating pod after resume

Persistence Guarantee

When you resume a persistent sandbox, your agent continues from the last checkpoint:

Step 1: Create persistent sandbox
  ↓
Agent writes: /workspace/state.json = {"step": 100}
  ↓
Step 2: Pause sandbox
  ↓
Pod deleted (compute freed), /workspace/state.json preserved
  ↓
Step 3: Resume sandbox
  ↓
New pod created, /workspace remounted
Agent reads: /workspace/state.json = {"step": 100}
Agent continues from step 100+ (not step 0!)

Next Steps

• Access Endpoints — Connect to services in your sandbox
• Delete Sandbox — Clean up when done