> ## 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 — 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 [Sandbox 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 [Sandbox Images](/sandboxes/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: ```bash theme={null} pip install tensorlake tl login ``` ```bash theme={null} npm install tensorlake npx 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 `.