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

​
How Templates Work

When you create a template, Tensorlake:
  1. Loads a template 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 a template name for that snapshot in your current project.
After that, you can create new sandboxes with tl sbx new --template <name>.

​
Prerequisites

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

​
Create a Template

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

SANDBOX_IMAGE = (
    Image(name="data-tools", base_image="python:3.11-slim")
    .run("pip install pandas pyarrow jupyter")
    .run("mkdir -p /workspace/cache")
    .env("APP_ENV", "prod")
)
Create the template from the image file: 
tl sbx create-template template.py --name data-tools-template
If the application file defines multiple images, select the one you want: 
tl sbx create-template template.py \
  --image-name data-tools \
  --name data-tools-template
--name defaults to the image name if you omit it. Template names must be unique within a project.

​
Launch Sandboxes from a Template

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

​
Notes

  • If an template 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 create-template.
  • Named template 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 a template.