Tensorlake Documentation

This page is the runtime API surface of the Sandbox SDK in one place. It maps the Python and TypeScript sandbox-management APIs you’ll use to create sandboxes, execute work inside them, manage files and processes, and interact with desktop sandboxes. Each detail page linked below expands on the same APIs with longer examples and edge cases.

All method names below use the Python form. The TypeScript SDK mirrors them in camelCase (start_process → startProcess, read_file → readFile, memory_mb → memoryMb, etc.). The same JavaScript runtime API is used from Node.js.

This page focuses on the sandbox runtime SDK surface. Related interfaces documented elsewhere include the CLI and HTTP API, the image-building DSLs in Build and Import Images, and the browser/VNC integration details in Computer Use.

Every method below is also available as an async-native variant on AsyncSandbox in Python: same names and parameters, just awaited. See the Async SDK page for usage. The TypeScript SDK is already Promise-based, so the methods shown in the TypeScript tabs are the async API.

Sandbox

Sandbox is the top-level entry point for managing sandboxes in your namespace. Use Sandbox.create() to start a sandbox, Sandbox.connect() to reconnect to an existing sandbox by ID or name, or Sandbox.get_or_create() when a deterministic name should resolve to one reusable sandbox.

Python
TypeScript

from tensorlake.sandbox import Sandbox

# SDK authentication comes from TENSORLAKE_API_KEY or api_key=...

import { Sandbox } from "@tensorlakeai/tensorlake";

// SDK authentication comes from TENSORLAKE_API_KEY or apiKey

See Authentication for the full auth flow.

Create

Create a sandbox. Omit name for an ephemeral sandbox (cannot be suspended); pass name to create a named sandbox that supports suspend/resume. Returns a connected Sandbox handle (blocks until the sandbox is running).

Parameter	Type	Default	Description
`name`	`str \| None`	`None`	Immutable name set at creation. Required for suspend/resume.
`auto_resume` / `autoResume`	`bool \| None`	`None` (server default `True`)	Whether proxy traffic may wake a suspended sandbox. `False` requires a named sandbox and does not suspend it.
`cpus`	`float`	`1.0`	Number of CPUs to allocate.
`memory_mb`	`int`	`1024`	Memory in megabytes. 1024–8192 MB per CPU core.
`timeout_secs`	`int`	`600`	Auto-suspend (named) or auto-terminate (ephemeral) after this many seconds.
`image`	`str \| None`	platform default	Name or ID of a prebuilt sandbox image.
`snapshot_id`	`str \| None`	`None`	Restore from a snapshot instead of booting a fresh VM.
`entrypoint`	`list[str] \| None`	`None`	Custom entrypoint command.
`allow_internet_access`	`bool`	`True`	Allow outbound internet traffic (see Networking).
`allow_out` / `deny_out`	`list[str] \| None`	`None`	Outbound destination allow/deny lists.
`wait`	`bool`	`True`	`False` returns a `PendingSandbox` at once instead of waiting for the sandbox to run.
`max_pending_secs`	`int \| None`	`None`	Longest the sandbox may wait for capacity before the server fails it with `no_capacity`. `0` fails at once if it cannot be placed. Unset waits indefinitely.
`request_timeout`	`float \| None`	client default (300)	Seconds to wait for the sandbox to run before raising `SandboxPending`. The sandbox is not deleted.
`cancel_on_timeout`	`bool`	`False`	Delete the sandbox when `request_timeout` runs out while it is still pending.

The auto_resume option also applies to SandboxClient.create(), create_and_connect(), and Sandbox.get_or_create() (TypeScript: autoResume, createAndConnect(), and getOrCreate()). For get-or-create, creation options apply only to a new sandbox; the default resume=True explicitly resumes an existing one regardless of its flag. Pass resume=False to attach without waking it. Python AsyncSandbox and AsyncSandboxClient accept the same option. To expose user ports for inbound traffic, call sandbox.update(exposed_ports=..., allow_unauthenticated_access=...) after create().

Python
TypeScript

sandbox = Sandbox.create(
    name="my-env",
    cpus=2.0,
    memory_mb=4096,
    timeout_secs=1800,
)
print(sandbox.sandbox_id, sandbox.status)

