Tensorlake Documentation

Sandbox images let you set up dependencies, files, and environment once, then launch fresh sandboxes from that prepared state. Define an image with a Dockerfile, the Python SDK, or the TypeScript SDK (or import an existing registry image directly), then pass the registered name to image= when creating sandboxes. Before running the examples, install the CLI or SDK and authenticate. The usual flow is:

Choose a base image.
Define the image, then build and register it under a name.
Create sandboxes from the registered name.

Images follow the Docker/OCI runtime contract. USER, WORKDIR, and ENV apply to every process you start in a sandbox, and ENTRYPOINT and CMD run when the sandbox boots unless you pass your own entrypoint at create time. The instructions that don’t carry over, such as EXPOSE and VOLUME, are listed in Supported Build Instructions and Limitations. Every image is project-scoped. Deleting an image requires Admin role in its project.

Choose a Base Image

You can use any image the build can pull as your FROM base: a Tensorlake image, a public OCI reference, or a private registry image.

Define, Build and Register an Image

You can define the same image with a Dockerfile, Python, or TypeScript. The build runs the setup steps and registers the result under the image name in your project.

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", context_dir=".")

import { Image } from "@tensorlakeai/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: ".",
});

In the SDKs, context_dir (contextDir in TypeScript) is optional and works like the build context in docker build <context>. Pass it when the Image reads host files (through copy(), add(), or a RUN --mount=type=bind) so those sources resolve relative to it. Omit it otherwise.

Build from an OCI Base

