Documentation Index
Fetch the complete documentation index at: https://docs.tensorlake.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 | Named | |
|---|---|---|
| Created with | tl sbx create | tl sbx create <name> |
| Suspend / Resume | Not supported | Supported |
| Reference by | ID only | ID or name |
| Use when | Short-lived tasks, one-off execution | Multi-step work, persistent environments |
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.
| State | What it means |
|---|---|
| Pending | Sandbox is being scheduled and booted. Transitions to Running automatically. |
| Running | Sandbox is live and accepting commands, file operations, and process execution. |
| Snapshotting | A reusable snapshot artifact is being captured. Returns to Running when done. |
| Suspending | Named sandbox is being paused — manually or via timeout_secs. |
| Suspended | Named sandbox is paused. Consumes no compute; state preserved. |
| Terminated | Sandbox has stopped. Final state; cannot be reversed. |
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.
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.
| Scenario | Use Suspend | Use Snapshot |
|---|---|---|
| Pause and resume later | ✅ | ❌ |
| Save cost when idle | ✅ | ❌ |
| Keep agent memory alive | ✅ | ❌ |
| Retry from a checkpoint | ❌ | ✅ |
| Run experiments from same state | ❌ | ✅ |
| Clone environment | ❌ | ✅ |
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?
No.Terminated is the final state. To restore prior state into a new sandbox, capture a snapshot before termination and create a new sandbox from that snapshot.
Coming soon: a
restart operation that re-boots a terminated sandbox from
its last snapshot.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.