> ## Documentation Index
> Fetch the complete documentation index at: https://vms.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Save a sandbox as a template

> Save the files of a sandbox as a named template, create many sandboxes from it, share it with another workspace, and rename or delete the template.

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](https://vms.dev/docs/reference/cli.md#template). With the TypeScript SDK, call `vms.saveTemplate()`. See [TypeScript SDK reference](https://vms.dev/docs/reference/typescript-sdk.md#savetemplate-and-waituntiltemplateready).

Write the code that saves a template and starts sandboxes from it.

Save a sandbox as a template with POST /v1/templates, a name, and fromSandbox.
Read GET /v1/templates/{id} until the status is ready. Stop if the status is failed, and show me the error message.
Create sandboxes with POST /v1/sandboxes and template set to the name of the template.
Do not ask me to share my API key.

## 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](https://vms.dev/docs/workspace/api-keys.md).
* The sandbox to save must be `running` or `stopped`. See [Create, get, and delete a sandbox](https://vms.dev/docs/sandboxes/create-and-delete.md).

## Save a template

Send `POST /v1/templates` with a `name` and the ID of the sandbox in `fromSandbox`:

```typescript TypeScript theme={null}
const response = await fetch("https://vms.dev/api/v1/templates", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VMS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "node-22-base", fromSandbox: sandbox.id }),
});

const template = await response.json();

console.log(response.status, template.id, template.status);
```

```bash cURL theme={null}
curl https://vms.dev/api/v1/templates \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "node-22-base", "fromSandbox": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja"}'
```

The API answers `202` with the template in the `saving` status:

```json theme={null}
{
  "id": "tpl_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "name": "node-22-base",
  "status": "saving",
  "size": "small",
  "sourceSandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "storedBytes": null,
  "error": null,
  "readyAt": null,
  "createdAt": "2026-11-16T09:30:00.000Z",
  "updatedAt": "2026-11-16T09:30:00.000Z"
}
```

* 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.

| Status | Meaning |
| - | - |
| `saving` | The template saves the files of the sandbox. |
| `ready` | You can create sandboxes from the template. `storedBytes` shows the compressed size of its files. |
| `failed` | The save did not complete, for example because the sandbox was deleted first, or because a stopped sandbox has no saved files (`no_snapshot`). |

A template saves the same files as a snapshot. See [Saved files](https://vms.dev/docs/reference/saved-files.md).

## Create a sandbox from a template

Send `template` in `POST /v1/sandboxes`, with the name or the ID of a `ready` template:

```typescript TypeScript theme={null}
const response = await fetch("https://vms.dev/api/v1/sandboxes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VMS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ size: "small", template: "node-22-base" }),
});

const sandbox = await response.json();
```

```bash cURL theme={null}
curl https://vms.dev/api/v1/sandboxes \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"size": "small", "template": "node-22-base"}'
```

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](https://vms.dev/docs/sandboxes/stop-and-resume.md#hydration). You can send any size. `env` and `files` of the create body are written after the files of the template.

| Error | Status | When |
| - | - | - |
| `not_found` | 404 | The workspace has no template with this name or ID, or the share code does not exist or was revoked. |
| `conflict` | 409 | The template is `saving` or `failed`. |

## 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](https://vms.dev/docs/api-reference/templates/list-templates.md). To do these steps in the app, see [Use templates in the app](https://vms.dev/docs/sandboxes/templates-in-the-app.md).

## 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:

```typescript TypeScript theme={null}
const response = await fetch(
  `https://vms.dev/api/v1/templates/${template.id}/share-codes`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VMS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ label: "partner-team" }),
  },
);

const shareCode = await response.json();

console.log(shareCode.code);
```

```bash cURL theme={null}
curl https://vms.dev/api/v1/templates/tpl_06d8k3m7q2v9x4b1n5c0e8f2ja/share-codes \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "partner-team"}'
```

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:

```json theme={null}
{
  "id": "tsc_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "templateId": "tpl_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "label": "partner-team",
  "codeEnd": "8f2j",
  "lastUsedAt": null,
  "createdAt": "2026-11-16T09:30:00.000Z",
  "code": "share_9x4b1n5c0e8f2ja06d8k3m7q2v9x4b1n5c0e8f2j"
}
```

The other workspace sends the code as `template` in `POST /v1/sandboxes`:

```typescript TypeScript theme={null}
const response = await fetch("https://vms.dev/api/v1/sandboxes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VMS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ size: "small", template: process.env.SHARE_CODE }),
});

const sandbox = await response.json();
```

```bash cURL theme={null}
curl https://vms.dev/api/v1/sandboxes \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size": "small", "template": "share_9x4b1n5c0e8f2ja06d8k3m7q2v9x4b1n5c0e8f2j"}'
```

* 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](https://vms.dev/docs/reference/plans.md#plans).

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.