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

# Read the files of a snapshot

> List a folder of a snapshot, download one file or a folder as a tar, or download the whole snapshot, with no running sandbox.

Read the saved files of a snapshot with no running sandbox. You pay for no sandbox, and the sandbox can be stopped or deleted.

With the CLI, run `vms snapshot ls` and `vms snapshot get`. See [CLI reference](https://vms.dev/docs/reference/cli.md#snapshot). With the TypeScript SDK, call `vms.latestSnapshot()` and `vms.readSnapshotFile()`. See [TypeScript SDK reference](https://vms.dev/docs/reference/typescript-sdk.md#latestsnapshot-and-readsnapshotfile).

Write the code that gets my files back from a snapshot.

List the snapshots of my sandbox with GET /v1/sandboxes/{id}/snapshots, and take the newest one.
List /home/user in it with GET /v1/snapshots/{id}/tree.
Download the folder that I name with GET /v1/snapshots/{id}/files, and unpack the tar.
Do not ask me to share my API key.

## Before you start

* You need an API key with the `snapshots:read` scope. To list the snapshots of a sandbox, the key also needs `sandboxes:read`. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* You need the ID of a snapshot. `GET /v1/sandboxes/{id}/snapshots` lists them. See [List the snapshots](https://vms.dev/docs/reference/saved-files.md#list-the-snapshots).

To browse and download the files in the app, open the sandbox on the **Sandboxes** page and choose the **Snapshots** tab. See [Browse the files of a snapshot](https://vms.dev/docs/sandboxes/in-the-app.md#browse-the-files-of-a-snapshot).

## What a snapshot holds

A snapshot holds the saved files of the sandbox at that time: the files and folders that are different from the base image. It does not hold the operating system or the preinstalled tools. See [Saved files reference](https://vms.dev/docs/reference/saved-files.md).

Each snapshot shows the files as they were when it was saved. To get an older version of a file, read an older snapshot.

## List a folder

Send `GET /v1/snapshots/{id}/tree` with the absolute `path` of a folder. The default is `/`.

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

const { entries } = await response.json();

for (const entry of entries) console.log(entry.type, entry.path, entry.size);
```

```bash cURL theme={null}
curl "https://vms.dev/api/v1/snapshots/$SNAPSHOT_ID/tree?path=/home/user" \
  -H "Authorization: Bearer $VMS_API_KEY"
```

The API answers `200` with the saved files and folders in the folder, sorted by name:

```json theme={null}
{
  "snapshotId": "snp_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2jb",
  "path": "/home/user",
  "entries": [
    {
      "name": "notes.md",
      "path": "/home/user/notes.md",
      "type": "file",
      "size": 4,
      "mode": "0644",
      "uid": 1000,
      "gid": 1000,
      "target": null,
      "modifiedAt": "2026-11-16T09:12:30.512Z"
    },
    {
      "name": "project",
      "path": "/home/user/project",
      "type": "directory",
      "size": null,
      "mode": "0755",
      "uid": 1000,
      "gid": 1000,
      "target": null,
      "modifiedAt": "2026-11-16T09:10:02.004Z"
    }
  ]
}
```

| Field | Value |
| - | - |
| `type` | `file`, `directory`, `symlink`, `fifo`, `char`, or `block` |
| `size` | The size of a file in bytes. `null` for the other types. |
| `mode`, `uid`, `gid` | The permissions and the owner. `null` for a folder that the snapshot shows only because it holds saved files. |
| `target` | The target of a symbolic link |
| `modifiedAt` | The time of the last change of the file |

## Download a file or a folder

Send `GET /v1/snapshots/{id}/files` with the absolute `path`:

* For a file, the API answers with its content, as `application/octet-stream`.
* For a folder, the API answers with a tar of the folder and of each saved file and folder in it, as `application/x-tar`. The names in the tar start at the folder, such as `project/main.ts`.

```typescript TypeScript theme={null}
import { writeFile } from "node:fs/promises";

const response = await fetch(
  `https://vms.dev/api/v1/snapshots/${snapshotId}/files?path=/home/user/project`,
  { headers: { Authorization: `Bearer ${process.env.VMS_API_KEY}` } },
);

if (!response.ok) throw new Error((await response.json()).error.message);

await writeFile("project.tar", Buffer.from(await response.arrayBuffer()));
```

```bash cURL theme={null}
curl "https://vms.dev/api/v1/snapshots/$SNAPSHOT_ID/files?path=/home/user/project" \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -o project.tar
tar -xf project.tar
```

## Download the whole snapshot

Send `GET /v1/snapshots/{id}/download`. The API streams a tar of each saved file and folder of the snapshot. The names in the tar have no leading `/`, such as `home/user/notes.md`.

```bash cURL theme={null}
curl "https://vms.dev/api/v1/snapshots/$SNAPSHOT_ID/download" \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -o snapshot.tar
```

If the download stops with an error, the tar is not complete. Download it again.

## Read a snapshot of a deleted sandbox

After you delete a sandbox, its saved files stay for up to 24 hours. Until then, `GET /v1/sandboxes/{id}/snapshots` lists its snapshots, and you can read them as on this page. After that, the API answers `404`. See [When saved files are deleted](https://vms.dev/docs/reference/saved-files.md#when-saved-files-are-deleted).

## Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `invalid` | `path` is not an absolute path. |
| `403` | `forbidden` | The API key does not have the `snapshots:read` scope. |
| `404` | `not_found` | The workspace has no snapshot with this ID, or the snapshot has no saved file or folder at this path. |
| `409` | `conflict` | The tree path is a file, or the files path is a link or a device. |
| `409` | `snapshot_old_format` | The snapshot uses an old format. Resume the sandbox to read its files. |
| `429` | `rate_limited` | Too many snapshot reads are open. Wait `retryAfterSeconds`, then try again. |
| `503` | `unavailable` | Could not read the snapshot. Try again. |

An older snapshot can use the old format. `GET /v1/snapshots/{id}/tree` works for it, but a download of its files answers `409 snapshot_old_format`. Resume the sandbox and read the files with [the file routes](https://vms.dev/docs/sandboxes/files.md). After the next full snapshot of the sandbox, you can download each file of its new snapshots. See [When a sandbox saves its files](https://vms.dev/docs/reference/saved-files.md#when-a-sandbox-saves-its-files).

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


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