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

# Download a snapshot

> Look inside a snapshot and download its files, also from a stopped sandbox. Get one file, one folder or the whole home folder.

You can read the files of a snapshot without starting the sandbox. The sandbox can be stopped.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
boat snapshot pull bx_f7k2q9hd -o ./restore    # newest snapshot of this sandbox
```

## Look inside and download

```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
boat snapshots                                 # across your sandboxes
boat snapshots bx_f7k2q9hd                     # one sandbox
boat snapshot latest bx_f7k2q9hd
boat snapshot tree <snapshotId>                # files + sizes
boat snapshot pull <snapshotId> -o ./restore   # download and reassemble
boat snapshot pull <snapshotId> -o ./restore --path /home/user/project/report   # one folder only
```

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl -sS "$BOAT_API_BASE/snapshots" \
  -H "Authorization: Bearer $BOAT_API_KEY"
curl -sS "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/snapshots/latest" \
  -H "Authorization: Bearer $BOAT_API_KEY"
curl -sS "$BOAT_API_BASE/snapshots/<snapshotId>/tree" \
  -H "Authorization: Bearer $BOAT_API_KEY"

# one file, or a folder as .tar, straight from a snapshot
curl -sS "$BOAT_API_BASE/snapshots/<snapshotId>/files?path=projects/app/.env" \
  -H "Authorization: Bearer $BOAT_API_KEY" -o .env
curl -sS "$BOAT_API_BASE/snapshots/<snapshotId>/files?path=projects/app" \
  -H "Authorization: Bearer $BOAT_API_KEY" -o app.tar

# a changed system file: use its absolute path
curl -sS "$BOAT_API_BASE/snapshots/<snapshotId>/files?path=/etc/nginx/nginx.conf" \
  -H "Authorization: Bearer $BOAT_API_KEY" -o nginx.conf
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
await sandbox.listSnapshots();                                    // across your sandboxes
await sandbox.listSandboxSnapshots({ sandboxId: "bx_f7k2q9hd" }); // one sandbox
await sandbox.getLatestSandboxSnapshot({ sandboxId: "bx_f7k2q9hd" });
await sandbox.getSnapshotTree({ snapshotId: "<snapshotId>" });    // files + sizes

const file = await sandbox.getSnapshotFile({
  snapshotId: "<snapshotId>",
  path: "projects/app/.env",
});
const archive = await sandbox.getSnapshotDownload({ snapshotId: "<snapshotId>" });
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
sandbox.list_snapshots()                          # across your sandboxes
sandbox.list_sandbox_snapshots("bx_f7k2q9hd")     # one sandbox
sandbox.get_latest_sandbox_snapshot("bx_f7k2q9hd")
sandbox.get_snapshot_tree("<snapshotId>")         # files + sizes

file = sandbox.get_snapshot_file("<snapshotId>", path="projects/app/.env")
archive = sandbox.get_snapshot_download("<snapshotId>")
```

`$BOAT_API_BASE` is `https://boat.dev/api/v1`.

## What `pull` downloads

`boat snapshot pull` writes two folders:

| Folder | Holds |
| - | - |
| `home_user/` | Your `/home/user` |
| `docker/` | Your Docker named volumes |

They hold the files exactly as they were at that snapshot.

`--path` extracts only the files under that path. It still downloads the whole snapshot.

`pull` recreates symlinks that stay inside `home_user/` and `docker/`. On every platform it skips a link that points outside that tree, such as `/etc`, or one that resolves through another symlink. On Windows it also skips links unless Developer Mode is on or the shell runs as administrator. It prints how many entries it skipped.

`pull` is for your home folder and your volumes. A snapshot also saves your changes in `/etc`, `/usr`, `/opt`, `/root`, `/srv` and `/var`, other home folders, and folders that you create at `/`. To get one of these files, ask the file endpoint for its absolute path, as in the curl example above.

## Download a saved snapshot

A saved snapshot downloads the same way. Use its snapshot id, not its name.

1. Get the id: `GET $BOAT_API_BASE/saved-snapshots/<name>` returns it in `snapshot.snapshotId`.
2. Download: `boat snapshot pull <snapshotId> -o ./restore`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl -sS "$BOAT_API_BASE/saved-snapshots/web-stack" \
  -H "Authorization: Bearer $BOAT_API_KEY"
```

The SDKs have no `pull`. Use `getSnapshotDownload`, then put the files together on your computer.

You can also see the files, and download them, in the [Snapshots](https://boat.dev/dashboard?tab=snapshots) tab of the dashboard.

For all calls, read the [Snapshots API](https://docs.boat.dev/api/reference/snapshots/list-snapshots.md).

## Which snapshots you can download

The newest snapshot of a sandbox stays while it runs and for at least 14 days after it stops. After that, automated retention cleanup can delete it once enabled ([details](https://docs.boat.dev/snapshots/stop.md#keep-a-stopped-sandbox-longer-than-14-days)). Older snapshots stay in the list only for a short time, usually less than a day. Resume and fork always use the newest one. Read [How long boat keeps data](https://docs.boat.dev/data-retention#how-long-boat-keeps-data) and [Restore an older snapshot](https://docs.boat.dev/snapshots/resume-and-fork.md#restore-an-older-snapshot-roll-back).

* After the deletion, the sandbox stays in your list as expired. Resume and fork fail with `409 snapshot_data_expired`.
* To keep the data longer, save a saved snapshot before the deletion: `boat snapshot <id> <name>`. This works on a stopped sandbox. A saved snapshot does not expire.

If you need more time, write to [support](https://docs.boat.dev/support.md).

## Delete a sandbox

A stop keeps the snapshots. A delete erases them for good. To delete a sandbox or one snapshot, read [Delete a sandbox or snapshot](https://docs.boat.dev/data-retention/delete.md).


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