Skip to main content
Prepare one sandbox: install your tools, clone your code, and set up your files. Then save it as a template and start many sandboxes from it. Each new sandbox starts with the files of the template. With the CLI, run 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:write scope to rename and delete templates, templates:write and snapshots:read to save a template, and sandboxes:write to create sandboxes. See API keys.
  • The sandbox to save must be running or stopped. See Create, get, and delete a sandbox.

Save a template

Send POST /v1/templates with a name and the ID of the sandbox in fromSandbox:
The API answers 202 with the template in the saving status:
  • For a running sandbox, the save takes a new snapshot first. So the template has each write until the save. The sandbox keeps running.
  • For a stopped sandbox, the save uses the last snapshot of the stop.
  • The name is unique in the workspace: 1 to 63 lowercase letters, digits, and hyphens.
Read the template with 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

Send template in POST /v1/sandboxes, with the name or the ID of a ready template:
The sandbox is 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/templates lists the templates of the workspace, newest first. Send name or status to filter the list. A key with templates:read is 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, and delete-many do up to 500 changes in one request.
See the Templates API reference. To do these steps in the app, see Use templates in the app.

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. Send POST /v1/templates/{id}/share-codes. label is optional. Use it to record who has the code:
The API answers 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:
The other workspace sends the code as template in POST /v1/sandboxes:
  • The template must be ready. Else the create answers 409.
  • 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-codes lists the codes of a template. The list shows codeEnd, the last 4 characters of each code, and lastUsedAt. It does not show the codes.

Revoke a share code

Send DELETE /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 are saving or ready count. See Plans.