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 — or import an existing registry image directly — 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

If you can docker pull an image from a private registry, then you can use that private image as a base or dependency in the Dockerfile of your sandbox image. To make a private registry available to you, authenticate with docker login. Then run the sandbox image build command.

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

docker login is supported by all private registries, including Docker Hub, GHCR, ECR, GCR, Quay, and self-hosted. docker login populates the local Docker config file with the registry credentials. During the sandbox image build, Tensorlake CLI and SDKs look for the config file at ~/.docker/config.json, or $DOCKER_CONFIG/config.json if DOCKER_CONFIG environment variable is set. If the file is found, Tensorlake CLI and SDKs use credentials from it to pull any base images or dependencies from private registries during the sandbox image build. If the credentials are missing or expired, the build will fail when it tries to pull from the private registry. This also works in CI environments, i.e. if you use amazon-ecr-login to authenticate in ECR in your GitHub Actions workflow, the ECR credentials will be available for tl sbx image create CLI command or SDK calls running in the same workflow.

Import an Image from a Registry

If you just want an existing registry image as a sandbox image — without adding any build steps — import it directly. There is no Dockerfile and no build context: Tensorlake pulls the referenced image’s layers and writes them straight into the sandbox root filesystem, bypassing the Docker daemon entirely. The reference is always pulled fresh from the registry. 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

from tensorlake import import_sandbox_image

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

import { importSandboxImage } from "tensorlake";

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

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 honor the same docker login credentials as Dockerfile builds, so private references work the same way (see Private Registries). The same CPU, memory, disk, and visibility options apply as for builds (see Build Resources and Public Images).

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

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.

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

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 Dockerfile, snapshot ID, image size

describe accepts either the registered image name or the underlying sandbox-template 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 "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);
}

The SDK list and lookup calls use the same environment-based Tensorlake auth as image builds, and require organization and project context (TENSORLAKE_ORGANIZATION_ID and TENSORLAKE_PROJECT_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

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

Dockerfile $VAR and environment variable substitution is not working in FROM commands
Dockerfile ONBUILD commands are ignored and do not run during child image builds
The following Dockerfile commands 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

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

Import an Image from a Registry

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

​Import an Image from a Registry

​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

Import an Image from a Registry

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