Backup and restore snapshot a sandbox directory into an R2 archive, then bring that tree back later. The public API is the same in production and in wrangler dev. The restore mechanism is not.
Use backups when you want a project directory such as /workspace to return later. Use bucket mounts when a separate storage path such as /data should persist independently of the sandbox filesystem.
In production, restoreBackup() mounts the squashfs archive with FUSE overlayfs:
- The backup is a read-only lower layer.
- New writes go to a writable upper layer.
- The original archive in R2 does not change.
- Restoring the same handle again discards the upper layer.
The overlay exists only while the container is running. When the sandbox sleeps or the container restarts, the mount is gone and the directory is empty. Store the DirectoryBackup handle and restore again.
With localBucket: true, wrangler dev extracts the archive with unsquashfs. The target directory is replaced. There is no overlay, so local restore does not reproduce production FUSE behavior.
Overlayfs treats the lower and upper layers as different devices. A rename that moves a directory from the restored lower layer into the writable upper layer can fail with EXDEV (cross-device link not permitted).
Vite does this with node_modules/.vite/deps. Omit that directory from the backup, or delete it after restore.
For the procedure, refer to Exclude generated caches.
- Backup and restore - Create, restore, and exclude caches
- Backups API - Method signatures and options
- Sandbox lifecycle - What happens when a sandbox sleeps