diff --git a/src/content/changelog/containers/2026-06-08-fuse-local-dev.mdx b/src/content/changelog/containers/2026-06-08-fuse-local-dev.mdx new file mode 100644 index 00000000000..f6854a617d1 --- /dev/null +++ b/src/content/changelog/containers/2026-06-08-fuse-local-dev.mdx @@ -0,0 +1,13 @@ +--- +title: Enable FUSE in local development +description: Opt in to FUSE mounts in `wrangler dev` with the `privileged_containers` flag +products: + - containers +date: 2026-06-08 +--- + +Containers in `wrangler dev` can now opt into the kernel permissions FUSE mounts require. + +Set `dev.privileged_containers: true` in your [Wrangler configuration](/workers/wrangler/configuration/), or pass `--privileged-containers` to `wrangler dev`. The flag adds `CAP_SYS_ADMIN`, mounts `/dev/fuse`, and runs the container with AppArmor unconfined. + +Refer to [Mount R2 buckets with FUSE](/containers/examples/r2-fuse-mount/) and [Local development](/containers/local-dev/). diff --git a/src/content/docs/containers/examples/r2-fuse-mount.mdx b/src/content/docs/containers/examples/r2-fuse-mount.mdx index 8cf14a634a1..89a335efc30 100644 --- a/src/content/docs/containers/examples/r2-fuse-mount.mdx +++ b/src/content/docs/containers/examples/r2-fuse-mount.mdx @@ -30,6 +30,14 @@ Common use cases where this tradeoff is acceptable include reading shared assets ::: +:::caution[FUSE in local development] + +By default, `wrangler dev` launches containers without the elevated permissions FUSE requires (`CAP_SYS_ADMIN`, access to `/dev/fuse`, and an unconfined AppArmor profile), so a FUSE mount inside the container will fail. + +To opt in to FUSE locally, set `dev.privileged_containers: true` in your [Wrangler configuration](/workers/wrangler/configuration/), or pass `--privileged-containers` to `wrangler dev`. + +::: + ## Mounting buckets To mount an R2 bucket, install a FUSE adapter in your Dockerfile and configure it to run at container startup. diff --git a/src/content/docs/containers/local-dev.mdx b/src/content/docs/containers/local-dev.mdx index 511b30398d4..c53a1c6f44a 100644 --- a/src/content/docs/containers/local-dev.mdx +++ b/src/content/docs/containers/local-dev.mdx @@ -84,6 +84,12 @@ This retry logic should be handled for you if you are using the [containers pack If you see an opaque `internal error` when attempting to connect to your container, you may need to set the `DOCKER_HOST` environment variable to the socket path your container engine is listening on. Wrangler or Vite will attempt to automatically find the correct socket to use to communicate with your container engine, but if that does not work, you may have to set this environment variable to the appropriate socket path. +### FUSE filesystems + +By default, `wrangler dev` launches containers without the elevated permissions a FUSE mount requires (`CAP_SYS_ADMIN`, access to `/dev/fuse`, and an unconfined AppArmor profile). If your container uses a FUSE adapter — for example, [mounting an R2 bucket with FUSE](/containers/examples/r2-fuse-mount/) — the mount call will fail with `ENODEV` or a permission error. + +To opt in to FUSE locally, set `dev.privileged_containers: true` in your [Wrangler configuration](/workers/wrangler/configuration/), or pass `--privileged-containers` to `wrangler dev`. + ### SSL errors with the Cloudflare One Client or a VPN If you are running the Cloudflare One Client or a VPN that performs TLS inspection, HTTPS requests made during the Docker build process may fail with SSL or certificate errors. This happens because the VPN intercepts HTTPS traffic and re-signs it with its own certificate authority, which Docker does not trust by default.