const sandbox = await Sandbox.create({
  name: "my-env",
  cpus: 2.0,
  memoryMb: 4096,
  timeoutSecs: 1800,
});

Create and connect

Sandbox.create() creates a sandbox and returns a live Sandbox handle you can immediately run commands against.

Python
TypeScript

sandbox = Sandbox.create(cpus=2.0, memory_mb=2048)
result = sandbox.run("python", ["-c", "print('hello')"])
print(result.stdout)
# Context manager terminates the sandbox on exit

const sandbox = await Sandbox.create({ cpus: 2.0, memoryMb: 2048 });
try {
  const result = await sandbox.run("python", { args: ["-c", "print('hello')"] });
  console.log(result.stdout);
} finally {
  await sandbox.terminate();
}

Create without waiting

Sandbox.create(..., wait=False) returns a PendingSandbox as soon as the sandbox is durable. ready() polls every two seconds until it runs and returns a connected Sandbox; status() fetches the current SandboxInfo once. When ready() runs out of time it raises SandboxPending and the sandbox keeps its place in the queue. See Non-blocking Sandbox Creation.

`ready()` parameter	Type	Default	Description
`timeout`	`float \| None`	client request timeout	Seconds to wait.
`poll_interval`	`float`	`2.0`	Seconds between polls.
`cancel_on_timeout`	`bool`	`False`	Delete the sandbox if the wait runs out.

Python
TypeScript

pending = Sandbox.create(cpus=4, memory_mb=8192, wait=False, max_pending_secs=2700)
print(pending.sandbox_id, pending.pending_reason)

try:
    sandbox = pending.ready(timeout=1800)
except SandboxPending as still_queued:
    print(still_queued.sandbox_id, still_queued.pending_reason)

const pending = await Sandbox.create({ cpus: 4, memoryMb: 8192, wait: false, maxPendingSecs: 2700 });
console.log(pending.sandboxId, pending.pendingReason);

try {
  const sandbox = await pending.ready({ timeout: 1800 });
} catch (err) {
  if (err instanceof SandboxPending) console.log(err.sandboxId, err.pendingReason);
}

Get or create

Return the sandbox bound to a name, creating it on first use. This is the recommended factory for agent sessions that derive a sandbox name from a stable session ID.

Sandbox state	Behavior
No sandbox has the name	Creates a named sandbox with the supplied configuration and waits until it is running.
Running	Connects to and returns the existing sandbox.
Pending	Waits until the existing sandbox is running.
Suspended or suspending	Waits as needed, then resumes the sandbox before returning it. Pass `resume=False` to skip the resume.
Another caller claims the name concurrently	Connects to the winning caller’s sandbox instead of returning the create conflict.

The name argument is required and must be unique within the namespace. All other creation arguments, such as image, cpus, and memory_mb, apply only when a new sandbox is created. An existing sandbox keeps its current configuration.

Python
Python (async)
TypeScript

session_id = "session-123"

sandbox = Sandbox.get_or_create(
    f"agent-{session_id}",
    cpus=2.0,
    memory_mb=4096,
)

from tensorlake.sandbox import AsyncSandbox

session_id = "session-123"
sandbox = await AsyncSandbox.get_or_create(
    f"agent-{session_id}",
    cpus=2.0,
    memory_mb=4096,
)

const sessionId = "session-123";

const sandbox = await Sandbox.getOrCreate(`agent-${sessionId}`, {
  cpus: 2.0,
  memoryMb: 4096,
});

get_or_create() does not accept pool_id (poolId in TypeScript). A pool claim cannot assign a name during creation, so a later call could not find the claimed sandbox by name. Names cannot be assigned later through sandbox.update().

Connect

Get a Sandbox handle for an existing sandbox (by ID or name) without creating a new one. If the sandbox is still pending, connect() waits for it to run, up to request_timeout, and raises SandboxPending if it does not. Use this to rejoin a named sandbox after resume, or to operate on a sandbox a different process created.

Python
TypeScript

sandbox = Sandbox.connect("my-env")
print(sandbox.sandbox_id)  # always UUID, even if you connected by name
print(sandbox.name)        # "my-env"

const sandbox = Sandbox.connect("my-env");

List and get

Sandbox.connect() attaches to a single sandbox by ID or name. To enumerate all sandboxes in your namespace, use Sandbox.list().

Python
TypeScript

