Lifecycle

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 new`	`tl sbx new <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 new

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

from tensorlake.sandbox import SandboxClient

client = SandboxClient()

# Ephemeral sandbox — no name, cannot be suspended
ephemeral = client.create()

# Named sandbox — can be suspended and resumed
named = client.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 client.create();

// Named sandbox — can be suspended and resumed
const named = await client.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 and memory per sandbox. Disk sizing is managed by the platform.

CLI
Python
TypeScript
HTTP

tl sbx new --cpus 2.0 --memory 2048

sandbox = client.create(
    cpus=2.0,
    memory_mb=2048,
)

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

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

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.

Timeout

Set a timeout to automatically stop a sandbox that runs too long. The behavior depends on the sandbox type:

Named sandboxes — timeout triggers a suspend, preserving state for later resume.
Ephemeral sandboxes — timeout triggers termination (final state).

If timeout_secs is not set, the sandbox runs until explicitly suspended or terminated.

CLI
Python
TypeScript
HTTP

tl sbx new --timeout 300

sandbox = client.create(timeout_secs=300)

const sandbox = await client.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}'

Secrets

Inject secrets into the sandbox at creation. Secrets must be pre-configured in your Tensorlake account with tl secrets set OPENAI_API_KEY=<your-key>.

CLI
Python
TypeScript
HTTP

Not supported in the CLI.

sandbox = client.create(
    secret_names=["OPENAI_API_KEY", "DATABASE_URL"]
)

curl -X POST https://api.tensorlake.ai/sandboxes \
  -H "Authorization: Bearer $TL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_names": ["OPENAI_API_KEY", "DATABASE_URL"]
  }'

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

renamed = client.update_sandbox("sbx-123", "my-env")
print(renamed.name)

const renamed = await client.update("sbx-123", { name: "my-env" });
console.log(renamed.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 snapshot my-env
tl sbx name my-env new-name

info = client.get("my-env")
print(info.status)

sandbox = client.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 = client.update_sandbox("my-env", "new-name")
print(renamed.name)

client.delete("new-name")

const info = await client.get("my-env");
console.log(info.status);

const sandbox = client.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 client.update("my-env", { name: "new-name" });
await client.delete("new-name");

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

info = client.get("my-env")
print(info.status)
print(info.image)
print(f"{info.resources.cpus} CPUs, {info.resources.memory_mb} MB RAM")

sandboxes = client.list()
for sb in sandboxes:
    print(f"{sb.sandbox_id}: {sb.status}")

const info = await client.get("my-env");
console.log(info.status, info.image, info.resources.cpus, info.resources.memoryMb);

const sandboxes = await client.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

client.suspend("my-env")
client.resume("my-env")

await client.suspend("my-env");
await client.resume("my-env");

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

client.delete("my-env")

await client.delete("my-env");

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 new --cpus 1.0 --memory 1024 --timeout 300

# Create a named sandbox (can be suspended and resumed)
tl sbx new 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 SandboxClient

client = SandboxClient()

# Ephemeral sandbox — no name, cannot be suspended
ephemeral = client.create(
    cpus=1.0,
    memory_mb=1024,
    timeout_secs=300,
)

# Named sandbox — can be suspended and resumed
named = client.create(
    name="my-env",
    cpus=1.0,
    memory_mb=1024,
    timeout_secs=300,
)

print(f"Sandbox ID: {named.sandbox_id}")
print(f"Status: {named.status}")

info = client.get(named.sandbox_id)
print(f"Image: {info.image}")
print(f"Resources: {info.resources.cpus} CPUs, {info.resources.memory_mb} MB RAM")

sandboxes = client.list()
for sb in sandboxes:
    print(f"{sb.sandbox_id}: {sb.status}")

client.delete(named.sandbox_id)
client.delete(ephemeral.sandbox_id)
print("Sandboxes terminated")

const ephemeral = await client.create({
  cpus: 1.0,
  memoryMb: 1024,
  timeoutSecs: 300,
});

const named = await client.create({
  name: "my-env",
  cpus: 1.0,
  memoryMb: 1024,
  timeoutSecs: 300,
});

console.log(named.sandboxId, named.status);

const info = await client.get(named.sandboxId);
console.log(info.image, info.resources.cpus, info.resources.memoryMb);

const sandboxes = await client.list();
for (const sandbox of sandboxes) {
  console.log(`${sandbox.sandboxId}: ${sandbox.status}`);
}

await client.delete(named.sandboxId);
await client.delete(ephemeral.sandboxId);

# 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 connect() and create_and_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 = client.connect(identifier="my-env")
print(sandbox.sandbox_id)  # "s7jus08qec4axzgbpq76h"  ← UUID
print(sandbox.name)        # "my-env"                  ← name

SandboxInfo

The SandboxInfo object returned by client.get() 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
`secret_names`	`list[str]`	Injected secret names
`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

Overview

Lifecycle states

Suspend vs. snapshot

When should I use what?

Create a sandbox

Resources

Timeout

Secrets

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

Guides

Use Cases

​Overview

​Lifecycle states

​Suspend vs. snapshot

​When should I use what?

​Create a sandbox

​Resources

​Timeout

​Secrets

​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

Secrets

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