[wrangler/miniflare] Add enable_containers_privileged_mode for FUSE in local dev

Containers using FUSE work in production but break in `wrangler dev`
because workerd doesn't grant CAP_SYS_ADMIN, mount /dev/fuse, or relax
AppArmor on the container it creates.

Adds an opt-in dev config flag — `dev.enable_containers_privileged_mode`
in wrangler.json, `--enable-containers-privileged-mode` on the CLI —
that, when set, has miniflare ask workerd to launch local containers
with those three permissions. Off by default; only takes effect when
the user explicitly opts in.

Pairs with the workerd change in
cloudflare/workerd#6596, which adds the
matching `allowPrivileged` field to ContainerOptions and gates the
FUSE injection on it.

Author: Ben2W

.changeset/fuse-allow-privileged-mode.md

@@ -0,0 +1,10 @@
+---
+"wrangler": minor
+"miniflare": minor
+---
+
+Add `dev.enable_containers_privileged_mode` (and `--enable-containers-privileged-mode`) opt-in for FUSE in local dev
+
+Containers using FUSE work in production but break in `wrangler dev` because workerd doesn't grant `CAP_SYS_ADMIN`, mount `/dev/fuse`, or relax AppArmor on the container it creates. This adds a top-level dev config flag — `dev.enable_containers_privileged_mode` in `wrangler.json`, `--enable-containers-privileged-mode` on the CLI — that, when set, has miniflare ask workerd to launch local containers with those three permissions. Off by default; only takes effect when the user opts in.
+
+Pairs with the workerd change in https://github.com/cloudflare/workerd/pull/6596, which adds the matching `allowPrivileged` option to `ContainerOptions` and gates the FUSE injection on it.

packages/miniflare/src/plugins/do/index.ts

