Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tensorlake.ai/llms.txt

Use this file to discover all available pages before exploring further.

Sandbox images let you prebuild dependencies, files, and environment setup once, then launch fresh sandboxes from that prepared state. Below are the most common questions about images.

​
What is a sandbox image and how is it different from a Docker image?

A sandbox image is a prebuilt, named environment used to launch isolated VMs or sandboxes. It packages dependencies, files, and environment setup so each new sandbox starts from the same prepared state. The shape is similar to a Docker image — base layer, build operations like run, copy, env, workdir — but:
  • The runtime target is a MicroVM, not a container.
  • The build artifact is a sandbox snapshot, not an OCI image.
  • The image is scoped to a project, not a registry.
Tensorlake supports defining sandbox images in Python, TypeScript, or a raw Dockerfile. See Sandbox Images.

​
What sandbox images does Tensorlake provide?

Tensorlake ships several base images:
  • ubuntu-minimal (default) — minimal Ubuntu without systemd. Boots in a few hundred milliseconds. Best for fast cold boot.
  • ubuntu-systemd — Ubuntu with a full systemd init system. Use when you need to install packages like Docker or Kubernetes inside the sandbox.
  • debian-minimal — minimal Debian 13.
  • ubuntu-vnc — desktop-enabled Ubuntu (based on ubuntu-systemd) with XFCE, TigerVNC, and Firefox preinstalled. Use for browser automation and computer-use workloads.

​
Which sandbox image should I use?

WorkloadRecommended image
Fastest cold bootubuntu-minimal
Need systemd, Docker, or Kubernetesubuntu-systemd
Debian-based environmentdebian-minimal
Browser automation / desktop / computer useubuntu-vnc

​
How do I build a custom sandbox image?

You can build a custom image on top of a base image from Python, TypeScript, or a raw Dockerfile. When you build an image, Tensorlake:
  1. Parses the image definition DSL and local source context.
  2. Starts a temporary sandbox from the selected base image.
  3. Translates supported build operations such as run, copy, add, env, and workdir into sandbox build steps and executes them there.
  4. Creates a snapshot of the prepared sandbox.
  5. Registers the image name for that snapshot in your current project.
Then create new sandboxes with: 
tl sbx new --image <name>
See Sandbox Images for full examples.

​
Are Tensorlake sandbox images project-scoped?

Yes. Custom images are scoped to the project selected in the CLI. Before registering one: 
pip install tensorlake
tl login
Programmatic image registration from the TypeScript SDK additionally needs TENSORLAKE_API_KEY, TENSORLAKE_ORGANIZATION_ID, and TENSORLAKE_PROJECT_ID.

​
Why does pip install require --break-system-packages in a Tensorlake sandbox?

The base Ubuntu and Debian images ship a PEP 668–managed system Python, so pip install requires --break-system-packages (or an explicit virtualenv). Without the flag, pip exits with error: externally-managed-environment. The flag is a requirement, not a stylistic choice.

​
Can I use my existing Dockerfile with Tensorlake?

Yes. Tensorlake can build a sandbox image from a raw Dockerfile alongside the Python and TypeScript image DSLs. Tensorlake parses the Dockerfile, starts a temporary sandbox from the selected base image, runs supported build operations (run, copy, add, env, workdir), captures a snapshot, and registers the resulting image name in your project. After that, launch sandboxes with tl sbx new --image <name>.