Tensorlake Documentation

Sandbox images let you prebuild dependencies, files, and environment setup once, then launch fresh sandboxes from that prepared state. An image is a project-scoped name backed by a filesystem snapshot. You can define one with a Dockerfile, the Python SDK, or the TypeScript SDK, then pass the registered name to image= when creating sandboxes. The usual flow is:

Choose a base image.
Define the setup steps with a Dockerfile or Image object.
Build and register the image name in your project.
Create sandboxes from that registered name.

Base Images

Tensorlake ships preconfigured base images that boot quickly and are tuned for common sandbox workloads:

tensorlake/ubuntu-minimal (default sandbox image): Minimal Ubuntu without systemd. Use this when you want the fastest cold starts.
tensorlake/ubuntu-systemd: Ubuntu with systemd. Use this when you need services such as Docker or Kubernetes inside the sandbox.
tensorlake/debian-minimal: Minimal Debian 13.

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

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

Build and Register an Image

You can define the same image with a Dockerfile, Python, or TypeScript. During a build, Tensorlake prepares a temporary builder sandbox, applies the setup steps, snapshots the prepared root filesystem, and registers the snapshot under the image name.

CLI
Python SDK
TypeScript SDK

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

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

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")
    .workdir("/workspace")
)

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

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

await image.build({
  registeredName: "data-tools-image",
  contextDir: ".",
});

contextDir controls how relative copy() and add() sources are resolved in SDK builds. Dockerfile builds use the Dockerfile’s parent directory as the build context.

Build from an OCI Base

You are not limited to tensorlake/* bases. The build base can be any standard OCI image reference, including python:3.12-slim, debian:bookworm-slim, node:22-alpine, ghcr.io/..., or public.ecr.aws/....

Dockerfile

FROM python:3.12-slim

RUN apt-get update && apt-get install -y curl
RUN python3 -m pip install pandas pyarrow duckdb
WORKDIR /workspace

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

The first build from a new OCI base takes longer because Tensorlake has to fetch and prepare the upstream image. After registration, sandboxes launched from py-data-tools use the registered sandbox image.

Private Registries

Registry credentials are read from your local Docker config file: ~/.docker/config.json, or $DOCKER_CONFIG/config.json when DOCKER_CONFIG environment variable is set. Any registry that works with docker login can be used here, including Docker Hub, GHCR, ECR, GCR, Quay, and self-hosted registries.

docker login ghcr.io
tl sbx image create ./Dockerfile --registered-name my-private-image

In CI, make sure the runner has a populated Docker config before running tl sbx image create. There is no separate environment-variable or programmatic registry-auth path today.

Launch Sandboxes from an Image

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

CLI
Python
TypeScript

tl sbx create --image data-tools-image

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

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();
}

We don’t support launching sandboxes directly from Docker images. They have to be exported into a Tensorlake registered image first, as described in the previous section. We are working on providing the ability to launch Docker images from public registry directly without registering with Tensorlake’s image registry first.

Python Packages

The Tensorlake Ubuntu and Debian base images ship a PEP 668-managed system Python, so pip install requires --break-system-packages unless you create a virtual environment. Without it, pip exits with error: externally-managed-environment. For one-off installs in 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 the 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.

Build Resources

Image builds run inside a temporary builder sandbox. You can allocate more CPU, memory, or disk for that builder, and you can separately choose the root disk size of the generated sandbox image.

CLI
Python SDK
TypeScript SDK

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

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

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

disk_mb / diskMb sets the root disk size for sandboxes created from the registered image. builder_disk_mb / builderDiskMb only affects the temporary builder sandbox. Build defaults are cpus=2.0, memory=4096 MB, and a generated root disk of 10240 MiB (10 GiB).

Register an Existing Snapshot as an Image

If you already have a completed filesystem snapshot, you can give it a reusable image name without rebuilding:

tl sbx image register data-tools-image snap_01HX... \
  --dockerfile ./Dockerfile

The first positional argument is the image name to register, the second is the completed snapshot ID, and --dockerfile is stored alongside the image so tl sbx image describe can show how it was built. Add --public to make the name resolvable from any namespace (see Public Images). The snapshot must be in Completed status with a durable snapshot_uri; tl sbx image register rejects snapshots that haven’t finished uploading.

Inspect and List Registered Images

tl sbx image ls                       # list every image registered in the current project
tl sbx image describe data-tools-image # show Dockerfile, snapshot ID, image size

describe accepts either the registered image name or the underlying sandbox-template ID.

Public Images

By default a registered image is namespace-scoped. Pass --public, is_public=True, or isPublic: true to make the image name resolvable from any namespace. This is how the tensorlake/* base images work.

CLI
Python SDK
TypeScript SDK

tl sbx image create ./Dockerfile --registered-name shared-base --public

image.build(registered_name="shared-base", is_public=True)

await image.build({
  registeredName: "shared-base",
  isPublic: true,
  contextDir: ".",
});

Public image names must be globally unique for the registry. Names that collide with an already-registered public image will be rejected at creation time.

Examples

Skills Image

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.

Supported Build Operations and Limitations

We’re actively working on supporting full Dockerfile feature set.

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

FROM
RUN
WORKDIR
ENV
COPY
ADD
ARG

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

CMD
ENTRYPOINT
EXPOSE
HEALTHCHECK
LABEL
STOPSIGNAL
VOLUME

These instructions are not supported and cause the build to fail:

ONBUILD
SHELL
USER

Additional notes:

Multi-stage Dockerfiles are supported, including earlier-stage FROM, COPY --from=<stage>, COPY --from=<image>, and RUN --mount=...,from=<image>.
tl sbx image create and SDK image builds 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.

Sandbox Images

Base Images

Build and Register an Image

Build from an OCI Base

Private Registries

Launch Sandboxes from an Image

Python Packages

Build Resources

Register an Existing Snapshot as an Image

Inspect and List Registered Images

Public Images

Examples

Skills Image

Supported Build Operations and Limitations

See Also

Snapshots

Lifecycle

Skills in Sandboxes

Documentation Index

​Base Images

​Build and Register an Image

​Build from an OCI Base

​Private Registries

​Launch Sandboxes from an Image

​Python Packages

​Build Resources

​Register an Existing Snapshot as an Image

​Inspect and List Registered Images

​Public Images

​Examples

​Skills Image

​Supported Build Operations and Limitations

​See Also

Snapshots

Lifecycle

Skills in Sandboxes

Base Images

Build and Register an Image

Build from an OCI Base

Private Registries

Launch Sandboxes from an Image

Python Packages

Build Resources

Register an Existing Snapshot as an Image

Inspect and List Registered Images

Public Images

Examples

Skills Image

Supported Build Operations and Limitations

See Also