Tensorlake Documentation

Sandbox images let you prebuild dependencies, files, and environment setup once, then launch fresh sandboxes from that prepared state. They are project-scoped named images backed by a sandbox snapshot. You can define them in Python, TypeScript, or a raw Dockerfile.

Base Images

We provide four base images:

ubuntu-minimal(default): A minimal Ubuntu image which doesn’t include systemd, it boots up in a few hundred milliseconds. If you want to optimize cold boot times, use this image.
ubuntu-systemd: A Ubuntu image which includes systemd, which offers the flexibility of installing packages like Docker and Kubernetes inside the sandbox.
debian-minimal: A minimal Debian 13 image.

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

ubuntu-vnc: A desktop-enabled Ubuntu image based on ubuntu-systemd with XFCE, TigerVNC, and Firefox preinstalled. Use it for browser automation and computer-use workloads. See Computer Use.

Building Custom Images:

You can build a custom image on top of the base images from Python, TypeScript, or a raw Dockerfile. When you build an image, Tensorlake:

Parses the image definition DSL and local source context.
Starts a temporary sandbox from the selected base image.
Translates supported build operations such as run, copy, add, env, and workdir into sandbox build steps and executes them there.
Creates a snapshot of the prepared sandbox.
Registers an image name for that snapshot in your current project.

After that, you can create new sandboxes with tl sbx new --image <name>.

Prerequisites

Images are scoped to the project selected in the CLI. Before creating one, make sure you have:

Python
TypeScript

pip install tensorlake
tl login

npm install tensorlake
npx tl login

For the TypeScript SDK examples on this page, also export TENSORLAKE_API_KEY. Programmatic image registration additionally needs TENSORLAKE_ORGANIZATION_ID and TENSORLAKE_PROJECT_ID.

If you already selected the project earlier, you can skip tl init.

Installing Python packages

The base Ubuntu and Debian images ship a PEP 668–managed system Python, so pip install requires --break-system-packages (or an explicit virtualenv). The flag in the examples below is a requirement, not a stylistic choice — without it, pip exits with error: externally-managed-environment. Use this pattern for ad-hoc packages at runtime, when you don’t have a requirements.txt:

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 from a requirements.txt, see the image-build examples in Define and register the Image below.

Do not sidestep PEP 668 by switching Python versions. python3.11 -m pip install ... (or any deadsnakes-style alternate Python) produces the same externally-managed-environment error — the restriction is per-interpreter, not specific to python3. Do not run ensurepip followed by a bare pip install either. Either pass --break-system-packages to the system python3, or create an explicit venv.

Define and register the Image

You can define images using the Python and Typescript APIs or as Dockerfiles.

CLI
Python SDK
TypeScript SDK

Dockerfile

FROM ubuntu-systemd
RUN apt-get update && apt-get install -y python3 python3-pip
COPY requirements.txt /tmp/requirements.txt
RUN python3 -m pip install --break-system-packages -r /tmp/requirements.txt
RUN mkdir -p /workspace/cache

ENV APP_ENV=prod
WORKDIR /workspace

tl sbx image create ./Dockerfile --registered-name data-tools-image

npx tl sbx image create ./Dockerfile \
  --registered-name data-tools-image \
  --cpus 4 \
  --memory 4096 \
  --disk_mb 25600

from tensorlake import Image

image = (
    Image(name="data-tools-image", base_image="ubuntu-systemd")
    .copy("requirements.txt", "/tmp/requirements.txt")
    .run("apt-get update && apt-get install -y python3 python3-pip")
    .run("python3 -m pip install --break-system-packages -r /tmp/requirements.txt")
    .run("mkdir -p /workspace/cache")
    .env("APP_ENV", "prod")
    .workdir("/workspace")
)

image.build(
    registered_name="data-tools-image")

import { createSandboxImage, Image } from "tensorlake";

const image = new Image({
  name: "data-tools-image",
  baseImage: "tensorlake/ubuntu-systemd",
})
  .copy("requirements.txt", "/tmp/requirements.txt")
  .run("apt-get update && apt-get install -y python3 python3-pip")
  .run("python3 -m pip install --break-system-packages -r /tmp/requirements.txt")
  .run("mkdir -p /workspace/cache")
  .env("APP_ENV", "prod")
  .workdir("/workspace");

await createSandboxImage(image, {
  contextDir: "."
});

contextDir controls how relative copy() and add() sources are resolved. createSandboxImage() reads its cloud context from the current process environment. Set TENSORLAKE_API_KEY, TENSORLAKE_ORGANIZATION_ID, and TENSORLAKE_PROJECT_ID before calling it.

Compute and Storage Configuration

You can specify CPU, Memory and Disk parameters when building images to get bigger sandboxes where images are built. The disk size also carries over to sandboxes launched from that image, so you can use it to prepare images with large dependencies.

CLI
Python SDK
TypeScript SDK