sandbox = Sandbox.connect("my-env")
print(sandbox.sandbox_id, sandbox.name, sandbox.status)

for sb in Sandbox.list():
    print(sb.sandbox_id, sb.status)

const sandbox = await Sandbox.connect("my-env");
console.log(sandbox.sandboxId, sandbox.name, sandbox.status);

Update

Use sandbox.update() to change automatic resume, exposed user ports, unauthenticated access, or the egress network policy. Names are immutable; set name when creating the sandbox.

Parameter	Type	Default	Description
`auto_resume` / `autoResume`	`bool \| None`	`None` (unchanged)	Whether proxy traffic may wake a suspended sandbox. `False` requires a named sandbox. Accepted while suspended without waking it.
`allow_unauthenticated_access`	`bool \| None`	`None`	Whether exposed user ports accept traffic without Tensorlake authentication.
`exposed_ports`	`list[int] \| None`	`None`	User ports routable through the sandbox proxy. Port `9501` is reserved.
`network`	`NetworkConfig \| ClearNetworkPolicy \| None`	`None`	Omit to keep the policy, pass a `NetworkConfig` to replace it, or pass `CLEAR_NETWORK_POLICY` (Python) / `null` (TypeScript) to clear it.

These examples disable automatic resume on an existing named sandbox and inspect the returned metadata:

Python
TypeScript

from tensorlake.sandbox import SandboxClient

client = SandboxClient()
info = client.update_sandbox("parked-agent", auto_resume=False)
print(info.auto_resume)

import { SandboxClient } from "@tensorlakeai/tensorlake";

const client = new SandboxClient();
const info = await client.update("parked-agent", { autoResume: false });
console.log(info.autoResume);

If you already have a handle, use sandbox.update(auto_resume=False) or await sandbox.update({ autoResume: false }). Omission preserves the setting; explicit False disables it. Updating this flag neither suspends a running sandbox nor wakes a suspended one. A resources resize PATCH cannot include this or any other setting. Read the current flag with sandbox.info().auto_resume or (await sandbox.info()).autoResume. The client equivalents are client.get(sandbox_id).auto_resume and (await client.get(sandboxId)).autoResume. When proxy traffic targets a suspended sandbox with automatic resume disabled, RemoteAPIError reports status_code (statusCode in TypeScript) 409 and code SANDBOX_AUTO_RESUME_DISABLED. Explicitly resume before retrying, or enable automatic resume with an update. See Keep a sandbox suspended for a complete example.

Suspend and resume

Pause a running named sandbox in place; resume it later under the same ID with its memory, filesystem, and running processes intact. Ephemeral sandboxes return an error on suspend.

Python
TypeScript

sandbox.suspend()
sandbox.resume()

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

Explicit resume works even when auto_resume is False and does not change that setting. To re-enable proxy-triggered resume, call update(auto_resume=True) (update({ autoResume: true }) in TypeScript). See Keep a sandbox suspended.

Terminate

terminate() ends the sandbox permanently. Terminated is a final state and cannot be reversed.

Python
TypeScript

sandbox.terminate()

await sandbox.terminate();

See Lifecycle for the full state machine.

Expose and unexpose ports

Route public internet traffic to services listening on user ports inside the sandbox. Requests arrive at https://<port>-<sandbox-id-or-name>.sandbox.tensorlake.ai. Port exposure is just a sandbox.update() call: pass exposed_ports and (optionally) allow_unauthenticated_access. Pass exposed_ports=[] to remove all exposed ports.

Python
TypeScript

sandbox.update(exposed_ports=[8080], allow_unauthenticated_access=False)
sandbox.update(exposed_ports=[])  # remove all

await sandbox.update({ exposedPorts: [8080], allowUnauthenticatedAccess: false });
await sandbox.update({ exposedPorts: [] }); // remove all

See Networking for authenticated vs. unauthenticated access and how clients reach user ports.

Snapshot and restore

Capture a reusable artifact of the sandbox (filesystem + memory + running processes). Restore by passing snapshot_id to Sandbox.create().

Python
TypeScript

snapshot = sandbox.checkpoint()

# Restore into a fresh sandbox
restored = Sandbox.create(snapshot_id=snapshot.snapshot_id)

