Backup and restore API for Sandbox SDK

Sandboxes now support createBackup() and restoreBackup() methods for creating and restoring point-in-time snapshots of directories.

This allows you to restore environments quickly. For instance, in order to develop in a sandbox, you may need to include a user's codebase and run a build step. Unfortunately git clone and npm install can take minutes, and you don't want to run these steps every time the user starts their sandbox.

Now, after the initial setup, you can just call createBackup(), then restoreBackup() the next time this environment is needed. This makes it practical to pick up exactly where a user left off, even after days of inactivity, without repeating expensive setup steps.

const sandbox = getSandbox(env.Sandbox, "my-sandbox");

// Make non-trivial changes to the file system
await sandbox.gitCheckout(endUserRepo, { targetDir: "/workspace" });
await sandbox.exec("npm install", { cwd: "/workspace" });

// Create a point-in-time backup of the directory
const backup = await sandbox.createBackup({ dir: "/workspace" });

// Store the handle for later use
await env.KV.put(`backup:${userId}`, JSON.stringify(backup));

// ... in a future session...

// Restore instead of re-cloning and reinstalling
await sandbox.restoreBackup(backup);

Backups are stored in R2 and can take advantage of R2 object lifecycle rules to ensure they do not persist forever.

Key capabilities:

• Persist and reuse across sandbox sessions — Easily store backup handles in KV, D1, or Durable Object storage for use in subsequent sessions
• Usable across multiple instances — Fork a backup across many sandboxes for parallel work
• Named backups — Provide optional human-readable labels for easier management
• TTLs — Set time-to-live durations so backups are automatically removed from storage once they are no longer needed

Note

Backup and restore currently uses a FUSE overlay. Soon, native snapshotting at a lower level will be added to Containers and Sandboxes, improving speed and ergonomics. The current backup functionality provides a significant speed improvement over manually recreating a file system, but it will be further optimized in the future. The new snapshotting system will use a similar API, so changing to this system will be simple once it is available.

To get started, refer to the backup and restore guide for setup instructions and usage patterns, or the Backups API reference for full method documentation.