> ## 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. # Lifecycle > Sandbox states, creation, suspend/resume, and cleanup ## Overview Sandboxes come in two flavors: * **Ephemeral**: no name. Runs until you terminate it or it times out. Cannot be suspended. * **Named**: a name given at creation (or assigned later). Supports suspend and resume, so you can pause between tasks and pick up exactly where you left off. | | Ephemeral | Named | | -------------------- | ------------------------------------ | ---------------------------------------- | | **Created with** | `tl sbx create` | `tl sbx create ` | | **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 | ## Lifecycle states Every sandbox moves through the states below. Create starts the sandbox in `Pending`; from `Running`, you can suspend (named only), snapshot, or terminate. Ephemeral sandboxes follow the same flow but skip `Suspending`/`Suspended`. ```mermaid theme={null} stateDiagram-v2 [*] --> Pending: • create
• restore from snapshot Pending --> Running Running --> Snapshotting: snapshot Snapshotting --> Running: snapshot complete Running --> Suspending: named sandbox
• suspend
• timeout Suspending --> Suspended Suspended --> Running: resume Running --> Terminated: • terminate
• timeout (ephemeral) Suspended --> Terminated: terminate Terminated --> Pending: restart
(within 48 hours) Terminated --> [*] style Suspending fill:#E8F4FF,stroke:#1D70B8,color:#0B3C6F,stroke-width:2px style Suspended fill:#E8F4FF,stroke:#1D70B8,color:#0B3C6F,stroke-width:2px ``` | State | What it means | How you exit it | | ---------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Pending** | Sandbox is being scheduled and booted. Not yet ready to accept commands. | Transitions to `Running` automatically once boot completes. | | **Running** | Sandbox is live and accepting commands, file operations, and process execution. Snapshots can be taken from this state. | Call `suspend` (named only) or `terminate`. | | **Snapshotting** | A reusable snapshot artifact is being captured from the sandbox's filesystem, memory, and running processes. | Returns to `Running` when capture completes. | | **Suspending** | Named sandbox is being paused in place. Triggered by manual suspend or by `timeout_secs` elapsing. | Transitions to `Suspended` automatically. | | **Suspended** | Named sandbox is paused. Consumes no compute; state is preserved for resume under the same sandbox ID. | Call `resume` to return to `Running`, or `terminate` to end it. | | **Terminated** | Sandbox has stopped, either manually or via timeout for ephemeral sandboxes. | Call `restart` within 48 hours of termination to boot it again under the same ID and name; after that the sandbox is gone. | ## Suspend vs. snapshot Suspend and 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. Suspend/resume is covered on this page; see [Snapshots](/sandboxes/snapshots) for save-and-restore. ### When should I use what? | 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 | ❌ | ✅ | ## Create a sandbox Create an ephemeral sandbox by calling create with no name. Add a name to make the sandbox persistent and eligible for suspend/resume. You can also boot a sandbox from an existing snapshot to restore a previously captured filesystem, memory, and running processes. See [Restoring from a snapshot](/sandboxes/snapshots#restoring-from-a-snapshot) for details. ```bash theme={null} # Ephemeral: runs until terminated or timed out tl sbx create # Named: can be suspended and resumed tl sbx create my-env ``` ```python theme={null} from tensorlake.sandbox import Sandbox # Ephemeral sandbox: no name, cannot be suspended ephemeral = Sandbox.create() # Named sandbox: can be suspended and resumed named = Sandbox.create(name="my-env") print(f"Sandbox ID: {named.sandbox_id}") print(f"Status: {named.status}") ``` ```typescript theme={null} // Ephemeral sandbox: no name, cannot be suspended const ephemeral = await Sandbox.create(); // Named sandbox: can be suspended and resumed const named = await Sandbox.create({ name: "my-env" }); console.log(named.sandboxId, named.status); ``` ```bash theme={null} # Ephemeral curl -X POST https://api.tensorlake.ai/sandboxes \ -H "Authorization: Bearer $TL_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' # Named curl -X POST https://api.tensorlake.ai/sandboxes \ -H "Authorization: Bearer $TL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "my-env"}' ``` ### Resources Configure CPU, memory, and disk size per sandbox. These are fixed when the sandbox is created and cannot be changed afterwards. Create a new sandbox if you need different resources. ```bash theme={null} tl sbx create --cpus 2.0 --memory 2048 --disk_mb 25600 ``` ```python theme={null} sandbox = Sandbox.create( cpus=2.0, memory_mb=2048, disk_mb=25600, ) ``` ```typescript theme={null} const sandbox = await Sandbox.create({ cpus: 2.0, memoryMb: 2048, diskMb: 25600, }); ``` ```bash theme={null} curl -X POST https://api.tensorlake.ai/sandboxes \ -H "Authorization: Bearer $TL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "resources": { "cpus": 2.0, "memory_mb": 2048, "disk_mb": 25600 } }' ``` | Parameter | Type | Default | Description | | ----------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cpus` | `float` | `1.0` | Number of CPUs to allocate | | `memory_mb` | `int` | `1024` | Memory in megabytes. Must be between 1024–8192 MB per CPU core. | | `disk_mb` | `int` | `10240` | Root filesystem size in MiB. Defaults to 10240 (10 GiB) when omitted. Must be between 10240 and 102400 (10–100 GiB). The CLI accepts `--disk_mb` in MiB. Accepted for fresh creates. With `image`, `disk_mb` can be used to grow the root disk at create time (growth-only). With `snapshot_id` from a filesystem snapshot, `disk_mb` can also be used to grow the root disk at restore time (growth-only). | See [Pricing and billing](/platform/billing) for concurrency, session duration, and metered rates. ### Timeout `timeout_secs` is an **idle threshold**, not a wall-clock lifetime. A sandbox stays running as long as it is handling traffic through the sandbox proxy: an open SSH session, a connected WebSocket PTY, a request to an exposed user port, or any SDK/CLI call. Once no proxied traffic has been in flight for `timeout_secs`, the sandbox times out. What happens next depends on the sandbox type: * **Named sandboxes**: suspend on timeout. Filesystem, memory, and running processes are preserved so you can resume later under the same name. * **Ephemeral sandboxes**: terminate on timeout (final state). The sandbox cannot be resumed. If `timeout_secs` is not set, it goes with the default value which is `600` sec (10 minutes). The maximum allowed `timeout_secs` depends on your plan: **2 hours** on Free, **24 hours** with Usage Credits, and unlimited on Pro and Enterprise. Setting `timeout_secs=0` requests the plan maximum. See [Pricing and billing](/platform/billing) for the full plan comparison. ```bash theme={null} tl sbx create --timeout 300 ``` ```python theme={null} sandbox = Sandbox.create(timeout_secs=300) ``` ```typescript theme={null} const sandbox = await Sandbox.create({ timeoutSecs: 300 }); ``` ```bash theme={null} curl -X POST https://api.tensorlake.ai/sandboxes \ -H "Authorization: Bearer $TL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"timeout_secs": 300}' ``` ### Runtime environment Sandboxes run on Tensorlake's managed Ubuntu 24.04 environment by default. If you need reusable setup or preinstalled dependencies, create a [sandbox image](/sandboxes/images) and launch sandboxes with `--image`. For one-off startup setup, create the sandbox and then use [command execution](/sandboxes/commands) to run those steps explicitly. ## Name and reference a sandbox You can assign or update a sandbox's name after it is created. This is how you convert an ephemeral sandbox into a named one so it becomes eligible for suspend and resume. ```bash theme={null} # Assign a name to a running sandbox tl sbx name my-env # Change an existing name tl sbx name my-env new-name ``` ```python theme={null} from tensorlake.sandbox import Sandbox sandbox = Sandbox.create() named_sbx = sandbox.update(name="my-env") print(named_sbx.name) ``` ```typescript theme={null} import { Sandbox } from "tensorlake"; const sandbox = await Sandbox.create(); const named_sbx = await sandbox.update({ name: "my-env" }); console.log(named_sbx.name); ``` ```bash theme={null} curl -X PATCH https://api.tensorlake.ai/sandboxes/ \ -H "Authorization: Bearer $TL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "my-env"}' ``` Once a sandbox has a name, you can use either the name or the UUID anywhere a sandbox identifier is accepted. Use `connect` to get an operable handle from either identifier. ```bash theme={null} # All of these work with either the ID or the name tl sbx exec my-env python main.py tl sbx ssh my-env tl sbx cp ./file.py my-env:/workspace/file.py tl sbx suspend my-env tl sbx resume my-env tl sbx terminate my-env tl sbx checkpoint my-env tl sbx name my-env new-name ``` ```python theme={null} info = Sandbox.connect("my-env") print(info.status) sandbox = Sandbox.connect(identifier="my-env") print(sandbox.sandbox_id) # server UUID, e.g. "s7jus08qec4axzgbpq76h" print(sandbox.name) # "my-env" result = sandbox.run("python", ["main.py"]) print(result.stdout) renamed = sandbox.update(name= "new-name") print(renamed.name) sandbox.terminate() ``` ```typescript theme={null} const info = await Sandbox.connect("my-env"); console.log(info.status); const sandbox = Sandbox.connect("my-env"); console.log(sandbox.sandboxId); // server UUID console.log(sandbox.name); // "my-env" const result = await sandbox.run("python", { args: ["main.py"] }); console.log(result.stdout); await sandbox.update({ name: "new-name" }); await sandbox.terminate(); ``` ```bash theme={null} curl https://api.tensorlake.ai/sandboxes/my-env \ -H "Authorization: Bearer $TL_API_KEY" ``` Authenticated requests can use either the sandbox ID or sandbox name. Unauthenticated proxy requests can also use sandbox names for exposed user ports when `allow_unauthenticated_access` is enabled. The management URL on port `9501` still requires authentication. ## Get or create a named sandbox Use `get_or_create` when your application has a stable name, such as one derived from an agent session ID, and should reuse the same sandbox across calls. It connects to the named sandbox when it exists or creates it when the name is free. Concurrent callers using the same name converge on the same sandbox instead of failing with a name conflict. | Intent | Method | | ------------------------------------------ | ----------------- | | Always create a new sandbox | `create()` | | Connect only if the sandbox already exists | `connect()` | | Connect by name or create on first use | `get_or_create()` | ```python theme={null} from tensorlake.sandbox import Sandbox session_id = "session-123" sandbox = Sandbox.get_or_create( f"agent-{session_id}", timeout_secs=600, ) ``` ```typescript theme={null} import { Sandbox } from "tensorlake"; const sessionId = "session-123"; const sandbox = await Sandbox.getOrCreate(`agent-${sessionId}`, { timeoutSecs: 600, }); ``` By default, the call resumes a suspended sandbox and returns it once it is usable. Set `resume=False` in Python or `resume: false` in TypeScript if you want the suspended handle without resuming it; call `resume()` before running commands against that handle. Creation options such as the image and resource allocation are used only when the name is free. If the sandbox already exists, `get_or_create` returns it with its existing configuration. The method does not accept `pool_id` (`poolId` in TypeScript); see [Pools](/sandboxes/pools) for the create-then-name workflow. This is an SDK convenience API composed from existing sandbox lifecycle operations. It does not add a separate CLI command or HTTP endpoint. See [`get_or_create` in the SDK Reference](/sandboxes/sdk-reference#get-or-create) for the complete behavior and async Python usage. ## Inspect and list Use `get` to check a single sandbox's status and configuration, or `list` to see all sandboxes in your namespace. ```bash theme={null} # List active sandboxes tl sbx ls # Running sandboxes only tl sbx ls --running # Include all sandboxes regardless of state tl sbx ls --all ``` ```python theme={null} from tensorlake.sandbox import Sandbox # Connect returns a Sandbox handle (not SandboxInfo) sandbox = Sandbox.connect("my-env") print(sandbox.status) # property: fetches fresh from server print(sandbox.name) print(sandbox.sandbox_id) # Get the full metadata (image, resources, timeouts, etc.) info = sandbox.info() print(info.image) print(f"{info.resources.cpus} CPUs, {info.resources.memory_mb} MB RAM") # List all sandboxes in the namespace for sb in Sandbox.list(): print(f"{sb.sandbox_id}: {sb.status}") ``` ```typescript theme={null} import { Sandbox } from "tensorlake"; // Connect returns a Sandbox handle (not SandboxInfo) const sandbox = await Sandbox.connect("my-env"); console.log(await sandbox.status()); // status is an async method in TS console.log(sandbox.name); // name is a getter console.log(sandbox.sandboxId); // Get the full metadata (image, resources, timeouts, etc.) const info = await sandbox.info(); console.log(info.image, info.resources.cpus, info.resources.memoryMb); // List all sandboxes in the namespace const sandboxes = await Sandbox.list(); for (const sb of sandboxes) { console.log(`${sb.sandboxId}: ${sb.status}`); } ``` ```bash theme={null} # Get one sandbox (by name or ID) curl https://api.tensorlake.ai/sandboxes/my-env \ -H "Authorization: Bearer $TL_API_KEY" # List all sandboxes curl https://api.tensorlake.ai/sandboxes \ -H "Authorization: Bearer $TL_API_KEY" ``` ## Suspend and resume Suspend a running named sandbox to pause it in place, then resume the same sandbox later exactly where it left off. Suspend and resume do not create a reusable artifact. For that, use [Snapshots](/sandboxes/snapshots). Ephemeral sandboxes cannot be suspended, and suspend calls on them return an error. ```bash theme={null} # Suspend a named sandbox (by name or ID) tl sbx suspend my-env # Resume it later tl sbx resume my-env ``` ```python theme={null} sandbox.suspend() sandbox.resume() ``` ```typescript theme={null} await sandbox.suspend(); await sandbox.resume(); ``` ```bash theme={null} curl -X POST https://api.tensorlake.ai/sandboxes/my-env/suspend \ -H "Authorization: Bearer $TL_API_KEY" curl -X POST https://api.tensorlake.ai/sandboxes/my-env/resume \ -H "Authorization: Bearer $TL_API_KEY" ``` ## Terminate Terminate a sandbox when the work is done. Sandboxes with `timeout_secs` set also terminate automatically once the timeout elapses. A terminated sandbox can be brought back with [restart](#restart-a-terminated-sandbox) for up to 48 hours; after that it is gone. ```bash theme={null} tl sbx terminate my-env ``` ```python theme={null} sandbox.terminate() ``` ```typescript theme={null} await sandbox.terminate(); ``` ```bash theme={null} curl -X DELETE https://api.tensorlake.ai/sandboxes/my-env \ -H "Authorization: Bearer $TL_API_KEY" ``` ## Restart a terminated sandbox Restart boots a terminated sandbox again under its original ID and name. Use it to recover a sandbox that was terminated by mistake, or one that ended up terminated because it could not be resumed. Terminated sandboxes stay restartable for 48 hours after termination. ```bash theme={null} curl -X POST https://api.tensorlake.ai/sandboxes/my-env/restart \ -H "Authorization: Bearer $TL_API_KEY" ``` * Only terminated sandboxes can be restarted. To wake a suspended sandbox, use [resume](#suspend-and-resume) instead. * When the sandbox has a usable snapshot, the restart restores from the most recent one, so filesystem and memory state come back. When no snapshot exists, the sandbox cold boots from its image with a fresh filesystem. * The restarted sandbox re-enters `Pending` and boots like a newly created sandbox. * If another sandbox has claimed the same name since termination, the restart fails with `409 Conflict`. See the [Restart Sandbox API reference](/api-reference/v2/sandboxes/restart) for full details. ## End-to-end example If you want a single example that creates a sandbox, inspects it, lists sandboxes, and cleans up when finished, use one of the sessions below. ```bash theme={null} # Create an ephemeral sandbox (no name, cannot be suspended) tl sbx create --cpus 1.0 --memory 1024 --timeout 300 # Create a named sandbox (can be suspended and resumed) tl sbx create my-env --cpus 1.0 --memory 1024 --timeout 300 # Check status or list sandboxes tl sbx ls tl sbx ls --all # Terminate the sandbox when you are done (by name or ID) tl sbx terminate my-env ``` ```python theme={null} from tensorlake.sandbox import Sandbox # Ephemeral sandbox: no name, cannot be suspended ephemeral = Sandbox.create( cpus=1.0, memory_mb=1024, disk_mb=10240, timeout_secs=300, ) # Named sandbox: can be suspended and resumed named = Sandbox.create( name="my-env", cpus=1.0, memory_mb=1024, disk_mb=10240, timeout_secs=300, ) print(f"Sandbox ID: {named.sandbox_id}") print(f"Status: {named.status}") # Get the full metadata (image, resources, timeouts, etc.) info = sandbox.info() print(f"Image: {info.image}") print(f"Resources: {info.resources.cpus} CPUs, {info.resources.memory_mb} MB RAM") sandboxes = Sandbox.list() for sb in sandboxes: print(f"{sb.sandbox_id}: {sb.status}") sandbox.terminate() print("Sandboxes terminated") ``` ```typescript theme={null} import { Sandbox } from "tensorlake"; const ephemeral = await Sandbox.create({ cpus: 1.0, memoryMb: 1024, diskMb: 10240, timeoutSecs: 300, }); const named = await Sandbox.create({ name: "my-env", cpus: 1.0, memoryMb: 1024, diskMb: 10240, timeoutSecs: 300, }); console.log(named.sandboxId, named.status); # Get the full metadata (image, resources, timeouts, etc.) const info = await sandbox.info(); console.log(info.image, info.resources.cpus, info.resources.memoryMb); const sandboxes = await Sandbox.list(); for (const sandbox of sandboxes) { console.log(`${sandbox.sandboxId}: ${sandbox.status}`); } await sandbox.terminate(); ``` ```bash theme={null} # Create an ephemeral sandbox curl -X POST https://api.tensorlake.ai/sandboxes \ -H "Authorization: Bearer $TL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "resources": {"cpus": 1.0, "memory_mb": 1024}, "timeout_secs": 300 }' # Create a named sandbox (supports suspend/resume) curl -X POST https://api.tensorlake.ai/sandboxes \ -H "Authorization: Bearer $TL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "my-env", "resources": {"cpus": 1.0, "memory_mb": 1024}, "timeout_secs": 300 }' # Get one sandbox curl https://api.tensorlake.ai/sandboxes/ \ -H "Authorization: Bearer $TL_API_KEY" # List all sandboxes curl https://api.tensorlake.ai/sandboxes \ -H "Authorization: Bearer $TL_API_KEY" # Delete curl -X DELETE https://api.tensorlake.ai/sandboxes/ \ -H "Authorization: Bearer $TL_API_KEY" ``` ## Sandbox object reference ### Sandbox The `Sandbox` object returned by `Sandbox.create()`, `Sandbox.connect()`, and `Sandbox.get_or_create()` exposes the following properties. Both properties are resolved from the server on first access and cached for the lifetime of the object. | Property (Python) | Property (TypeScript) | Type | Description | | ----------------- | --------------------- | ------------- | -------------------------------------------------------------------------------------- | | `sandbox_id` | `sandboxId` | `str` | Server-assigned UUID. Always a UUID, never a name, even if you connected using a name. | | `name` | `name` | `str \| None` | Human-readable name, or `None` for ephemeral sandboxes. | ```python theme={null} sandbox = Sandbox.connect(identifier="my-env") print(sandbox.sandbox_id) # "s7jus08qec4axzgbpq76h" ← UUID print(sandbox.name) # "my-env" ← name ``` ### SandboxInfo The `SandboxInfo` object returned by `Sandbox.info()` and `Sandbox.list()` contains: | Field | Type | Description | | --------------- | ------------------------ | ------------------------------------------------------ | | `sandbox_id` | `str` | Unique sandbox identifier | | `name` | `str \| None` | Name of the sandbox, or `None` for ephemeral sandboxes | | `namespace` | `str` | Namespace the sandbox belongs to | | `status` | `str` | Current lifecycle state | | `image` | `str` | Container image used | | `resources` | `ContainerResourcesInfo` | CPU and memory allocation | | `timeout_secs` | `int` | Timeout in seconds | | `entrypoint` | `list[str]` | Custom entrypoint command | | `created_at` | `datetime \| None` | Creation timestamp | | `terminated_at` | `datetime \| None` | Termination timestamp | ## Learn more Save and restore sandbox filesystem, memory, and running processes. Control internet access and blocked destinations.