Update docs for Sandbox local mount support (#28890)

* Update docs for local mount support

* Update confusing env example

---------

Co-authored-by: scuffi <aferguson@cloudflare.com>

Author: scuffi

src/content/docs/sandbox/api/storage.mdx

@@ -110,7 +110,8 @@ Mounted buckets are automatically unmounted when the container is destroyed.
 
 ```ts
 interface MountBucketOptions {
-	endpoint: string;
+	endpoint?: string;
+	localBucket?: boolean;
 	provider?: BucketProvider;
 	credentials?: BucketCredentials;
 	readOnly?: boolean;
@@ -121,11 +122,17 @@ interface MountBucketOptions {
 
 **Fields**:
 
-- `endpoint` (required) - S3-compatible endpoint URL
+- `endpoint` (required when `localBucket` is `false` or unset) - S3-compatible endpoint URL
   - R2: `'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com'`
   - S3: `'https://s3.amazonaws.com'`
   - GCS: `'https://storage.googleapis.com'`
 
+- `localBucket` (optional) - Mount an R2 bucket using the Worker's R2 binding during local development with `wrangler dev`
+  - When `true`, the SDK syncs the R2 binding directly instead of using an S3 endpoint
+  - `endpoint` and `credentials` are not required when this is `true`
+	- `provider` and `s3fsOptions` are not used when this is `true`
+  - Default: `false`
+
 - `provider` (optional) - Storage provider hint
   - Enables provider-specific optimizations
   - Values: `'r2'`, `'s3'`, `'gcs'`

src/content/docs/sandbox/configuration/environment-variables.mdx

@@ -296,10 +296,6 @@ wrangler secret put AWS_SECRET_ACCESS_KEY
 # Paste your R2 Secret Access Key
 ```
 
-:::caution[Production only]
-Bucket mounting requires production deployment. It does not work with `wrangler dev` due to FUSE support limitations. See [Mount buckets guide](/sandbox/guides/mount-buckets/) for details.
-:::
-
 **Mount buckets with automatic credential detection:**
 
 ```typescript

src/content/docs/sandbox/guides/mount-buckets.mdx

@@ -6,18 +6,14 @@ sidebar:
 description: Mount S3-compatible object storage as local filesystems for persistent data storage.
 ---
 
-import { TypeScriptExample } from "~/components";
+import { TypeScriptExample, WranglerConfig } from "~/components";
 
 Mount S3-compatible object storage buckets as local filesystem paths. Access object storage using standard file operations.
 
 :::note[S3-compatible providers]
 The SDK works with any S3-compatible object storage provider. Examples include Cloudflare R2, Amazon S3, Google Cloud Storage, Backblaze B2, MinIO, and [many others](https://github.com/s3fs-fuse/s3fs-fuse/wiki/Non-Amazon-S3). The SDK automatically detects and optimizes for R2, S3, and GCS.
 :::
 
-:::caution[Production only]
-Bucket mounting does not work with `wrangler dev` because it requires FUSE support that wrangler does not currently provide. Deploy your Worker with `wrangler deploy` to use this feature. All other Sandbox SDK features work in local development.
-:::
-
 ## When to mount buckets
 
 Mount S3-compatible buckets when you need:
@@ -150,6 +146,86 @@ await sandbox.writeFile('/data/new-file.txt', 'data');  // Error: Read-only file
 ```
 </TypeScriptExample>
 
+## Local development
+
+You can mount R2 buckets during local development with `wrangler dev` by passing the `localBucket` option. This uses the R2 binding from your Worker environment directly, so no S3-compatible endpoint or credentials are required.
+
+### Configure R2 bindings
+
+Add an R2 bucket binding to your Wrangler configuration:
+
+<WranglerConfig>
+```jsonc
+{
+	"r2_buckets": [
+		{
+			"binding": "MY_BUCKET",
+			"bucket_name": "my-test-bucket"
+		}
+	]
+}
+```
+</WranglerConfig>
+
+### Mount with `localBucket`
+
+Pass `localBucket: true` in the options to mount the bucket locally:
+
+<TypeScriptExample>
+```typescript
+await sandbox.mountBucket('MY_BUCKET', '/data', {
+	localBucket: true
+});
+
+// Access files using standard operations
+await sandbox.exec('ls', { args: ['/data'] });
+await sandbox.writeFile('/data/results.json', JSON.stringify(results));
+```
+</TypeScriptExample>
+
+:::note
+You can use an environment variable to toggle `localBucket` between local development and production. Set an environment variable such as `LOCAL_DEV` in your Wrangler configuration using `vars` for local development, then reference it in your code:
+
+```typescript
+await sandbox.mountBucket('MY_BUCKET', '/data', {
+	localBucket: Boolean(env.LOCAL_DEV),
+	endpoint: 'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com'
+});
+```
+
+When `localBucket` is `true`, the `endpoint` is ignored and the SDK uses the R2 binding directly. For more information on setting environment variables, refer to [Environment variables in Wrangler configuration](/workers/configuration/environment-variables/).
+:::
+
+The `readOnly` and `prefix` options work the same way in local mode:
+
+<TypeScriptExample>
+```typescript
+// Read-only local mount
+await sandbox.mountBucket('MY_BUCKET', '/data', {
+	localBucket: true,
+	readOnly: true
+});
+
+// Mount a subdirectory
+await sandbox.mountBucket('MY_BUCKET', '/images', {
+	localBucket: true,
+	prefix: '/uploads/images/'
+});
+```
+</TypeScriptExample>
+
+### Local development considerations
+
+During local development, files are synchronized between R2 and the container using a periodic sync process rather than a direct filesystem mount. Keep the following in mind:
+
+- **Synchronization window** - A brief delay exists between when a file is written and when it appears on the other side. For example, if you upload a file to R2 and then immediately read it from the mounted path in the container, the file may not yet be available. Allow a short window for synchronization to complete before reading recently written data.
+- **High-frequency writes** - Rapid successive writes to the same file path may take slightly longer to fully propagate. For best results, avoid writing to the same file from both R2 and the container at the same time.
+- **Bidirectional sync** - Changes made in the container are synced to R2, and changes made in R2 are synced to the container. Both directions follow the same periodic sync model.
+
+:::note
+These considerations apply to local development with `wrangler dev` only. In production, bucket mounts use a direct filesystem mount with no synchronization delay.
+:::
+
 ## Unmount buckets
 
 <TypeScriptExample>

src/content/docs/sandbox/tutorials/persistent-storage.mdx

@@ -176,13 +176,7 @@ Try this flow:
 Replace `YOUR_ACCOUNT_ID` in the endpoint URL with your Cloudflare account ID. Find it in the [dashboard](https://dash.cloudflare.com/) under **R2** > **Overview**.
 :::
 
-## 4. Local development limitation
-
-:::caution[Requires production deployment]
-Bucket mounting does not work with `wrangler dev` because it requires FUSE support that wrangler does not currently provide. You must deploy to production to test this feature. All other Sandbox SDK features work locally - only `mountBucket()` and `unmountBucket()` require production deployment.
-:::
-
-## 5. Deploy to production
+## 4. Deploy to production
 
 **Generate R2 API tokens:**
 1. Go to **R2** > **Overview** in the [Cloudflare dashboard](https://dash.cloudflare.com/)
@@ -210,7 +204,7 @@ npx wrangler deploy
 
 After deployment, wrangler outputs your Worker URL (e.g., `https://data-pipeline.yourname.workers.dev`).
 
-## 6. Test the persistence flow
+## 5. Test the persistence flow
 
 Now test against your deployed Worker. Replace `YOUR_WORKER_URL` with your actual Worker URL: