vms template save <sandbox> <name>. See CLI reference. With the TypeScript SDK, call vms.saveTemplate(). See TypeScript SDK reference.
Write the code that saves a template and starts sandboxes from it.
Before you start
- You need an API key with the
templates:writescope to rename and delete templates,templates:writeandsnapshots:readto save a template, andsandboxes:writeto create sandboxes. See API keys. - The sandbox to save must be
runningorstopped. See Create, get, and delete a sandbox.
Save a template
SendPOST /v1/templates with a name and the ID of the sandbox in fromSandbox:
202 with the template in the saving status:
- For a
runningsandbox, the save takes a new snapshot first. So the template has each write until the save. The sandbox keeps running. - For a
stoppedsandbox, the save uses the last snapshot of the stop. - The name is unique in the workspace: 1 to 63 lowercase letters, digits, and hyphens.
GET /v1/templates/{id} until status is ready. If the status is failed, error tells why. Save the template again.
A template saves the same files as a snapshot. See Saved files.
Create a sandbox from a template
Sendtemplate in POST /v1/sandboxes, with the name or the ID of a ready template:
running when the system files of the template are back and each file of its home folders shows. The other files download in the background. The files that earlier sandboxes from the template opened first download before the other files. See Hydration. You can send any size. env and files of the create body are written after the files of the template.
A template is a full copy
- A template does not change when its sandbox changes, stops, or is deleted.
- A template has no expiry date. It stays until you delete it.
- A sandbox from a template does not change when you rename or delete the template.
- A template holds the profile of the desktop browser (
/home/user/.config/vms-browser), with its cookies and sign-ins. Sign out and delete the profile before you save a template that you share:rm -rf /home/user/.config/vms-browser.
List, rename, and delete templates
GET /v1/templateslists the templates of the workspace, newest first. Sendnameorstatusto filter the list. A key withtemplates:readis enough.PATCH /v1/templates/{id}with{"name": "new-name"}renames a template.DELETE /v1/templates/{id}deletes a template. Its saved files are deleted within 24 hours after each sandbox from the template has a full snapshot of its own. A sandbox that still downloads its files from the template keeps working.POST /v1/templates/create-many,update-many, anddelete-manydo up to 500 changes in one request.
Share a template with another workspace
A share code lets another workspace create sandboxes from your template. The other workspace cannot see, list, or download the template or its files. It gets the files only in its own sandboxes. SendPOST /v1/templates/{id}/share-codes. label is optional. Use it to record who has the code:
201 with the share code. The response shows code only one time. Keep it in a safe place, and give it to the other workspace:
template in POST /v1/sandboxes:
- The template must be
ready. Else the create answers409. - The other workspace pays for its sandboxes. Your workspace pays for the template.
- A template can have 20 share codes.
GET /v1/templates/{id}/share-codeslists the codes of a template. The list showscodeEnd, the last 4 characters of each code, andlastUsedAt. It does not show the codes.
Revoke a share code
SendDELETE /v1/templates/{id}/share-codes/{codeId}. POST /v1/templates/{id}/share-codes/delete-many revokes up to 500 codes in one request.
- A create with a revoked code answers
404. - Sandboxes that were created with the code continue to run. They keep their files after a stop and a resume.
- A delete of the template also revokes each of its codes.
Price
The plan includes as many templates as saved snapshots: 20 on the $20 plan and 2 in the trial. Each template above this count costs $0.04 each day. Templates that aresaving or ready count. See Plans.