Skip to main content
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. With the TypeScript SDK, call vms.latestSnapshot() and vms.readSnapshotFile(). See TypeScript SDK reference.

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

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.
  • You need the ID of a snapshot. GET /v1/sandboxes/{id}/snapshots lists them. See 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.

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. 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 /.
The API answers 200 with the saved files and folders in the folder, sorted by name:

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.

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

Errors

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. After the next full snapshot of the sandbox, you can download each file of its new snapshots. See When a sandbox saves its files.