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

# Snapshots

> What a Box snapshot captures, how it is stored, and how long it is kept.

A snapshot is a point-in-time copy of your Box's **filesystem**. `box resume` and `box fork` restore from one.

## What is captured

<Columns cols={2}>
  <Card title="Captured" icon="check">
    `/home/user`: your code, files, and config

    Docker **named volumes**: databases, app data
  </Card>

  <Card title="Not captured" icon="xmark">
    The base OS and pre-installed tooling, which ship with the machine image

    Running processes, memory, open ports
  </Card>
</Columns>

Packages you install yourself (`apt`, `snap`) are recorded and **reinstalled automatically** when a Box resumes or forks, so your environment comes back, not just your files.

After a resume or fork, restart your processes. See [Long-Running Tasks](/box/long-running-tasks).

## How it works

Snapshots are **incremental**: the first is a full base, each later one stores only what changed (compressed, content-addressed, deduped against the base image). They are taken **periodically** while the Box runs and again when it **stops**.

```mermaid theme={null}
flowchart LR
  A[Box filesystem<br/>/home/user + Docker volumes] -->|periodic + on stop| B[Incremental snapshot<br/>base + deltas]
  B --> C[(Object storage)]
  C -->|box resume| D[Same Box, restored]
  C -->|box fork| E[New Box, same state]
```

## Why filesystem, not the VM

Snapshots capture the filesystem, independent of the machine running underneath. Today a Box is a Hetzner VPS, but a Box is meant to become anything: a Linux server, a Mac or Windows machine in the cloud, or a physical device. A filesystem snapshot stays portable across all of them, restores fast, stays small, and lets us filter what's captured as needs grow. A whole-VM image would tie you to one kind of machine.

## Retention

Snapshots are kept for up to **30 days**. Superseded snapshots are cleaned up continuously as new ones are taken; the 30-day window is the outer limit. The most recent snapshot for a Box is always the one used by resume and fork.

## Inspect and download

```bash CLI theme={null}
box snapshots                 # list snapshots across your boxes
box snapshot latest bx_f7k2q9hd
box snapshot tree <snapshotId>      # files + sizes
box snapshot pull <snapshotId> -o ./restore   # download and reassemble
```

`pull` writes two subfolders, `home_user/` (your `/home/user`) and `docker/` (named volumes), reflecting exactly the files that were live at that snapshot.

```bash curl theme={null}
curl -sS "$BOX_API_BASE/boxes/bx_f7k2q9hd/snapshots/latest" \
  -H "Authorization: Bearer $BOX_API_KEY"
```

See the [Snapshots API](/box/api/reference/snapshots/list-snapshots) for the full surface.

## Related

* [Long-Running Tasks](/box/long-running-tasks)
* [Machines](/box/machines)