Templates

Save a prepared sandbox as a template and start new sandboxes from it in seconds.

A template is a saved copy of a sandbox’s disk. Prepare a sandbox once, with your packages, repositories and configuration, save it, and every sandbox you start from the template begins exactly there.

pols template save web node-app --description "Node 24 with the app's dependencies"
pols template ls
pols new --name review --template node-app
pols template rm node-app

Saving

pols template save SANDBOX NAME (POST /v1/templates) copies the disk of a running or stopped sandbox. The save takes about a second on the host; the template starts in status creating and becomes ready when the copy is done. The CLI waits for that; over the API, poll GET /v1/templates/{template} until status is ready before using it. A save that fails stays visible with status failed until it has been cleaned up.

A template does not keep the source sandbox’s environment variables or vault entries. Name the secrets again when you create sandboxes from it.

Saving a running sandbox copies its disk as it is at that moment, without the contents of memory. Files an application has not yet written to disk are not in the template; stop the sandbox first, or flush and pause the application, when that matters.

Using a template

Pass the template’s name or ID to pols new --template. The new sandbox gets a copy of the template’s disk, with a new machine ID and new SSH host keys. Its size must have a disk at least as large as the template’s (disk_gib).

ubuntu-24.04 is the system template every sandbox starts from by default. It is provided for every org and cannot be deleted.

Deleting

pols template rm NAME (DELETE /v1/templates/{template}) deletes one of your org’s own templates. The API answers 202 and removes it in the background; a GET returns 404 once it is gone. The CLI waits for that. Sandboxes already created from the template are not affected. While a template is still being saved, or a sandbox is still being created from it, deleting it is refused with 409 conflict.

Your org may have up to 10 templates of its own; see quotas.