Skip to content

[Containers] Document privileged_containers for FUSE in local dev #30462

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Ben2W wants to merge 1 commit into
base: production
Choose a base branch
from
Open

[Containers] Document privileged_containers for FUSE in local dev #30462

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions src/content/changelog/containers/2026-06-08-fuse-local-dev.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/).
8 changes: 8 additions & 0 deletions src/content/docs/containers/examples/r2-fuse-mount.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@rzazadebilal7 rzazadebilal7 May 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Expand Down
6 changes: 6 additions & 0 deletions src/content/docs/containers/local-dev.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down