Skip to content
VMYardDocs

Guides

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.

View as Markdown
On this page

A template is a stopped machine saved as a named, warm snapshot. 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.

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, the environment choice, and a setup script 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).