Work with files in a sandbox

Last updated Oct 22, 2026 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.

Persistence

You can keep files from a sandbox in several ways, from a snapshot of the root filesystem 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 root filesystem, but not mounted directories
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

Combine approaches

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.

Was this helpful?

YesNo

On this page

Work with files in a sandbox - 图1Docs

{"@context":"https://schema.org","@type":"WebPage","@id":"https://developers.cloudflare.com/sandbox/files/#page","headline":"Work with files in a sandbox","description":"Move files in and out of a sandbox, keep a workspace after its instance stops, and share files through R2.","url":"https://developers.cloudflare.com/sandbox/files/","inLanguage":"en","image":"https://developers.cloudflare.com/sandbox/files/og.png?v=74a9c89ed01f6f30","dateModified":"2026-10-22","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Save a directory from a Linux sandbox to your R2 bucket, and restore it into the same sandbox after its instance or image changes. title: Back up a directory to R2 image: https://developers.cloudflare.com/sandbox/files/back-up-a-directory-to-r2/og.png?v=aab44210f0b32ab9

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/sandbox/llms.txt
Use this file to discover all available pages before exploring further.