# Templates

> Save a stopped machine as a named template and create machines from it with the same plan, image, region, and machine name, each with its own identity.

A **template** is a stopped machine saved as a named, warm [snapshot](/docs/guides/snapshots). Machines created from it start from its disk and memory with the template's plan, image, region, resources, backend, and machine name, and their own identity. An organization keeps at most **10** templates.

> [!NOTE]
> Use the console's **Templates** page, `vy templates`, the SDKs, or the HTTP API below. Owners, Admins, and Operators save and delete templates; every member can list them and anyone who can create machines can create from one.

## Save a template

The machine must be requested and observed stopped (`409 machine_not_stopped`).

```sh
curl -X POST "$VMYARD_API_URL/v1/templates" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"machine_id": "'"$MACHINE_ID"'", "name": "python-base"}'
```

- `name` is a lowercase letter or digit followed by up to 63 of `a-z`, `0-9`, `.`, `_`, and `-`. It is unique among the organization's live templates (`409 template_name_taken`); a deleted template's name can be reused at once.
- An eleventh template is `409 template_limit_reached`.

The answer is `202` like a snapshot push; the template is `pending` until it is `ready` or `failed`, and a successful save emits the `template.ready` webhook.

## Create a machine from a template

Send `template` (its name or ID) to `POST /v1/machines`:

```sh
curl -X POST "$VMYARD_API_URL/v1/machines" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"template": "python-base", "name": "worker-1", "auto_stop_after_seconds": 7200}'
```

The template fixes `tenant_alias`, `plan`, `image`, `region`, `resources`, and `backend`: leave them out, or send exactly the template's values (anything else is `422`). Display `name`, auto-stop, [idle sleep](/docs/concepts/idle-sleep), the [environment](/docs/guides/environments) choice, and a [setup script](/docs/guides/setup-scripts) are yours to choose; the environment is applied after the restore, like any create.

The machine is restored running, with its own machine ID, host name, and SSH host keys, and no ports or SSH access. A template that doesn't exist is `422 unknown_template`; one that isn't `ready` is `409 snapshot_not_ready`. Creates from a template are admitted by billing like any create. A replay of the same `Idempotency-Key` and body succeeds even after the template was deleted.

In the console, **Create machine** on a template opens the create page with the plan, image, region, and machine name locked to the template.

## List and delete

`GET /v1/templates` lists templates; `GET /v1/templates/{template}` and `DELETE /v1/templates/{template}` take a name or ID. Deleting answers `204`; machines created from the template keep running. A save that hasn't settled can't be deleted yet (`409 snapshot_pending`).