# Manage snapshots
sandbox.list_snapshots()
Sandbox.get_snapshot(snapshot.snapshot_id)
Sandbox.delete_snapshot(snapshot.snapshot_id)

const snapshot = await sandbox.checkpoint();

const restored = await Sandbox.create({ snapshotId: snapshot.snapshotId });

await sandbox.listSnapshots();
await Sandbox.getSnapshot(snapshot.snapshotId);
await Sandbox.deleteSnapshot(snapshot.snapshotId);

Suspend pauses this sandbox; snapshot captures a reusable artifact you restore into a new sandbox. See Snapshots.

Sandbox handle

The Sandbox object returned by Sandbox.create(), Sandbox.connect(), or Sandbox.get_or_create() is how you execute work inside a running sandbox. All methods below target a single live sandbox.

Property (Python)	Property (TypeScript)	Type	Description
`sandbox_id`	`sandboxId`	`str`	Server-assigned UUID.
`name`	`name`	`str \| None`	Human-readable name, or `None` for ephemeral.

Run a command

run() is the short-lived foreground execution primitive: send a command, wait for it to exit, receive captured output. Use it for the common case of “do this one thing and give me the result.”

Python
TypeScript

result = sandbox.run("python", ["-c", "print('hello')"], timeout=30)
print(result.stdout)
print(result.stderr)
print(result.exit_code)

const result = await sandbox.run("python", {
  args: ["-c", "print('hello')"],
  timeout: 30,
});
console.log(result.stdout, result.stderr, result.exitCode);

Pass env={"KEY": "value"} (Python) or env: { KEY: "value" } (TypeScript) for per-command environment variables. See Environment Variables. See Commands & Processes for streaming, multi-step shell pipelines, and error handling.

Background processes

For long-running or concurrent work, start a process and keep the handle so you can monitor, stream output, and signal it.

Python
TypeScript

proc = sandbox.start_process("python", ["-m", "http.server", "8080"])
print(proc.pid)

for p in sandbox.list_processes():
    print(p.pid, p.command, p.status)

for event in sandbox.follow_output(proc.pid):
    print(event.line, end="")

import signal
sandbox.send_signal(proc.pid, signal.SIGTERM)

const proc = await sandbox.startProcess("python", { args: ["-m", "http.server", "8080"] });

for (const p of await sandbox.listProcesses()) {
  console.log(p.pid, p.command, p.status);
}

for await (const event of sandbox.followOutput(proc.pid)) {
  console.log(event.line);
}

await sandbox.sendSignal(proc.pid, 15); // SIGTERM
await sandbox.killProcess(proc.pid);    // SIGKILL

Writing to stdin

Drive a process interactively from code by writing bytes to its stdin, then closing the stream when you’re done.

Python
TypeScript

proc = sandbox.start_process("python", ["-c", "import sys; print(sys.stdin.read())"])
sandbox.write_stdin(proc.pid, b"hello from stdin\n")
sandbox.close_stdin(proc.pid)

const proc = await sandbox.startProcess("python", {
  args: ["-c", "import sys; print(sys.stdin.read())"],
});
await sandbox.writeStdin(proc.pid, new TextEncoder().encode("hello from stdin\n"));
await sandbox.closeStdin(proc.pid);

See Commands & Processes for the full API.

PTY sessions

Open an interactive terminal inside the sandbox. The PTY is created over HTTPS; terminal I/O then moves over a WebSocket attached to the session.

Python
TypeScript

pty = sandbox.create_pty(
    command="bash",
    cols=120,
    rows=40,
    env={"PS1": "sandbox$ "},
)
# `pty` is a connected Pty handle - see PTY Sessions for send_input / resize / wait.
# Reconnect later from session_id and token:
reattached = sandbox.connect_pty(pty.session_id, pty.token)

const pty = await sandbox.createPty({
  command: "bash",
  cols: 120,
  rows: 40,
});

See PTY Sessions for the wire protocol, reconnect flow, and resize frames.

TCP tunnels

Forward a local TCP port to a port inside the sandbox over an authenticated WebSocket. The remote port does not need to be in exposed_ports.

Python
TypeScript

with sandbox.create_tunnel(5432, local_port=15432) as tunnel:
    addr = tunnel.address()  # TunnelAddress(host="127.0.0.1", port=15432)
    # Connect a client to addr.host:addr.port

