> ## 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

> Define reusable named sandbox images in Python, TypeScript, or Dockerfiles.

Sandbox images let you prebuild dependencies, files, and environment setup once, then launch fresh sandboxes from that prepared state.

An image is a project-scoped name backed by a filesystem snapshot. You can define one with a Dockerfile, the Python SDK, or the TypeScript SDK, then pass the registered name to `image=` when creating sandboxes.

The usual flow is:

1. Choose a base image.
2. Define the setup steps with a Dockerfile or `Image` object.
3. Build and register the image name in your project.
4. Create sandboxes from that registered name.

## Prerequisites

Images are scoped to the authenticated project. Before creating one, make sure you have installed the SDK or CLI and authenticated:

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install tensorlake
    tl login
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install tensorlake
    npx tl login
    ```
  </Tab>
</Tabs>

For SDK image builds, set `TENSORLAKE_API_KEY` in the process environment. If you authenticate with a personal access token instead, also set `TENSORLAKE_ORGANIZATION_ID` and `TENSORLAKE_PROJECT_ID` so the SDK can choose the project.

## Base Images

Tensorlake ships preconfigured base images that boot quickly and are tuned for common sandbox workloads:

* `tensorlake/ubuntu-minimal` (*default sandbox image*): Minimal Ubuntu without systemd. Use this when you want the fastest cold starts.
* `tensorlake/ubuntu-systemd`: Ubuntu with systemd. Use this when you need services such as Docker or Kubernetes inside the sandbox.
* `tensorlake/debian-minimal`: Minimal Debian 13.

In environments where desktop automation is enabled, you may also see:

* `tensorlake/ubuntu-vnc`: Desktop-enabled Ubuntu based on `tensorlake/ubuntu-systemd`, with XFCE, TigerVNC, and Firefox preinstalled. Use it for browser automation and computer-use workloads. See [Computer Use](/sandboxes/computer-use).

<Note>
  The short aliases `ubuntu-minimal`, `ubuntu-systemd`, `ubuntu-vnc`, and `debian-minimal` resolve to their canonical `tensorlake/`-prefixed names. Both forms work anywhere `image=` is accepted.
</Note>

### `FROM` vs `image=`

`FROM` and `image=` are related, but they are resolved at different times:

* `FROM` in a Dockerfile, `base_image=` in Python, or `baseImage` in TypeScript accepts any OCI image reference. Tensorlake resolves it during the image build.
* `image=` on `Sandbox.create()` or `--image` on `tl sbx create` accepts a registered sandbox image name. It is not resolved against an upstream registry at sandbox-create time.

For example, `FROM python:3.12-slim` is valid in a Dockerfile build. `Sandbox.create(image="python:3.12-slim")` will fail unless you have already registered an image with that exact name.

## Build and Register an Image

You can define the same image with a Dockerfile, Python, or TypeScript. During a build, Tensorlake prepares a temporary builder sandbox, applies the setup steps, snapshots the prepared root filesystem, and registers the snapshot under the image name.

<Tabs>
  <Tab title="CLI">
    ```dockerfile Dockerfile theme={null}
    FROM tensorlake/ubuntu-systemd

    RUN apt-get update && apt-get install -y python3 python3-pip
    COPY requirements.txt /tmp/requirements.txt
    RUN python3 -m pip install --break-system-packages -r /tmp/requirements.txt
    RUN mkdir -p /workspace/cache

    ENV APP_ENV=prod
    WORKDIR /workspace
    ```

    ```bash theme={null}
    tl sbx image create ./Dockerfile --registered-name data-tools-image
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    from tensorlake import Image

    image = (
        Image(name="data-tools-image", base_image="tensorlake/ubuntu-systemd")
        .copy("requirements.txt", "/tmp/requirements.txt")
        .run("apt-get update && apt-get install -y python3 python3-pip")
        .run("python3 -m pip install --break-system-packages -r /tmp/requirements.txt")
        .run("mkdir -p /workspace/cache")
        .env("APP_ENV", "prod")
        .workdir("/workspace")
    )

    image.build(registered_name="data-tools-image")
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { Image } from "tensorlake";

    const image = new Image({
      name: "data-tools-image",
      baseImage: "tensorlake/ubuntu-systemd",
    })
      .copy("requirements.txt", "/tmp/requirements.txt")
      .run("apt-get update && apt-get install -y python3 python3-pip")
      .run("python3 -m pip install --break-system-packages -r /tmp/requirements.txt")
      .run("mkdir -p /workspace/cache")
      .env("APP_ENV", "prod")
      .workdir("/workspace");

    await image.build({
      registeredName: "data-tools-image",
      contextDir: ".",
    });
    ```
  </Tab>
</Tabs>

`contextDir` controls how relative `copy()` and `add()` sources are resolved in SDK builds. Dockerfile builds use the Dockerfile's parent directory as the build context.

### Build from an OCI Base

You are not limited to `tensorlake/*` bases. The build base can be any standard OCI image reference, including `python:3.12-slim`, `debian:bookworm-slim`, `node:22-alpine`, `ghcr.io/...`, or `public.ecr.aws/...`.

```dockerfile Dockerfile theme={null}
FROM python:3.12-slim

RUN apt-get update && apt-get install -y curl
RUN python3 -m pip install pandas pyarrow duckdb
WORKDIR /workspace
```

```bash theme={null}
tl sbx image create ./Dockerfile --registered-name py-data-tools
```

The first build from a new OCI base takes longer because Tensorlake has to fetch and prepare the upstream image. After registration, sandboxes launched from `py-data-tools` use the registered sandbox image.

### Private Registries

Registry credentials are read from your local Docker config file: `~/.docker/config.json`, or `$DOCKER_CONFIG/config.json` when `DOCKER_CONFIG` is set. Any registry that works with `docker login` can be used here, including Docker Hub, GHCR, ECR, GCR, Quay, and self-hosted registries.

```bash theme={null}
docker login ghcr.io
tl sbx image create ./Dockerfile --registered-name my-private-image
```

In CI, make sure the runner has a populated Docker config before running `tl sbx image create`. There is no separate environment-variable or programmatic registry-auth path today.

## Launch Sandboxes from an Image

Create a sandbox from the registered image name. You can still override CPU, memory, disk, timeout, and entrypoint when the sandbox starts.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx create --image data-tools-image
    ```

    ```bash theme={null}
    tl sbx create \
      --image data-tools-image \
      --cpus 4.0 \
      --memory 4096 \
      --disk_mb 51200 \
      --timeout 1800
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from tensorlake.sandbox import Sandbox

    sandbox = Sandbox.create(
        image="data-tools-image",
        cpus=4.0,
        memory_mb=4096,
        disk_mb=51200,
        timeout_secs=1800,
    )

    try:
        result = sandbox.run(
            "python3",
            ["-c", "import pandas, pyarrow; print('ready')"],
        )
        print(result.stdout)
    finally:
        sandbox.terminate()
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { Sandbox } from "tensorlake";

    const sandbox = await Sandbox.create({
      image: "data-tools-image",
      cpus: 4.0,
      memoryMb: 4096,
      diskMb: 51200,
      timeoutSecs: 1800,
    });

    try {
      const result = await sandbox.run("python3", {
        args: ["-c", "import pandas, pyarrow; print('ready')"],
      });

      console.log(result.stdout);
    } finally {
      await sandbox.terminate();
    }
    ```
  </Tab>
</Tabs>

## Python Packages

The Tensorlake Ubuntu and Debian base images ship a PEP 668-managed system Python, so `pip install` requires `--break-system-packages` unless you create a virtual environment. Without it, `pip` exits with `error: externally-managed-environment`.

For one-off installs in a running sandbox:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    sandbox.run(
        "python3",
        ["-m", "pip", "install", "--break-system-packages", "pandas", "pyarrow", "duckdb"],
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await sandbox.run("python3", {
      args: ["-m", "pip", "install", "--break-system-packages", "pandas", "pyarrow", "duckdb"],
    });
    ```
  </Tab>
</Tabs>

For repeatable installs, put the packages in `requirements.txt` and install them during the image build, as shown in [Build and Register an Image](#build-and-register-an-image).

<Warning>
  Do not sidestep PEP 668 by switching Python versions. `python3.11 -m pip install ...` or another alternate system Python can produce the same `externally-managed-environment` error. Use `--break-system-packages` with the system `python3`, or create an explicit virtual environment.
</Warning>

## Build Resources

Image builds run inside a temporary builder sandbox. You can allocate more CPU, memory, or disk for that builder, and you can separately choose the root disk size of the generated sandbox image.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx image create ./Dockerfile \
      --registered-name data-tools-image \
      --cpus 4 \
      --memory 4096 \
      --disk_mb 25600 \
      --builder_disk_mb 32768
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    image.build(
        registered_name="data-tools-image",
        cpus=4.0,
        memory_mb=4096,
        disk_mb=25600,
        builder_disk_mb=32768,
    )
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    await image.build({
      registeredName: "data-tools-image",
      cpus: 4.0,
      memoryMb: 4096,
      diskMb: 25600,
      builderDiskMb: 32768,
      contextDir: ".",
    });
    ```
  </Tab>
</Tabs>

`disk_mb` / `diskMb` sets the root disk size for sandboxes created from the registered image. `builder_disk_mb` / `builderDiskMb` only affects the temporary builder sandbox.

Build defaults are `cpus=2.0`, `memory=4096 MB`, and a generated root disk of `10240 MiB` (10 GiB).

## Register an Existing Snapshot as an Image

If you already have a completed filesystem snapshot, you can give it a reusable image name without rebuilding:

```bash theme={null}
tl sbx image register data-tools-image snap_01HX... \
  --dockerfile ./Dockerfile
```

The first positional argument is the image name to register, the second is the completed snapshot ID, and `--dockerfile` is stored alongside the image so `tl sbx image describe` can show how it was built. Add `--public` to make the name resolvable from any namespace (see [Public Images](#public-images)).

The snapshot must be in `Completed` status with a durable `snapshot_uri`; `tl sbx image register` rejects snapshots that haven't finished uploading.

## Inspect and List Registered Images

```bash theme={null}
tl sbx image ls                       # list every image registered in the current project
tl sbx image describe data-tools-image # show Dockerfile, snapshot ID, image size
```

`describe` accepts either the registered image name or the underlying sandbox-template ID.

## Public Images

By default a registered image is namespace-scoped. Pass `--public`, `is_public=True`, or `isPublic: true` to make the image name resolvable from any namespace. This is how the `tensorlake/*` base images work.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx image create ./Dockerfile --registered-name shared-base --public
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    image.build(registered_name="shared-base", is_public=True)
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    await image.build({
      registeredName: "shared-base",
      isPublic: true,
      contextDir: ".",
    });
    ```
  </Tab>
</Tabs>

Public image names must be globally unique for the registry. Names that collide with an already-registered public image will be rejected at creation time.

## Examples

### Skills Image

This variant preloads the [Tensorlake skills repo](/agent-skills) so coding agents can auto-discover it at startup:

```dockerfile Dockerfile theme={null}
FROM tensorlake/ubuntu-systemd

RUN apt-get update && apt-get install -y git nodejs npm python3 python3-pip
RUN npm install -g skills
RUN skills add tensorlakeai/tensorlake-skills --all -y --copy
RUN python3 -m pip install --break-system-packages tensorlake
```

If the file is named `Dockerfile`, the registered name defaults to the parent directory name. Otherwise it defaults to the file stem. Registered image names must be unique within a project.

## Supported Build Operations and Limitations

Across the supported image-definition DSLs, Tensorlake currently materializes these build operations into the sandbox:

* `RUN`
* `WORKDIR`
* `ENV`
* `COPY`
* `ADD`

These metadata-oriented operations are preserved with the image definition but are not materialized into the snapshot:

* `CMD`
* `ENTRYPOINT`
* `EXPOSE`
* `HEALTHCHECK`
* `LABEL`
* `STOPSIGNAL`
* `VOLUME`

These operations are not currently supported for sandbox image creation:

* `ARG`
* `ONBUILD`
* `SHELL`
* `USER`

Additional limitations:

* Multi-stage Dockerfiles are not supported yet.
* `COPY` and `ADD` sources are read from the local filesystem relative to the Dockerfile build context.
* `COPY` and `ADD` currently assume a local build context. Remote URLs and advanced BuildKit-only features are not supported.
* `tl sbx image create` and SDK image builds use the current authenticated project context.
* `tl sbx image describe` shows the registered Dockerfile and snapshot metadata for a sandbox image.

## See Also

<CardGroup cols={3}>
  <Card title="Snapshots" icon="camera" href="/sandboxes/snapshots">
    Understand the underlying snapshot primitive used to save and restore sandbox state.
  </Card>

  <Card title="Lifecycle" icon="arrows-spin" href="/sandboxes/lifecycle">
    Learn which sandbox settings you can still override when launching from an image.
  </Card>

  <Card title="Skills in Sandboxes" icon="wand-magic-sparkles" href="/sandboxes/skills-in-sandboxes">
    Ship Tensorlake SDK docs inside sandbox images for agents and tools.
  </Card>
</CardGroup>