Tensorlake Documentation

Tensorlake provides managed images optimized for sandbox workloads. These images are designed for rapid boot and are globally available in every project. By default, creating a sandbox without specifying an image uses tensorlake/ubuntu-minimal. These images are fully self-contained and ready to launch without additional build or registration steps. Custom image builds and imports follow a separate workflow, detailed in Build and Import Images.

Available Images

tensorlake/ubuntu-minimal (default sandbox image): Minimal Ubuntu, systemd excluded. Recommended for scenarios requiring the lowest cold start latency.
tensorlake/ubuntu-systemd: Ubuntu with systemd included. Required for workloads needing service management, such as Docker or Kubernetes, within the sandbox.
tensorlake/debian-minimal: Base Debian 13, minimal profile.

In environments where desktop automation is enabled, you may also see:

tensorlake/ubuntu-vnc: Desktop-enabled Ubuntu derived from tensorlake/ubuntu-systemd, preinstalled with XFCE, TigerVNC, and Firefox. Intended for browser automation and interactive desktop workloads. See Computer Use for more details.

GPU sandboxes

GPU sandboxes can use the following images:

tensorlake/cas/cuda:13.3: CUDA 13.3 toolkit and cuDNN on Ubuntu 24.04 for building and running your own GPU code. Based on nvidia/cuda:13.3.1-cudnn-devel-ubuntu24.04.
tensorlake/cas/vllm:0.26: vLLM 0.26 with its OpenAI-compatible server. Model weights aren’t included. Based on vllm/vllm-openai:v0.26.0.
tensorlake/cas/sglang:0.5: SGLang 0.5.16 with its server. Model weights aren’t included. Based on lmsysorg/sglang:v0.5.16.

These are the upstream images repackaged in Tensorlake format without changes to their contents. Commands run with the upstream image’s user and working directory rather than tl-user, and the upstream image entrypoint is disabled, so nothing starts until you run it.

Example: Create Sandbox

Launch a new sandbox from the Tensorlake-managed tensorlake/ubuntu-systemd image:

CLI
Python
TypeScript

tl sbx create --image tensorlake/ubuntu-systemd

from tensorlake.sandbox import Sandbox

sandbox = Sandbox.create(image="tensorlake/ubuntu-systemd")

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

const sandbox = await Sandbox.create({ image: "tensorlake/ubuntu-systemd" });

Default User and Working Directory

By default, tensorlake/* images execute commands as tl-user (UID 1000, home /home/tl-user), a non-root user with passwordless sudo. Unlike Standard Docker images, which commonly run as root, this configuration enforces user-level isolation. Tools hardcoded to write to root-owned paths such as /workspace will encounter Permission denied errors. Note: non-interactive commands start from the filesystem root /, so relative commands like touch output.txt may fail unless run from a writable directory. Interactive PTY and SSH sessions default to /home/tl-user. To resolve Permission denied errors, ensure commands execute from a directory owned by tl-user (e.g., /home/tl-user), or escalate privileges using sudo or —user root. If files are created as root but need to be accessed by tl-user, adjust ownership with chown:

# Run from a writable working directory
# (working_dir in Python, workingDir in TypeScript)
tl sbx exec <sandbox-id> --workdir /home/tl-user -- touch output.txt

# Escalate with sudo (works in run() too, which always executes as tl-user)
tl sbx exec <sandbox-id> -- sudo apt-get update

# Or run the whole command as root
tl sbx exec <sandbox-id> --user root -- mkdir -p /opt/tools

# Make a system path writable for tl-user
tl sbx exec <sandbox-id> -- bash -c 'sudo mkdir -p /workspace && sudo chown tl-user:tl-user /workspace'

If a workload consistently requires a path such as /workspace, include its creation and ownership assignment in a custom image build rather than reconfiguring each new sandbox instance:

FROM tensorlake/ubuntu-minimal

RUN mkdir -p /workspace && chown tl-user:tl-user /workspace
WORKDIR /workspace

See Build and Import Images for how to build and register a custom image like this one.

Many third-party integrations assume root and default their workdir to /workspace/<name>. Point them to /home/tl-user/<name>, or use a custom image like the one above. For an example, see the Crabbox guide.

Python Packages

Tensorlake Ubuntu and Debian images include a system Python installation managed according to PEP 668. Installing packages with pip requires --break-system-packages flag, unless a virtual environment is used. Omitting this flag results in the externally-managed-environment error. For ad hoc installation within a running sandbox:

Python
TypeScript

sandbox.run(
    "python3",
    ["-m", "pip", "install", "--break-system-packages", "pandas", "pyarrow", "duckdb"],
)

await sandbox.run("python3", {
  args: ["-m", "pip", "install", "--break-system-packages", "pandas", "pyarrow", "duckdb"],
});

For repeatable installs, put the packages in requirements.txt and install them during a custom image build, as shown in Build and Register an Image.

Do not sidestep PEP 668 by switching Python versions. python3.11 -m pip install ... or another alternate system Python can produce the same externally-managed-environment error. Use --break-system-packages with the system python3, or create an explicit virtual environment.

Using Tensorlake Images as Build Bases

Any tensorlake/* image can be a FROM base (base_image= in the SDKs). See Build and Import Images for the full workflow.

A Dockerfile that builds on a Tensorlake image doesn’t inherit the tl-user defaults described above. As in any Docker build, the resulting image runs as root unless its Dockerfile sets USER, and its working directory comes from WORKDIR.

Build and Import Images

Build your own Docker image or import one from a registry and run it in sandboxes.

Computer Use

Drive the XFCE desktop that ships in tensorlake/ubuntu-vnc.

Lifecycle

Learn which sandbox settings you can override at launch time.

Overview

Guides

Use Cases

Tensorlake Images

Available Images

GPU sandboxes

Example: Create Sandbox

Default User and Working Directory

Python Packages

Using Tensorlake Images as Build Bases

See Also

Build and Import Images

Computer Use

Lifecycle

​Available Images

​GPU sandboxes

​Example: Create Sandbox

​Default User and Working Directory

​Python Packages

​Using Tensorlake Images as Build Bases

​See Also

Build and Import Images

Computer Use

Lifecycle

Available Images

GPU sandboxes

Example: Create Sandbox

Default User and Working Directory

Python Packages

Using Tensorlake Images as Build Bases

See Also