Tensorlake Documentation

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 <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

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.

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 — manually, or via timeout for ephemeral sandboxes. Final state; cannot be reversed.	—

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 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 for details.

CLI
Python
TypeScript
HTTP

# Ephemeral — runs until terminated or timed out
tl sbx create

# Named — can be suspended and resumed
tl sbx create my-env

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}")

// 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);

# 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.

CLI
Python
TypeScript
HTTP

tl sbx create --cpus 2.0 --memory 2048 --disk_mb 25600

sandbox = Sandbox.create(
    cpus=2.0,
    memory_mb=2048,
    disk_mb=25600,
)

const sandbox = await Sandbox.create({
  cpus: 2.0,
  memoryMb: 2048,
  diskMb: 25600,
});

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).

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: 1 hour on Free (unverified), 2 hours on Free (verified), and 24 hours on On-Demand (pay-as-you-go). Setting timeout_secs=0 requests the plan maximum. See tensorlake.ai/pricing for higher limits on committed plans.

CLI
Python
TypeScript
HTTP

tl sbx create --timeout 300

sandbox = Sandbox.create(timeout_secs=300)

const sandbox = await Sandbox.create({ timeoutSecs: 300 });

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 and launch sandboxes with --image. For one-off startup setup, create the sandbox and then use command execution 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.

CLI
Python
TypeScript
HTTP

# Assign a name to a running sandbox
tl sbx name <sandbox-id> my-env

# Change an existing name
tl sbx name my-env new-name

from tensorlake.sandbox import Sandbox
sandbox = Sandbox.create()
named_sbx = sandbox.update(name="my-env")
print(named_sbx.name)

import { Sandbox } from "tensorlake";

const sandbox = await Sandbox.create();
const named_sbx = await sandbox.update({ name: "my-env" });
console.log(named_sbx.name);

curl -X PATCH https://api.tensorlake.ai/sandboxes/<sandbox-id> \
  -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.

CLI
Python
TypeScript
HTTP

# 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

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()

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();

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.

Inspect and list

Use get to check a single sandbox’s status and configuration, or list to see all sandboxes in your namespace.

CLI
Python
TypeScript
HTTP

# List active sandboxes
tl sbx ls

# Running sandboxes only
tl sbx ls --running

# Include all sandboxes regardless of state
tl sbx ls --all

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}") 

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}`);
} 

# 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. Ephemeral sandboxes cannot be suspended — suspend calls on them return an error.

CLI
Python
TypeScript
HTTP

# Suspend a named sandbox (by name or ID)
tl sbx suspend my-env

# Resume it later
tl sbx resume my-env

sandbox.suspend()
sandbox.resume()

await sandbox.suspend();
await sandbox.resume();

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. Terminated is a final state and cannot be reversed. Sandboxes with timeout_secs set also terminate automatically once the timeout elapses.

CLI
Python
TypeScript
HTTP

tl sbx terminate my-env

sandbox.terminate()

await sandbox.terminate();

curl -X DELETE https://api.tensorlake.ai/sandboxes/my-env \
  -H "Authorization: Bearer $TL_API_KEY"

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.

CLI
Python
TypeScript
HTTP

# 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

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")

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();

# 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/<sandbox-id> \
  -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/<sandbox-id> \
  -H "Authorization: Bearer $TL_API_KEY"

Sandbox object reference

Sandbox

The Sandbox object returned by Sandbox.create() and Sandbox.connect() exposes the following properties. Both 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.

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

Overview

Guides

Use Cases

Lifecycle

Overview

Lifecycle states

Suspend vs. snapshot

When should I use what?

Create a sandbox

Resources

Timeout

Runtime environment

Name and reference a sandbox

Inspect and list

Suspend and resume

Terminate

End-to-end example

Sandbox object reference

Sandbox

SandboxInfo

Learn more

Snapshots

Networking

​Overview

​Lifecycle states

​Suspend vs. snapshot

​When should I use what?

​Create a sandbox

​Resources

​Timeout

​Runtime environment

​Name and reference a sandbox

​Inspect and list

​Suspend and resume

​Terminate

​End-to-end example

​Sandbox object reference

​Sandbox

​SandboxInfo

​Learn more

Snapshots

Networking

Overview

Lifecycle states

Suspend vs. snapshot

When should I use what?

Create a sandbox

Resources

Timeout

Runtime environment

Name and reference a sandbox

Inspect and list

Suspend and resume

Terminate

End-to-end example

Sandbox object reference

Sandbox

SandboxInfo

Learn more