Persistence & Storage

Agent Sandboxes support two storage modes:

1. Ephemeral (default) — Fast startup, no persistent storage
2. Persistent — Slower startup, /workspace PVC survives pause/resume

Storage is configured via the extensions field in the sandbox creation request.

Ephemeral Sandboxes

Default behavior — no extensions needed:

{
  "image": { "uri": "python:3.12-slim" },
  "entrypoint": ["/bin/sh", "-c", "python3 -m http.server 8000"],
  "resourceLimits": {
    "cpu": "2",
    "memory": "2Gi"
  }
}

Characteristics:

• Startup time: ~2.5 seconds
• Storage: In-memory only (lost on delete)
• Use case: Stateless services, temporary tasks, development/testing

Persistent Sandboxes

Add extensions to enable persistent storage:

{
  "image": { "uri": "python:3.12-slim" },
  "entrypoint": ["/bin/sh", "-c", "python3 -m http.server 8000"],
  "resourceLimits": {
    "cpu": "2",
    "memory": "2Gi"
  },
  "extensions": {
    "persistence": "true",
    "storageClass": "local-path",
    "storageSize": "50Gi"
  }
}

Characteristics:

• Startup time: ~6-7 seconds
• Storage: PVC mounted at /workspace
• Pause/Resume: PVC retained across pause cycles
• Use case: Long-running agents, state checkpointing, multi-step workflows

Extensions Fields

• persistence (Required) — String. Enable or disable persistent storage ("true" or "false").
• storageClass (Required if persistence=true) — String. Kubernetes StorageClass name (e.g., "local-path" or "abs").
• storageSize (Required if persistence=true) — String. PVC size in Kubernetes format (e.g., "50Gi")

Storage Classes

The storageClass field references a Kubernetes StorageClass:

• local-path — Local disk storage. Use for development and testing.
• abs — Accelerated Block Storage (Nirvana). Use for production workloads.

Persistence Guarantee

When a persistent sandbox is paused and resumed:

1. Pod is deleted — compute resources freed
2. PVC is retained — all files in /workspace preserved
3. New pod created on resume — same PVC mounted
4. Agent continues — picks up from last checkpoint

Example Workflow:

Step 1: Create sandbox with persistence
  → /workspace is empty

Step 2: Agent writes state to /workspace/state.json
  → step=1, step=2, step=3...

Step 3: Pause sandbox
  → Pod deleted, /workspace/state.json persists

Step 4: Resume sandbox
  → New pod created, /workspace mounted
  → Agent reads last checkpoint
  → Continues from step=N (not step=0)