The build base can be any standard OCI image reference, not just tensorlake/*, for example 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 the upstream image has to be fetched and prepared. Subsequent builds are faster.

Build arguments

Dockerfile build arguments are accepted. For example, declare an argument to select the Python version in FROM:

Dockerfile

ARG PYTHON_VERSION=3.12
FROM python:${PYTHON_VERSION}-slim

Pass the argument when building the Dockerfile or SDK image definition:

CLI
Python
TypeScript

tl sbx image create ./Dockerfile --registered-name my-image \
  --build-arg PYTHON_VERSION=3.12

from tensorlake import Image

image = Image(
    name="my-image",
    base_image="python:${PYTHON_VERSION}-slim",
)

image.build(
    build_args={"PYTHON_VERSION": "3.12"},
)

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

await createSandboxImage("./Dockerfile", {
  registeredName: "my-image",
  buildArgs: { PYTHON_VERSION: "3.12" },
});

Private Registries

If you can docker pull an image from a private registry, you can use it as a base or dependency in your sandbox image’s Dockerfile. Authenticate with docker login, then run the build:

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

docker login works with all private registries, including Docker Hub, GHCR, ECR, GCR, Quay, and self-hosted. During the build, the Tensorlake CLI and SDKs read registry credentials from ~/.docker/config.json (or $DOCKER_CONFIG/config.json if DOCKER_CONFIG is set) and use them to pull private base images and dependencies. If the credentials are missing or expired, the build fails when it tries to pull from the private registry. This also works in CI. For example, if you authenticate to ECR with amazon-ecr-login in a GitHub Actions workflow, tl sbx image create and SDK calls in the same workflow pick up those credentials.

Import an Image from a Registry

To use an existing registry image as a sandbox image without adding any build steps, import it directly. There is no Dockerfile and no build context, and the reference is always pulled fresh from the registry. Sandboxes run the imported image with whatever user, working directory, and environment it defines. Use this when you want a published image (ubuntu:24.04, pytorch/pytorch:2.4.1-cuda12.1-cudnn9-runtime, ghcr.io/org/app:v1) as-is. If you need to layer extra packages, files, or environment on top, write a Dockerfile that uses it as a FROM base instead. See Build from an OCI Base.

CLI
Python SDK
TypeScript SDK

tl sbx image import pytorch/pytorch:2.4.1-cuda12.1-cudnn9-runtime \
  --registered-name pytorch-runtime --disk_mb 20480

from tensorlake import import_sandbox_image

import_sandbox_image(
    "pytorch/pytorch:2.4.1-cuda12.1-cudnn9-runtime",
    registered_name="pytorch-runtime",
    disk_mb=20480,
)

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

await importSandboxImage(
  "pytorch/pytorch:2.4.1-cuda12.1-cudnn9-runtime",
  { registeredName: "pytorch-runtime", diskMb: 20480 },
);

--disk_mb in the CLI, disk_mb in Python, and diskMb in TypeScript set the root disk size of sandboxes created from the image, as for any build or import. Use the same option when creating an individual sandbox to grow its root disk further. If you omit the registered name, it defaults to the reference’s last path segment with any tag or digest stripped (pytorch/pytorch:2.4.1 → pytorch, ghcr.io/org/app@sha256:... → app). Imports use the same docker login credentials as Dockerfile builds, so private references work the same way (see Private Registries). The same CPU, memory, and disk options apply as for builds (see Build Resources).

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 "@tensorlakeai/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();
}

You can’t launch a sandbox directly from a Docker/registry image reference. It has to be registered as a Tensorlake image first. The quickest way to do that for an unmodified image is Import an Image from a Registry, which registers it in one step with no Dockerfile. We are working on launching public registry images directly without a separate registration step.

Build Resources

Builds run in a temporary builder sandbox. You can allocate more CPU or memory for the builder, and separately set the root disk size of the resulting image.

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",
    context_dir=".",
    cpus=4.0,
    memory_mb=4096,
    disk_mb=25600,
)

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

disk_mb / diskMb sets the root disk size for sandboxes created from the registered image. Build defaults are cpus=2.0, memory=4096 MB, and a generated root disk of 10240 MiB (10 GiB). Builder disk sizing and Docker compatibility mode apply only to legacy images.

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...

The first positional argument is the image name to register, the second is the completed snapshot ID. 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

List the images registered in your project, or look one up by name, from the CLI or the SDKs.

CLI
Python SDK
TypeScript SDK

tl sbx image ls                       # list every image registered in the current project
tl sbx image describe data-tools-image # show image metadata

describe accepts either the registered image name or the image ID.

from tensorlake import find_sandbox_image_by_name, list_sandbox_images

images = list_sandbox_images()  # every image registered in the current project

image = find_sandbox_image_by_name("data-tools-image")  # None if no such image exists
if image is not None:
    print(image["id"], image["snapshot_id"])

import { findSandboxImageByName, listSandboxImages } from "@tensorlakeai/tensorlake";

const images = await listSandboxImages(); // every image registered in the current project

const image = await findSandboxImageByName("data-tools-image"); // null if no such image exists
if (image) {
  console.log(image.id, image.snapshotId);
}

Supported Build Instructions and Limitations

Sandbox image builds support most of the standard Dockerfile instructions and features, but with some limitations:

Dockerfile ONBUILD instructions are ignored and do not run during child image builds
The following Dockerfile instructions work as expected during image builds but do not have any effect when running sandboxes from the images:
- ONBUILD
- SHELL
- EXPOSE
- HEALTHCHECK
- LABEL
- STOPSIGNAL
- VOLUME

Legacy images

Builds and imports use Content Addressable Streaming (CAS) by default. If you encounter problems with CAS and didn’t have them with legacy image format then, use --no-cas in the CLI, cas=False in Python, or cas: false in TypeScript to build or import a legacy image. The non-GPU Tensorlake images are available in legacy format too.

Differences from CAS images

Legacy images have these differences:

Startup: Legacy sandboxes download the snapshot before starting instead of streaming its contents on demand
Sandbox features: Legacy images don’t support live resize, nested virtualization, or GPU sandboxes
Build arguments: Dockerfile $VAR and environment variable substitution is not working in FROM commands
Build options: Builder disk sizing and Docker compatibility mode apply only to legacy builds and imports

Build a legacy image

Build and register the same legacy image with a Dockerfile or an SDK image definition. See Define, Build and Register an Image for the full workflow.

Dockerfile

FROM tensorlake/legacy/ubuntu-minimal
RUN apt-get update && apt-get install -y python3

CLI
Python
TypeScript

tl sbx image create ./Dockerfile --registered-name my-legacy-image --no-cas

from tensorlake import Image

image = Image(
    name="my-legacy-image",
    base_image="tensorlake/legacy/ubuntu-minimal",
).run("apt-get update && apt-get install -y python3")

image.build(cas=False)

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

const image = new Image({
  name: "my-legacy-image",
  baseImage: "tensorlake/legacy/ubuntu-minimal",
}).run("apt-get update && apt-get install -y python3");

await image.build({ cas: false });

Import a legacy image

Import a registry image as a legacy image with the CLI or either SDK. See Import an Image from a Registry for the import workflow.

CLI
Python
TypeScript

tl sbx image import ubuntu:24.04 \
  --registered-name my-legacy-image --no-cas --disk_mb 20480

from tensorlake import import_sandbox_image

import_sandbox_image(
    "ubuntu:24.04",
    registered_name="my-legacy-image",
    cas=False,
    disk_mb=20480,
)

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

await importSandboxImage("ubuntu:24.04", {
  registeredName: "my-legacy-image",
  cas: false,
  diskMb: 20480,
});

Launch a sandbox from a legacy image

Passing a legacy image when creating a sandbox launches it from the legacy image on legacy dataplane. Sandboxes created from legacy images and snapshot create their snapshots in legacy format too.

Live Resize

Change the CPUs, memory, and disk of a running sandbox.

Nested Virtualization

Run QEMU/KVM virtual machines inside a sandbox.

Tensorlake Images

The managed tensorlake/* images: what ships in them and how they behave at runtime.

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

Build and Import Images

Choose a Base Image

Define, Build and Register an Image

Build from an OCI Base

Build arguments

Private Registries

Import an Image from a Registry

Launch Sandboxes from an Image

Build Resources

Register an Existing Snapshot as an Image

Inspect and List Registered Images

Supported Build Instructions and Limitations

Legacy images

Differences from CAS images

Build a legacy image

Import a legacy image

Launch a sandbox from a legacy image

See Also

Live Resize

Nested Virtualization

Tensorlake Images

Snapshots

Lifecycle

Skills in Sandboxes

​Choose a Base Image

​Define, Build and Register an Image

​Build from an OCI Base

​Build arguments

​Private Registries

​Import an Image from a Registry

​Launch Sandboxes from an Image

​Build Resources

​Register an Existing Snapshot as an Image

​Inspect and List Registered Images

​Supported Build Instructions and Limitations

​Legacy images

​Differences from CAS images

​Build a legacy image

​Import a legacy image

​Launch a sandbox from a legacy image

​See Also

Live Resize

Nested Virtualization

Tensorlake Images

Snapshots

Lifecycle

Skills in Sandboxes

Choose a Base Image

Define, Build and Register an Image

Build from an OCI Base

Build arguments

Private Registries

Import an Image from a Registry

Launch Sandboxes from an Image

Build Resources

Register an Existing Snapshot as an Image

Inspect and List Registered Images

Supported Build Instructions and Limitations

Legacy images

Differences from CAS images

Build a legacy image

Import a legacy image

Launch a sandbox from a legacy image

See Also