Sandbox Images

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 two base images everywhere by default:

tensorlake/ubuntu-minimal: 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.
tensorlake/ubuntu-systemd: A Ubuntu image which includes systemd, which offers the flexibility of installing packages like Docker and Kubernetes inside the sandbox.

tensorlake/ubuntu-minimal is the default base image. In environments where desktop automation is enabled, you may also see:

tensorlake/ubuntu-vnc: A desktop-enabled Ubuntu image based on tensorlake/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
tl init

npm install tensorlake
npx tl login
npx tl init

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.

Define an Image

All three approaches below define the same sandbox image. These definitions are DSLs. TensorLake translates the supported operations into sandbox build steps before snapshotting the result.

Python

Use Python when you want to define the image with the TensorLake Image DSL:

from tensorlake import Image

image = (
    Image(name="data-tools-image", base_image="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")
)

TypeScript

Use TypeScript when you want to define the image with the TensorLake Image DSL:

import { 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");

Dockerfile

Use a raw Dockerfile when you want the image definition checked in directly as infrastructure code:

Dockerfile

FROM tensorlake/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

requirements.txt

pandas
pyarrow
jupyter

Register the Image

Once you have an image definition ready, register it as a Sandbox Image:

CLI
TypeScript SDK

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

npx tl sbx image create ./Dockerfile --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: ".",
  cpus: 4,
  memoryMb: 4096,
});

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.

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, and entrypoint when the sandbox starts. Then use the sandbox normally:

CLI
Python
TypeScript

tl sbx new --image data-tools-image

tl sbx new \
  --image data-tools-image \
  --cpus 4.0 \
  --memory 4096 \
  --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 SandboxClient

client = SandboxClient()

with client.create_and_connect(
    image="data-tools-image",
    cpus=4.0,
    memory_mb=4096,
    timeout_secs=1800,
) as sandbox:
    result = sandbox.run(
        "python3",
        ["-c", "import pandas, pyarrow; print('ready')"],
    )
    print(result.stdout)

import { SandboxClient } from "tensorlake";

const client = SandboxClient.forCloud({
  apiKey: process.env.TENSORLAKE_API_KEY,
});

const sandbox = await client.createAndConnect({
  image: "data-tools-image",
  cpus: 4.0,
  memoryMb: 4096,
  timeoutSecs: 1800,
});

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

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

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

Base Images

Building Custom Images

Prerequisites

Define an Image

Python

TypeScript

Dockerfile

Register the Image

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

​Base Images

​Building Custom Images

​Prerequisites

​Define an Image

​Python

​TypeScript

​Dockerfile

​Register the Image

​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

Define an Image

Python

TypeScript

Dockerfile

Register the Image

Skills Image Example

Launch Sandboxes from a custom image

Supported Build Operations and Limitations

See Also