Lifecycle

Sandbox States

A sandbox can move through these lifecycle states:

State	Description
Pending	Sandbox is being scheduled or started.
Running	Sandbox is active and ready for commands or file/process operations.
Snapshotting	The sandbox is creating a filesystem snapshot.
Suspending	The sandbox is being suspended and snapshotted for later resume.
Suspended	The sandbox has been suspended and can be resumed.
Terminated	Sandbox has been stopped manually or due to a timeout.

CLI
Python
HTTP

tl sbx new
tl sbx ls
tl sbx ls --running
tl sbx ls --all

from tensorlake.sandbox import SandboxClient

client = SandboxClient()
sandbox = client.create()

info = client.get(sandbox.sandbox_id)
print(info.status)

# Create
curl -X POST https://api.tensorlake.ai/sandboxes \
  -H "Authorization: Bearer $TL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Get status
curl https://api.tensorlake.ai/sandboxes/<sandbox-id> \
  -H "Authorization: Bearer $TL_API_KEY"

Manage Sandboxes

Use the lifecycle API to create a sandbox, inspect it, list active sandboxes, and clean it up when the work is done.

CLI
Python
HTTP

# Create a sandbox
tl sbx new --cpus 1.0 --memory 512 --timeout 300

# Check status or list sandboxes
tl sbx ls
tl sbx ls --all

# Terminate the sandbox when you are done
tl sbx terminate <sandbox-id>

from tensorlake.sandbox import SandboxClient

client = SandboxClient()

sandbox = client.create(
    cpus=1.0,
    memory_mb=512,
    timeout_secs=300,
)

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

info = client.get(sandbox.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(sandbox.sandbox_id)
print("Sandbox terminated")

# Create
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": 512},
    "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"

Resource Configuration

Configure CPU and memory for each sandbox. Disk sizing is managed by the platform and is not a current tl option.

CLI
Python
HTTP

tl sbx new --cpus 2.0 --memory 1024

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

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": 1024
    }
  }'

Parameter	Type	Default	Description
`cpus`	`float`	`1.0`	Number of CPUs to allocate
`memory_mb`	`int`	`512`	Memory in megabytes

Timeouts

Set a timeout to automatically terminate sandboxes that run too long:

CLI
Python
HTTP

tl sbx new --timeout 300

sandbox = client.create(
    timeout_secs=300
)

curl -X POST https://api.tensorlake.ai/sandboxes \
  -H "Authorization: Bearer $TL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout_secs": 300}'

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

Lifecycle Commands

Create, suspend, resume, and terminate sandboxes from the CLI or public API:

CLI
HTTP
Python

# Create
tl sbx new --timeout 300

# Suspend a running sandbox
tl sbx suspend <sandbox-id>

# Resume a suspended sandbox
tl sbx resume <sandbox-id>

# Terminate a sandbox
tl sbx terminate <sandbox-id>

# Suspend
curl -X POST https://api.tensorlake.ai/sandboxes/<sandbox-id>/suspend \
  -H "Authorization: Bearer $TL_API_KEY"

# Resume
curl -X POST https://api.tensorlake.ai/sandboxes/<sandbox-id>/resume \
  -H "Authorization: Bearer $TL_API_KEY"

# Terminate
curl -X DELETE https://api.tensorlake.ai/sandboxes/<sandbox-id> \
  -H "Authorization: Bearer $TL_API_KEY"

Runtime Environment

Sandboxes run on Tensorlake’s managed Ubuntu 24.04 environment. Custom image selection is not currently part of the public sandbox workflow, so the --image flag is intentionally omitted from these docs. If you need startup setup, create the sandbox and then use command execution to run those steps explicitly.

Secrets

Secrets can be injected from the Python SDK or HTTP API:

Python
HTTP
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"]
  }'

Secrets must be pre-configured in your Tensorlake account using:

tl secrets set OPENAI_API_KEY=<your-key>

Sandbox Information

The SandboxInfo object returned by client.get() contains:

Field	Type	Description
`sandbox_id`	`str`	Unique sandbox identifier
`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

Sandbox States

Manage Sandboxes

Resource Configuration

Timeouts

Lifecycle Commands

Runtime Environment

Secrets

Sandbox Information

Learn More

Snapshots

Networking

Overview

Guides

Use Cases

​Sandbox States

​Manage Sandboxes

​Resource Configuration

​Timeouts

​Lifecycle Commands

​Runtime Environment

​Secrets

​Sandbox Information

​Learn More

Snapshots

Networking

Sandbox States

Manage Sandboxes

Resource Configuration

Timeouts

Lifecycle Commands

Runtime Environment

Secrets

Sandbox Information

Learn More