A sandbox, an agent session, a prepared task, and a durable workflow preserve different
state. Choose the layer that owns the work; none makes an ambiguous external side effect
safe to repeat.
What survives
Create a durable workspace
The deployment must enable persistent/durable features and admit your plan, resources, and
runtime. Persistent/durable creation cold-starts. The managed PVC is deleted when the
sandbox terminates; export important results to artifact storage.
Use returned generation/recovery/expiry metadata to inspect actual state.
Non-durable lifetime is bounded by the plan and 24-hour platform cap. Durable plans have
separate limits; some plans do not admit durability. Extension returns applied duration,
maximum expiry, and remaining headroom. At the cap, inspect the machine-readable conflict
rather than repeatedly extending. Billing and current authorization also apply to resume.
Pause and resume
With KUBERNETES_PAUSE_MODE=snapshot, only durable sandboxes can pause. The API accepts
optional wait, timeout_seconds (up to 120), and the supported pause auto_resume option.
An accepted transition can return 202 pausing/resuming; inspect status until terminal
for that transition. A 200 paused/running result is different from mere acceptance.
Paused time does not accrue running-time compute, but paused-time budgets, retained storage,
plan policy, and other charges remain separate. Paused-time retention is bounded. Automatic
resume applies only to an eligible pause reason/configuration; it is not a general fallback
for manual or billing holds. Restored code must rebuild its in-memory state explicitly.
Session configuration
Sessions are under /api/v1/agent/sessions, using Sandbox authentication and scopes. A
source-derived creation body is:
Confirm the running deployment’s supported fields before creating a session. Legacy and
normalized forms are supported in the source, but client/server versions differ. Budgets
are session controls, not a prepaid guarantee for arbitrary external model calls. A command
can cross a cost threshold before accounting stops further work.
An enabled durable session keeps its durable sandbox instead of rotating it. Its supported
keepalive heartbeats extend within the plan cap. Ordinary session rotation carries only
its documented checkpoint/context state. includeProcessState does not make process-memory
restoration a supported general capability.
Reattach by retained session/client identity and inspect current state. Heartbeat, local
waiting, and server cancellation are separate operations. Stop/cancel acknowledgements
confirm acceptance, not observed process termination. For cross-process durable automation,
use the separately configured Temporal service and its own credentials.
Recovery boundary
During durable recovery or before execution admission, a documented not-started 503 can
carry a retry hint. Losing the execution connection after work may have started instead
leaves an unknown outcome. Preserve the original execution identity; inspect receipts and
workspace/external state before choosing any new command.
Source: docs/guides/LONG_RUNNING_AGENTS.md, PAUSE_RESUME.md,
guides/PERSISTENT_WORKSPACES.md, guides/SANDBOX_BRANCHING.md, and session handlers,
checked October 20, 2026. Continue with execution recovery
or prepared tasks. Last modified on October 20, 2026