const tunnel = await sandbox.createTunnel(5432, { localPort: 15432 });
const { host, port } = tunnel.address();
// Connect a client to host:port
await tunnel.close();

See Local Tunnels for options, the relay protocol, and common port mappings.

File operations

Copy data in and out of the sandbox filesystem without spawning a shell.

Python
TypeScript

sandbox.write_file("/workspace/data.csv", b"name,score\nAlice,95\n")

content = sandbox.read_file("/workspace/data.csv").value
print(content.decode("utf-8"))

for entry in sandbox.list_directory("/workspace").entries:
    print(entry.name, entry.is_dir, entry.size)

sandbox.delete_file("/workspace/data.csv")

await sandbox.writeFile(
  "/workspace/data.csv",
  new TextEncoder().encode("name,score\nAlice,95\n"),
);

const bytes = await sandbox.readFile("/workspace/data.csv");
console.log(new TextDecoder().decode(bytes));

const entries = await sandbox.listDirectory("/workspace");
await sandbox.deleteFile("/workspace/data.csv");

See File Operations for binary uploads, recursive listings, and move/copy patterns.

Desktop sessions

Desktop sandboxes expose a higher-level remote-control handle on top of the normal Sandbox APIs. Use this with tensorlake/ubuntu-vnc to capture screenshots and drive mouse and keyboard input through the authenticated sandbox proxy.

Python
TypeScript

with sandbox.connect_desktop(password="tensorlake") as desktop:
    png_bytes = desktop.screenshot()
    desktop.move_mouse(640, 400)
    desktop.click()
    desktop.type_text("hello from desktop")
    print(desktop.width, desktop.height)

const desktop = await sandbox.connectDesktop({ password: "tensorlake" });
try {
  const pngBytes = await desktop.screenshot();
  await desktop.moveMouse(640, 400);
  await desktop.click();
  await desktop.typeText("hello from desktop");
  console.log(desktop.width, desktop.height);
} finally {
  await desktop.close();
}

Common desktop methods are:

Python	TypeScript	Description
`screenshot()`	`screenshot()`	Capture the current desktop as PNG bytes.
`move_mouse(x, y)`	`moveMouse(x, y)`	Move the pointer to absolute screen coordinates.
`click()`	`click()`	Click the current pointer location.
`double_click()`	`doubleClick()`	Double-click the current pointer location.
`scroll_up()` / `scroll_down()`	`scrollUp()` / `scrollDown()`	Scroll vertically.
`press(keys)`	`press(keys)`	Send a key or key chord.
`type_text(text)`	`typeText(text)`	Type text into the active window.
`width`, `height`	`width`, `height`	Desktop resolution.

See Computer Use for reconnect patterns, coordinate workflows, and noVNC integration.

Terminate

Shortcut for sandbox.terminate() that uses the handle you already have.

Python
TypeScript

sandbox.terminate()

await sandbox.terminate();

Data models

The SDK returns typed objects for every API call. The fields below are the ones you’ll read most often. Field names shown in Python snake_case; TypeScript uses the camelCase equivalent.

SandboxInfo

Returned by sandbox.info(), client.get(), and updates; list results contain sandbox metadata. Sandbox.create() and Sandbox.connect() return handles instead.

Field	Type	Description
`sandbox_id`	`str`	Server UUID.
`name`	`str \| None`	Name, or `None` for ephemeral.
`namespace`	`str`	Namespace owning the sandbox.
`status`	`SandboxStatus`	One of `pending`, `running`, `snapshotting`, `suspending`, `suspended`, `terminated`.
`image`	`str \| None`	Sandbox image in use.
`resources`	`ContainerResourcesInfo`	`.cpus: float`, `.memory_mb: int`.
`timeout_secs`	`int \| None`	Auto-suspend/terminate timeout.
`auto_resume` / `autoResume`	`bool`	Whether proxy traffic may wake the sandbox while suspended. Defaults to `True` when reading older server responses that omit it.
`exposed_ports`	`list[int] \| None`	Public-routed user ports.
`allow_unauthenticated_access`	`bool`	Whether exposed ports accept unauthenticated traffic.
`ingress_endpoint`	`str \| None`	Base ingress origin for this sandbox’s current placement.
`sandbox_url`	`str \| None`	Sandbox-specific management URL derived from `ingress_endpoint`.
`entrypoint`	`list[str] \| None`	Custom entrypoint command.
`network_policy` / `networkPolicy`	`NetworkConfig \| None`	Egress policy in force (`allow_internet_access`, `allow_out`, `deny_out`), or `None` when egress is unrestricted. See Read the current policy.
`created_at`	`datetime \| None`	Creation timestamp.
`terminated_at`	`datetime \| None`	Termination timestamp (if terminated).

