Skip to main content
A snapshot is a point-in-time copy of your Box’s filesystem. box resume and box fork restore from one.

​
What is captured

Captured

/home/user: your code, files, and configDocker named volumes: databases, app data

Not captured

The base OS and pre-installed tooling, which ship with the machine imageRunning processes, memory, open ports
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.

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

​
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

CLI
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.
curl
curl -sS "$BOX_API_BASE/boxes/bx_f7k2q9hd/snapshots/latest" \
  -H "Authorization: Bearer $BOX_API_KEY"
See the Snapshots API for the full surface.