The Files class from @cloudflare/sandbox moves files between your Worker and a running sandbox, and provides common file system operations. For more information, refer to Move files in and out of a sandbox.
Each sandbox name maps to a Durable Object, which starts a Linux instance when needed. Stopping the instance deletes the files on its disk. For more information, refer to Sandbox lifetime.
You can keep files from a sandbox in several ways, from a snapshot of the whole disk to one directory kept in R2:
| Goal | Guide | Trade-off |
|---|---|---|
| Continue an agent workspace in a later session | Save and restore a sandbox with snapshots | Saves the whole disk for 30 days after the last save or restore |
| Keep a workspace without explicit save calls | Save a sandbox automatically | Same as snapshots, plus an alarm in your Durable Object |
| Keep a project across images, or beyond 30 days | Back up a directory to R2 | Saves one directory, and your Durable Object stores each backup record |
| Share job inputs and outputs with other systems | Mount an R2 bucket | Renames, locks, and permissions do not work as they do on a local disk |
Snapshots do not include mounted directories, so a sandbox can use both. For example, a coding agent can keep its repository and dependencies in a snapshot, and write results to a mounted bucket for other Workers to read. For more information, refer to Sandbox lifetime.