> ## 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. # How do sandbox images work in Tensorlake? > Frequently asked questions about Tensorlake sandbox images, covering base images, custom images, and building from Python, TypeScript, or a Dockerfile. 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 [Build and Import Images](/sandboxes/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](/sandboxes/computer-use) workloads. ## Which sandbox image should I use? | Workload | Recommended image | | ------------------------------------------- | ----------------- | | Fastest cold boot | `ubuntu-minimal` | | Need systemd, Docker, or Kubernetes | `ubuntu-systemd` | | Debian-based environment | `debian-minimal` | | Browser automation / desktop / computer use | `ubuntu-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: ```bash theme={null} tl sbx new --image ``` See [Build and Import Images](/sandboxes/images) for full examples. ## Are Tensorlake sandbox images project-scoped? Yes. Custom images are project-scoped. Choose the setup for the interface you use: ```bash theme={null} pip install tensorlake export TENSORLAKE_API_KEY=tl_apiKey_... ``` ```bash theme={null} npm install tensorlake export TENSORLAKE_API_KEY=tl_apiKey_... ``` ```bash theme={null} curl -fsSL https://tensorlake.ai/install | sh tl login # Or skip interactive login and export TENSORLAKE_API_KEY. ``` SDK image operations use the project encoded by `TENSORLAKE_API_KEY`; they do not require `TENSORLAKE_ORGANIZATION_ID` or `TENSORLAKE_PROJECT_ID`. The CLI accepts either an API key or the Personal Access Token created by `tl login`. ## Why does `pip install` require `--break-system-packages` in a Tensorlake sandbox? The Tensorlake 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 `.