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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.