PendingSandbox

Returned by create(wait=False).

Field / method	Type	Description
`sandbox_id`	`str`	The sandbox ID.
`name`	`str \| None`	The name, if one was given.
`state`	`str`	`pending` at creation.
`pending_reason`	`str \| None`	Why it is waiting: `scheduling`, `no_executors_available`, `no_resources_available`, `pool_at_capacity`, `max_capacity_reached`, `no_executor_for_snapshot_location`, `waiting_for_container`.
`ready(timeout, poll_interval, cancel_on_timeout)`	`Sandbox`	Wait until running; raises `SandboxPending` on timeout.
`status()`	`SandboxInfo`	Current state, one request.

Sandbox

Returned by Sandbox.create(), Sandbox.connect(), and Sandbox.get_or_create(). Exposes the runtime methods documented above plus:

Property	Type	Description
`sandbox_id` / `sandboxId`	`str`	UUID, even if connected by name.
`name`	`str \| None`	Human-readable name.

ProcessInfo

Returned by start_process() and list_processes().

Field	Type	Description
`pid`	`int`	Process ID inside the sandbox.
`command`	`str`	The executed command.
`args`	`list[str]`	Command arguments.
`status`	`ProcessStatus`	One of `running`, `exited`, `signaled`.
`exit_code`	`int \| None`	Exit code once the process has exited.
`signal`	`int \| None`	Signal number if the process was terminated by a signal.
`started_at`	`datetime`	When the process started.
`ended_at`	`datetime \| None`	When the process ended.

CommandResult

Returned by run().

Field	Type	Description
`stdout`	`str`	Captured standard output.
`stderr`	`str`	Captured standard error.
`exit_code`	`int`	Process exit code.

SnapshotInfo

Returned by the snapshot APIs.

Field	Type	Description
`snapshot_id`	`str`	Server-assigned ID, use to restore.
`sandbox_id`	`str`	Source sandbox this snapshot was captured from.
`status`	`SnapshotStatus`	One of `in_progress`, `completed`, `failed`.
`size_bytes`	`int \| None`	Size of the snapshot artifact.
`created_at`	`datetime \| None`	Capture timestamp.

Learn more

Lifecycle

State machine, suspend/resume, timeouts.

Commands & Processes

Run commands, capture output, stream, and manage background processes.

PTY Sessions

Interactive shells over WebSocket.

File Operations

Read, write, list, delete.

Snapshots

Capture and restore full VM state.

Build and Import Images

Prebuild dependencies into reusable images.

Computer Use

Desktop sessions, screenshots, mouse, keyboard.

Networking

Expose user ports to the internet.

Environment Variables

Per-command and per-PTY environment.

​Sandbox

​Create

​Create and connect

​Create without waiting

​Get or create

​Connect

​List and get

​Update

​Suspend and resume

​Terminate

​Expose and unexpose ports

​Snapshot and restore

​Sandbox handle

​Run a command

​Background processes

​Writing to stdin

​PTY sessions

​TCP tunnels

​File operations

​Desktop sessions

​Terminate

​Data models

​SandboxInfo

​PendingSandbox

​Sandbox

​ProcessInfo

​CommandResult

​SnapshotInfo

​Learn more

Lifecycle

Commands & Processes

PTY Sessions

File Operations

Snapshots

Build and Import Images

Computer Use

Networking

Environment Variables

Sandbox

Create

Create and connect

Create without waiting

Get or create

Connect

List and get

Update

Suspend and resume

Terminate

Expose and unexpose ports

Snapshot and restore

Sandbox handle

Run a command

Background processes

Writing to stdin

PTY sessions

TCP tunnels

File operations

Desktop sessions

Terminate

Data models

SandboxInfo

PendingSandbox

Sandbox

ProcessInfo

CommandResult

SnapshotInfo

Learn more