@@ -17,6 +17,9 @@ import type {
 // Options for a container attached to the DO
 export const DOContainerOptionsSchema = z.object({
 	imageName: z.string(),
+	// When true, workerd creates the container with the elevated privileges
+	// needed for FUSE (CAP_SYS_ADMIN, /dev/fuse, AppArmor unconfined).
+	allowPrivileged: z.boolean().optional(),
 });
 export type DOContainerOptions = z.infer<typeof DOContainerOptionsSchema>;
 

packages/miniflare/src/runtime/config/workerd.ts

@@ -195,8 +195,14 @@ export type Worker_DurableObjectNamespace = {
 	className?: string;
 	preventEviction?: boolean;
 	enableSql?: boolean;
+	container?: Worker_ContainerOptions;
 } & ({ uniqueKey?: string } | { ephemeralLocal?: Void });
 
+export type Worker_ContainerOptions = {
+	imageName?: string;
+	allowPrivileged?: boolean;
+};
+
 export type ExternalServer = { address?: string } & (
 	| { http: HttpOptions }
 	| { https: ExternalServer_Https }

packages/workers-utils/src/config/config.ts

@@ -254,6 +254,15 @@ export interface DevConfig {
 	 */
 	enable_containers: boolean;
 
+	/**
+	 * When developing, whether to launch containers with the elevated privileges
+	 * required for FUSE mounts (CAP_SYS_ADMIN, /dev/fuse, AppArmor unconfined).
+	 * Off by default — only enable when your container needs FUSE locally.
+	 *
+	 * @default false
+	 */
+	enable_containers_privileged_mode: boolean;
+
 	/**
 	 * Either the Docker unix socket i.e. `unix:///var/run/docker.sock` or a full configuration.
 	 * Note that windows is only supported via WSL at the moment
@@ -312,6 +321,7 @@ export const defaultWranglerConfig: Config = {
 		host: undefined,
 		// Note this one is also workers only
 		enable_containers: true,
+		enable_containers_privileged_mode: false,
 		container_engine: undefined,
 		generate_types: false,
 	},

packages/workers-utils/src/config/validation.ts

@@ -227,6 +227,7 @@ export type NormalizeAndValidateConfigArgs = {
 	upstreamProtocol?: string;
 	script?: string;
 	enableContainers?: boolean;
+	enableContainersPrivilegedMode?: boolean;
 	generateTypes?: boolean;
 };
 
@@ -681,6 +682,7 @@ function normalizeAndValidateDev(
 		upstreamProtocol: upstreamProtocolArg,
 		remote: remoteArg,
 		enableContainers: enableContainersArg,
+		enableContainersPrivilegedMode: enableContainersPrivilegedModeArg,
 		generateTypes: generateTypesArg,
 	} = args;
 	assert(
@@ -698,6 +700,10 @@ function normalizeAndValidateDev(
 		enableContainersArg === undefined ||
 			typeof enableContainersArg === "boolean"
 	);
+	assert(
+		enableContainersPrivilegedModeArg === undefined ||
+			typeof enableContainersPrivilegedModeArg === "boolean"
+	);
 	assert(
 		generateTypesArg === undefined || typeof generateTypesArg === "boolean"
 	);
@@ -720,6 +726,7 @@ function normalizeAndValidateDev(
 			: local_protocol,
 		host,
 		enable_containers = enableContainersArg ?? true,
+		enable_containers_privileged_mode = enableContainersPrivilegedModeArg ?? false,
 		container_engine,
 		generate_types = generateTypesArg ?? false,
 		...rest
@@ -767,6 +774,14 @@ function normalizeAndValidateDev(
 		"boolean"
 	);
 
+	validateOptionalProperty(
+		diagnostics,
+		"dev",
+		"enable_containers_privileged_mode",
+		enable_containers_privileged_mode,
+		"boolean"
+	);
+
 	validateOptionalProperty(
 		diagnostics,
 		"dev",
@@ -792,6 +807,7 @@ function normalizeAndValidateDev(
 		upstream_protocol,
 		host,
 		enable_containers,
+		enable_containers_privileged_mode,
 		container_engine,
 		generate_types,
 	};

packages/wrangler/src/api/integrations/platform/index.ts

@@ -259,6 +259,8 @@ async function getMiniflareOptionsFromConfig(args: {
 			),
 			containerBuildId: undefined,
 			enableContainers: config.dev.enable_containers,
+			enableContainersPrivilegedMode:
+				config.dev.enable_containers_privileged_mode,
 		},
 		remoteProxyConnectionString
 	);
@@ -432,6 +434,8 @@ export function unstable_getMiniflareWorkerOptions(
 			containerDOClassNames,
 			containerBuildId: options?.containerBuildId,
 			enableContainers,
+			enableContainersPrivilegedMode:
+				config.dev.enable_containers_privileged_mode,
 		},
 		options?.remoteProxyConnectionString
 	);
@@ -490,6 +494,8 @@ export function unstable_getMiniflareWorkerOptions(
 										doClassName: binding.class_name,
 										containerDOClassNames,
 										containerBuildId: options?.containerBuildId,
+										allowPrivileged:
+											config.dev.enable_containers_privileged_mode,
 									})
 								: undefined,
 					} satisfies DurableObjectDefinition,

packages/wrangler/src/api/startDevWorker/ConfigController.ts

@@ -158,6 +158,9 @@ async function resolveDevConfig(
 		multiworkerPrimary: input.dev?.multiworkerPrimary,
 		enableContainers:
 			input.dev?.enableContainers ?? config.dev.enable_containers,
+		enableContainersPrivilegedMode:
+			input.dev?.enableContainersPrivilegedMode ??
+			config.dev.enable_containers_privileged_mode,
 		dockerPath: input.dev?.dockerPath ?? getDockerPath(),
 		containerEngine: useContainers
 			? (input.dev?.containerEngine ??

packages/wrangler/src/api/startDevWorker/LocalRuntimeController.ts

@@ -144,6 +144,8 @@ export async function convertToConfigBundle(
 		containerBuildId: event.config.dev?.containerBuildId,
 		containerEngine: event.config.dev.containerEngine,
 		enableContainers: event.config.dev.enableContainers ?? true,
+		enableContainersPrivilegedMode:
+			event.config.dev.enableContainersPrivilegedMode ?? false,
 		// Zone for CF-Worker header - extracted from routes/host configuration
 		zone: event.config.dev?.origin?.hostname,
 		sendMetrics: event.config.sendMetrics,

packages/wrangler/src/api/startDevWorker/types.ts

@@ -178,6 +178,12 @@ export interface StartDevWorkerInput {
 		/** Whether to build and connect to containers during local dev. Requires Docker daemon to be running. Defaults to true. */
 		enableContainers?: boolean;
 
+		/**
+		 * Whether to launch local containers with the elevated privileges needed for FUSE
+		 * (CAP_SYS_ADMIN, /dev/fuse, AppArmor unconfined). Defaults to false.
+		 */
+		enableContainersPrivilegedMode?: boolean;
+
 		/** Path to the dev registry directory */
 		registry?: string;
 

packages/wrangler/src/dev.ts

@@ -142,6 +142,12 @@ export const dev = createCommand({
 			describe: "Whether to build and enable containers during development",
 			hidden: true,
 		},
+		"enable-containers-privileged-mode": {
+			type: "boolean",
+			describe:
+				"Launch local containers with the elevated privileges required for FUSE (CAP_SYS_ADMIN, /dev/fuse, AppArmor unconfined)",
+			hidden: true,
+		},
 		site: {
 			describe: "Root folder of static assets for Workers Sites",
 			type: "string",