How do you keep an AI agent’s environment alive between turns or sessions?
There are two general approaches:- Pause-in-place: suspend the live VM so its filesystem, memory, and running processes are preserved, then resume under the same identifier. Useful for keeping an agent’s working memory and open processes alive between turns.
- Snapshot-and-restore: capture a reusable artifact you can boot into a fresh VM later. Useful for retrying from a checkpoint or branching experiments.
What’s the difference between ephemeral and named sandboxes?
Ephemeral sandboxes have no name and run until you terminate them or they time out. Named sandboxes support suspend/resume so you can pause between tasks and pick up where you left off.
What states does a Tensorlake Sandbox move through?
Every sandbox moves through these states. Create starts the sandbox inPending; from Running, you can suspend (named only), snapshot, or terminate. Ephemeral sandboxes skip Suspending/Suspended.
For the full state diagram, see Lifecycle.
How do I suspend a Tensorlake Sandbox?
Callsuspend on a named sandbox. The sandbox transitions to Suspended, consumes no compute, and preserves its state. Call resume on the same sandbox ID to bring it back to Running. Suspend is not supported for ephemeral sandboxes.
How do I prevent traffic from waking a suspended sandbox?
Create a named sandbox withauto_resume: false, or set it through Update Sandbox. In Python, use auto_resume=False; in TypeScript, use autoResume: false. This setting does not suspend a running sandbox. After suspension, proxy traffic returns HTTP 409 with code SANDBOX_AUTO_RESUME_DISABLED.
Explicit resume still works without changing the setting. Set it to true to restore wake-on-traffic; that update does not itself wake the sandbox. See Keep a sandbox suspended.
How do I recover when resume fails?
Read sandbox metadata. Ifstatus is resume_failed, record optional error_details and the original snapshot_id, then explicitly resume the same sandbox. Limit retries and inspect the result before running work. An accepted retry clears the previous diagnosis; it does not guarantee success.
Proxy traffic never retries this state, even with auto_resume enabled. A timeout alone does not mean resume failed: pending, including retained_runtime.state: resume_uncertain, must settle before you treat it as safely retryable. Follow Recover from a failed resume for Python, TypeScript, and CLI examples.
When should I use suspend vs. snapshot?
Both preserve sandbox state, but they serve different purposes:- Suspend pauses this sandbox so you can resume it later under the same ID.
- Snapshot captures a reusable artifact you can restore into a new sandbox.
See Snapshots for save-and-restore.
What happens when a sandbox times out?
Ephemeral sandboxes are terminated when their timeout elapses. Named sandboxes transition to Suspending then Suspended whentimeout_secs elapses, preserving state for later resume rather than terminating.
Can I reverse a terminated sandbox?
resume cannot recover a terminated sandbox. Restart is a separate operation available within 48 hours of termination. It uses a usable snapshot if available and otherwise cold boots; it does not guarantee recovery of prior memory and process state.
How is suspend/resume different from stopping and restarting a Docker container?
Stopping a Docker container ends its processes and discards memory state; restarting goes through a cold boot and re-initializes the application. Tensorlakesuspend pauses a named sandbox in place: filesystem, memory, and running processes are preserved. resume brings it back to Running under the same sandbox ID with the same in-memory state, so an agent harness can pick up exactly where it left off.