> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2501.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> VM base images available for incus and lima modes

Templates are stopped VM instances that the runner clones from for each scenario run. Each template is a Debian 12 base image pre-provisioned with specific software. Cloning is fast (a few seconds); provisioning only happens once, when the template is first created.

Template instances are named `template-{name}` in incus/lima (e.g. `template-debian-docker`).

***

## Available Templates

| Template            | vCPUs | RAM  | Description                                                |
| ------------------- | ----- | ---- | ---------------------------------------------------------- |
| `debian-base`       | 1     | 1 GB | Debian 12 with basic tools (curl, wget, python3, vim, git) |
| `debian-docker`     | 1     | 2 GB | Debian 12 with Docker CE pre-installed                     |
| `debian-podman`     | 1     | 2 GB | Debian 12 with Podman pre-installed (rootful, cgroupfs)    |
| `debian-k3s`        | 2     | 2 GB | Debian 12 with k3s (lightweight Kubernetes) pre-installed  |
| `debian-localstack` | 1     | 2 GB | Debian 12 with AWS CLI v2 and moto server on port 4566     |

All templates use a 10 GB disk.

***

## Auto-Initialization

Templates are created automatically the first time a scenario references them. When the runner starts and a referenced template doesn't exist as a stopped instance, it:

1. Boots a fresh VM from the Debian 12 cloud image
2. Runs the provisioning playbooks (installs Docker, k3s, etc.)
3. Stops and saves the VM as `template-{name}`

This happens once per template per machine. Subsequent runs clone from the existing template and start in seconds.

***

## Listing Templates

Check which templates have been initialized:

<Tabs>
  <Tab title="incus">
    ```bash theme={null}
    incus list template-
    ```
  </Tab>

  <Tab title="lima">
    ```bash theme={null}
    limactl list | grep template-
    ```
  </Tab>
</Tabs>

***

## Deleting a Template

Delete a template to force re-initialization on the next run. Useful if a template becomes stale or you want to pick up a newer base image.

<Tabs>
  <Tab title="incus">
    ```bash theme={null}
    incus delete template-debian-docker
    ```
  </Tab>

  <Tab title="lima">
    ```bash theme={null}
    limactl delete template-debian-docker
    ```
  </Tab>
</Tabs>

<Warning>
  Deleting a template does not affect existing VM clones. The next run that references the deleted template will re-provision it from scratch, which takes a few minutes.
</Warning>

***

## Purging Stale Clones

If a `run` or `sandbox prepare` session is interrupted, clone VMs may be left behind. Use `purge-vms` to clean them up. Template instances are never touched.

```bash theme={null}
2501 runner sandbox purge-vms [-m incus|lima]
```

If `-m` is omitted, both providers are tried.