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

# Saved files reference

> The files that each snapshot of a sandbox saves and does not save, the .vmsignore file, the snapshot fields, and when saved files are deleted.

This reference gives the files that a sandbox saves, the files that it does not save, and the fields that show the snapshots.

Check which files of my sandbox are saved.

Read this reference and list the folders that my sandbox saves and does not save.
If my project writes large files that I do not need, write a .vmsignore file for them.
Show me how to list the snapshots with GET /v1/sandboxes/{id}/snapshots.
Do not ask me to share my API key.

## When a sandbox saves its files

* Each minute, a `running` sandbox saves the files that changed since its last snapshot. Each snapshot is one generation in the chain of the sandbox.
* Each stop takes a last snapshot after the pre-stop script. See [Stop and resume a sandbox](https://vms.dev/docs/sandboxes/stop-and-resume.md).
* The first snapshot holds each saved file that is different from the base image. Its `full` field is `true`.
* A minute with no change adds no snapshot and uploads nothing. Only `snapshotVerifiedAt` and `lastSnapshotLagSeconds` change.
* A deleted file is saved as a deletion.
* If a snapshot fails, the next snapshot one minute later saves the same changes.
* After the guest agent starts again, the next snapshot holds each saved file again, and its `full` field is `true`.
* When the chain has 50 snapshots from its latest full snapshot, the next snapshot holds each saved file again. Its `full` field is `true`, and its `parentId` is `null`. So a restore reads at most about 50 snapshots.
* After a resume from the saved files, the chain continues. The next snapshot holds only the changes since the resume. See [Resume from the saved files](https://vms.dev/docs/sandboxes/stop-and-resume.md#resume-from-the-saved-files).

## Saved

| What | Where |
| - | - |
| Home folders | `/home/<user>` and `/root` |
| Folders that you make at `/` | For example `/workspace` or `/data` |
| Docker volumes, containers, and images | `/var/lib/docker` |
| Changes to the system folders | `/etc`, `/usr`, `/opt`, `/srv`, and `/var` |

A saved file keeps its contents, its owner, its permissions, its extended attributes, and the holes of a sparse file. A symbolic link keeps its target.

## Not saved

| What | Where |
| - | - |
| The operating system and the preinstalled tools | Each file that is the same as in the base image |
| Temporary files | `/tmp` and `/var/tmp` |
| Caches | `/var/cache`, `/root/.cache`, and `/home/<user>/.cache` |
| The caches of the desktop browser | The `Cache`, `Code Cache`, `GPUCache`, and other cache folders in `/home/<user>/.config/vms-browser`. The browser profile, with its cookies and sign-ins, is saved. |
| The desktop pairing keys | `/var/lib/vms-desktop`. Each sandbox makes its own keys. |
| The system journal | `/var/log/journal` |
| The Docker build cache | `/var/lib/docker/buildkit` |
| Running programs and the memory | |
| Other file systems that you mount | |
| A path that a `.vmsignore` file names | See [.vmsignore](#vmsignore) |

## .vmsignore

A `.vmsignore` file excludes more paths from the snapshots. It has the rules of a `.gitignore` file. Put it in a folder. Its rules apply to that folder and to the folders below it.

```text /home/user/.vmsignore theme={null}
node_modules/
*.log
!keep.log
```

A `.vmsignore` file stops new snapshots of a path. A snapshot from before the change keeps the path.

## Snapshot fields of a sandbox

`GET /v1/sandboxes/{id}` gives these fields:

| Field | Value |
| - | - |
| `latestSnapshotAt` | When the latest snapshot with a change was saved |
| `snapshotVerifiedAt` | When the sandbox last saved its changes, or found no change |
| `lastSnapshotLagSeconds` | The seconds between the last two times in `snapshotVerifiedAt`. A change can wait this long before it is saved. |
| `snapshotProgress` | The part of the current snapshot that is done, from 0 to 1. `null` when no snapshot runs. |

## List the snapshots

`GET /v1/sandboxes/{id}/snapshots` lists the snapshots of a sandbox, newest first. `GET /v1/sandboxes/{id}/snapshots/{snapshotId}` gives one snapshot. Both need the `sandboxes:read` scope. They also work for a deleted sandbox until its saved files are deleted.

To list and download the files of a snapshot, see [Read the files of a snapshot](https://vms.dev/docs/sandboxes/snapshot-files.md).

```typescript TypeScript theme={null}
const response = await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/snapshots`,
  { headers: { Authorization: `Bearer ${process.env.VMS_API_KEY}` } },
);

const { data, nextCursor } = await response.json();
```

```bash cURL theme={null}
curl "https://vms.dev/api/v1/sandboxes/$SANDBOX_ID/snapshots" \
  -H "Authorization: Bearer $VMS_API_KEY"
```

| Field | Value |
| - | - |
| `id` | The snapshot ID, with the prefix `snp_` |
| `generation` | The position in the chain. The first snapshot is 0. |
| `parentId` | The snapshot before this one. `null` for the first snapshot, and for a full snapshot after a chain of 50. |
| `full` | `true` if the snapshot holds each saved file. `false` if it holds the changes since `parentId`. |
| `changedPaths` | The number of saved files, folders, and links |
| `deletedPaths` | The number of saved deletions |
| `uploadedBytes` | The compressed size of the snapshot |
| `startedAt`, `completedAt` | When the snapshot started and ended |

To get the next page, send the `nextCursor` of the last page as `cursor`.

## When saved files are deleted

Each day, the saved files that no restore needs are deleted:

| Saved files | Deleted |
| - | - |
| The snapshots before the latest full snapshot of a sandbox | Within 24 hours after the full snapshot. The list does not show them. |
| The snapshots of a stopped sandbox | Within 24 hours after `dataExpiresAt`, 30 days after the stop. See [How long a stopped sandbox keeps its files](https://vms.dev/docs/sandboxes/stop-and-resume.md#how-long-a-stopped-sandbox-keeps-its-files). |
| The snapshots of a deleted sandbox | Within 24 hours after the delete. Until then, you can [read their files](https://vms.dev/docs/sandboxes/snapshot-files.md#read-a-snapshot-of-a-deleted-sandbox). |

A deleted snapshot cannot be restored.

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


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