Skip to main content
Sandbox images let you prebuild dependencies, files, and environment setup once, then launch fresh sandboxes from that prepared state. They are useful when you want a reusable prepared filesystem state built from an Image definition.

​
Base Images

We provide two base images by default:
  • 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.
  • ubuntu-systemd: A Ubuntu image which includes systemd, which offers the flexibility of installing packages like Docker and Kubernetes inside the sandbox.
ubuntu-minimal is the default base image.

​
Building Custom Images

You can build a custom image on top of the base images using the tensorlake SDK. When you build an image, Tensorlake:
  1. Loads an image file and discovers the Image definitions attached to its functions.
  2. Starts a temporary sandbox from the image’s base container.
  3. Replays the image build steps inside that sandbox, including run(), env(), copy(), and add().
  4. Creates a snapshot of the prepared sandbox.
  5. Registers an image name for that snapshot in your current project.
After that, you can create new sandboxes with tl sbx new --image <name>.
We are planning on supporting building custom images from Dockerfiles in the future.

​
Prerequisites

Images are scoped to the project selected in the CLI. Before creating one, make sure you have: 
pip install tensorlake
tl login

​
Define an Image

Define an image in an application file and attach it to at least one function so the CLI can discover it.
image.py
from tensorlake.applications import Image function

SANDBOX_IMAGE = (
    Image(name="data-tools", base_image="ubuntu-minimal")
    .run("pip install pandas pyarrow jupyter")
    .run("mkdir -p /workspace/cache")
    .env("APP_ENV", "prod")
)

​
Create an Image

Create the image from the image file: 
tl sbx image create image.py --name data-tools-image
If the application file defines multiple images, select the one you want: 
tl sbx image create image.py \
  --image-name data-tools \
  --registered-name data-tools-image
--registered-name defaults to the image name if you omit it. Registered image names must be unique within a project.

​
Launch Sandboxes from a custom image

Create a new sandbox from the registered image name: 
tl sbx new --image data-tools-image
You can still choose CPU, memory, timeout, and entrypoint when the sandbox starts: 
tl sbx new \
  --image data-tools-image \
  --cpus 4.0 \
  --memory 4096 \
  --timeout 1800
Then use the sandbox normally: 
SANDBOX_ID=$(tl sbx new --image data-tools-image)
tl sbx exec "$SANDBOX_ID" python -c "import pandas, pyarrow; print('ready')"
Images are built on top of snapshots. The difference is that an image adds a stable project-scoped name and is created from a declarative application image definition.

​
Notes

  • If an image file has more than one image, --image-name is required.
  • copy() and add() sources are read from the local filesystem when you run tl sbx image create.
  • Named image creation and lookup are available in the CLI.

​
See Also

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.