Feature: allow wrangler dev to run local containers with /dev/fuse for R2/S3 FUSE mounts

[banchichen]

Describe the feature

Production Cloudflare Containers support mounting R2/S3 buckets via FUSE (s3fs, tigrisfs, mountpoint-s3, …), GA'd on 2025-11-21. But when the same container-enabled Worker runs locally under wrangler dev, the local container is launched without the /dev/fuse device and without CAP_SYS_ADMIN, so any FUSE mount inside the container fails. There is currently no wrangler option to enable it.

As a result, FUSE-dependent behavior can't be exercised locally and has to be branched/stubbed for dev, diverging from the deployed code path.

Motivation

• Prod/local parity. Local dev can't reproduce production FUSE mount/ restore semantics. Cloudflare's own Sandbox SDK documents this as two different code paths:

  "Production R2 binding mounts and local localBucket mounts both avoid explicit credentials, but they are different execution paths. Production uses credential-less egress interception and overlays the target path. Local development uses periodic synchronization with the R2 binding."
  "These considerations apply to local development with wrangler dev only." — https://developers.cloudflare.com/sandbox/guides/mount-buckets/

• It already works with plain Docker. Running the same image with docker run --cap-add SYS_ADMIN --device /dev/fuse … mounts fine. The only gap is that wrangler dev doesn't expose a way to pass these to the local container run.
• Containers using their own FUSE adapter (mountpoint-s3, gcsfuse, …) can't be tested at all under wrangler dev today.

Proposed solution

An opt-in, dev-only way to grant the local container the FUSE device + capability. Any of:

1. A dedicated boolean in the container config:

   // wrangler.jsonc
   "containers": [{
     "class_name": "MyContainer",
     "image": "./Dockerfile",
     "dev": { "enable_fuse": true } // adds --device /dev/fuse --cap-add SYS_ADMIN locally
   }]

2. A more general dev escape hatch:

   "dev": { "devices": ["/dev/fuse"], "cap_add": ["SYS_ADMIN"] }

3. A generic docker_run_args passthrough honored only by wrangler dev.

Scope: local dev only (no effect on wrangler deploy); off by default.

Alternatives considered

• Sandbox SDK localBucket / sync mode — works, but is a deliberately different execution path (periodic sync vs FUSE overlay), so it isn't parity and forces conditional code.
• Running the container manually via docker run — loses the Worker↔container integration, bindings, and dev registry wrangler dev gives.

Additional context / caveats

• Security: CAP_SYS_ADMIN is broad — keep it strictly opt-in and document the implications.
• Cross-platform: /dev/fuse availability differs inside the Docker VM on macOS/Windows (Docker Desktop, Colima). A Linux-first, best-effort implementation that errors clearly when the device is missing would already be valuable.

References

• FUSE in Containers (GA, 2025-11-21): https://developers.cloudflare.com/changelog/post/2025-11-21-fuse-support-in-containers/
• Mount R2 with FUSE example: https://developers.cloudflare.com/containers/examples/r2-fuse-mount/
• Sandbox SDK – mount buckets (local vs prod): https://developers.cloudflare.com/sandbox/guides/mount-buckets/
• Sandbox SDK – backup/restore (local unsquashfs vs prod FUSE overlay): https://developers.cloudflare.com/sandbox/guides/backup-restore/
• Related: Possible to enable FUSE? containers#112