tl sbx image create ./Dockerfile \
  --registered-name data-tools-image \
  --cpus 4 \
  --memory 4096 \
  --disk_mb 25600

image.build(
    registered_name="data-tools-image",
    cpus=4.0,
    memory_mb=4096,
    disk_mb=25600,
)

await createSandboxImage(image, {
  registeredName: "data-tools-image",
  cpus: 4.0,
  memoryMb: 4096,
  diskMb: 25600,
  contextDir: ".",
});

Build-time resource defaults are cpus=2.0, memory=4096 MB, and disk=10 GiB. Override them with --cpus / --memory / --disk_mb in CLI or cpus / memoryMb / diskMb in SDK options.

Skills Image Example

This variant preloads the TensorLake skills repo so coding agents can auto-discover it at startup:

Dockerfile

FROM tensorlake/ubuntu-systemd

RUN apt-get update && apt-get install -y git nodejs npm python3 python3-pip
RUN npm install -g skills
RUN skills add tensorlakeai/tensorlake-skills --all -y --copy
RUN python3 -m pip install --break-system-packages tensorlake

If the file is named Dockerfile, the registered name defaults to the parent directory name. Otherwise it defaults to the file stem. Registered image names must be unique within a project.

Launch Sandboxes from a custom image

Create a new sandbox from the registered image name. You can still choose CPU, memory, timeout, entrypoint, and disk when the sandbox starts.

CLI
Python
TypeScript

tl sbx new --image data-tools-image

tl sbx new \
  --image data-tools-image \
  --cpus 4.0 \
  --memory 4096 \
  --disk_mb 51200 \
  --timeout 1800

SANDBOX_ID=$(tl sbx new --image data-tools-image)
tl sbx exec "$SANDBOX_ID" python3 -c "import pandas, pyarrow; print('ready')"

from tensorlake.sandbox import Sandbox

sandbox = Sandbox.create(
    image="data-tools-image",
    cpus=4.0,
    memory_mb=4096,
    disk_mb=51200,
    timeout_secs=1800,
)

try:
    result = sandbox.run(
        "python3",
        ["-c", "import pandas, pyarrow; print('ready')"],
    )
    print(result.stdout)
finally:
    sandbox.terminate()

import { Sandbox } from "tensorlake";

const sandbox = await Sandbox.create({
  image: "data-tools-image",
  cpus: 4.0,
  memoryMb: 4096,
  diskMb: 51200,
  timeoutSecs: 1800,
});

try {
  const result = await sandbox.run("python3", {
    args: ["-c", "import pandas, pyarrow; print('ready')"],
  });

  console.log(result.stdout);
} finally {
  await sandbox.terminate();
}

Supported Build Operations and Limitations

Across the supported image-definition DSLs, TensorLake currently materializes these build operations into the sandbox:

RUN
WORKDIR
ENV
COPY
ADD

These metadata-oriented operations are preserved with the image definition but are not materialized into the snapshot:

CMD
ENTRYPOINT
EXPOSE
HEALTHCHECK
LABEL
STOPSIGNAL
VOLUME

These operations are not currently supported for sandbox image creation:

ARG
ONBUILD
SHELL
USER

Additional limitations:

Multi-stage Dockerfiles are not supported yet.
FROM must reference a base image that TensorLake can launch as a sandbox, such as tensorlake/ubuntu-minimal or tensorlake/ubuntu-systemd.
COPY and ADD sources are read from the local filesystem relative to the Dockerfile build context.
COPY and ADD currently assume a local build context. Remote URLs and advanced BuildKit-only features are not supported.
tl sbx image create and createSandboxImage() both use the current authenticated project context.
tl sbx image describe shows the registered Dockerfile and snapshot metadata for a sandbox image.

Snapshots

Understand the underlying snapshot primitive used to save and restore sandbox state.

Lifecycle

Learn which sandbox settings you can still override when launching from an image.

Skills in Sandboxes

Ship TensorLake SDK docs inside sandbox images for agents and tools.

Overview

Guides

Use Cases

Sandbox Images

Base Images

Building Custom Images:

Prerequisites

Installing Python packages

Define and register the Image

Compute and Storage Configuration

Skills Image Example

Launch Sandboxes from a custom image

Supported Build Operations and Limitations

See Also

Snapshots

Lifecycle

Skills in Sandboxes

Overview

Guides

Use Cases

Documentation Index

​Base Images

​Building Custom Images:

​Prerequisites

​Installing Python packages

​Define and register the Image

​Compute and Storage Configuration

​Skills Image Example

​Launch Sandboxes from a custom image

​Supported Build Operations and Limitations

​See Also

Snapshots

Lifecycle

Skills in Sandboxes

Base Images

Building Custom Images:

Prerequisites

Installing Python packages

Define and register the Image

Compute and Storage Configuration

Skills Image Example

Launch Sandboxes from a custom image

Supported Build Operations and Limitations

See Also