[wrangler/miniflare] Add privileged_containers / --privileged-containers 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.privileged_containers` in
wrangler.json, `--privileged-containers` 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-privileged-containers.md

@@ -0,0 +1,8 @@
+---
+"wrangler": minor
+"miniflare": minor
+---
+
+Add `dev.privileged_containers` config and `--privileged-containers` CLI flag for FUSE in local dev
+
+When set, miniflare launches local containers with the elevated permissions FUSE requires (`CAP_SYS_ADMIN`, `/dev/fuse`, AppArmor unconfined). Off by default.

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
+	 */
+	privileged_containers: 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,
+		privileged_containers: false,
 		container_engine: undefined,
 		generate_types: false,
 	},

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

@@ -237,6 +237,7 @@ export type NormalizeAndValidateConfigArgs = {
 	upstreamProtocol?: string;
 	script?: string;
 	enableContainers?: boolean;
+	privilegedContainers?: boolean;
 	generateTypes?: boolean;
 };
 
@@ -692,6 +693,7 @@ function normalizeAndValidateDev(
 		upstreamProtocol: upstreamProtocolArg,
 		remote: remoteArg,
 		enableContainers: enableContainersArg,
+		privilegedContainers: privilegedContainersArg,
 		generateTypes: generateTypesArg,
 	} = args;
 	assert(
@@ -709,6 +711,10 @@ function normalizeAndValidateDev(
 		enableContainersArg === undefined ||
 			typeof enableContainersArg === "boolean"
 	);
+	assert(
+		privilegedContainersArg === undefined ||
+			typeof privilegedContainersArg === "boolean"
+	);
 	assert(
 		generateTypesArg === undefined || typeof generateTypesArg === "boolean"
 	);
@@ -731,6 +737,7 @@ function normalizeAndValidateDev(
 			: local_protocol,
 		host,
 		enable_containers = enableContainersArg ?? true,
+		privileged_containers = privilegedContainersArg ?? false,
 		container_engine,
 		generate_types = generateTypesArg ?? false,
 		...rest
@@ -778,6 +785,14 @@ function normalizeAndValidateDev(
 		"boolean"
 	);
 
+	validateOptionalProperty(
+		diagnostics,
+		"dev",
+		"privileged_containers",
+		privileged_containers,
+		"boolean"
+	);
+
 	validateOptionalProperty(
 		diagnostics,
 		"dev",
@@ -803,6 +818,7 @@ function normalizeAndValidateDev(
 		upstream_protocol,
 		host,
 		enable_containers,
+		privileged_containers,
 		container_engine,
 		generate_types,
 	};

packages/wrangler/src/__tests__/config-validation-pages.test.ts

@@ -194,6 +194,7 @@ describe("validatePagesConfig()", () => {
 						upstream_protocol: "https",
 						host: "test-host",
 						enable_containers: false,
+						privileged_containers: false,
 						container_engine: undefined,
 						generate_types: false,
 					},

packages/wrangler/src/__tests__/dev.test.ts

@@ -1679,6 +1679,44 @@ describe.sequential("wrangler dev", () => {
 		});
 	});
 
+	describe("privileged containers", () => {
+		it("should default to false", async ({ expect }) => {
+			writeWranglerConfig({
+				main: "index.js",
+			});
+			fs.writeFileSync("index.js", `export default {};`);
+			const config = await runWranglerUntilConfig("dev");
+			expect(config.dev.privilegedContainers).toBe(false);
+		});
+
+		it("should be true when `dev.privileged_containers` is set in the Wrangler config", async ({
+			expect,
+		}) => {
+			writeWranglerConfig({
+				main: "index.js",
+				dev: {
+					privileged_containers: true,
+				},
+			});
+			fs.writeFileSync("index.js", `export default {};`);
+			const config = await runWranglerUntilConfig("dev");
+			expect(config.dev.privilegedContainers).toBe(true);
+		});
+
+		it("should be true when `--privileged-containers` is passed on the CLI", async ({
+			expect,
+		}) => {
+			writeWranglerConfig({
+				main: "index.js",
+			});
+			fs.writeFileSync("index.js", `export default {};`);
+			const config = await runWranglerUntilConfig(
+				"dev --privileged-containers"
+			);
+			expect(config.dev.privilegedContainers).toBe(true);
+		});
+	});
+
 	describe("durable_objects", () => {
 		it("should warn if there are remote Durable Objects, or missing migrations for local Durable Objects", async ({
 			expect,

packages/wrangler/src/api/dev.ts

@@ -164,6 +164,7 @@ export async function unstable_dev(
 		d1Databases,
 		disableDevRegistry,
 		testScheduled: testScheduled ?? false,
+		privilegedContainers: false,
 		enablePagesAssetsServiceBinding,
 		forceLocal,
 		liveReload,

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

@@ -296,6 +296,8 @@ async function getMiniflareOptionsFromConfig(args: {
 			),
 			containerBuildId: undefined,
 			enableContainers: config.dev.enable_containers,
+			privilegedContainers:
+				config.dev.privileged_containers,
 		},
 		remoteProxyConnectionString
 	);
@@ -467,6 +469,8 @@ export function unstable_getMiniflareWorkerOptions(
 			containerDOClassNames,
 			containerBuildId: options?.containerBuildId,
 			enableContainers,
+			privilegedContainers:
+				config.dev.privileged_containers,
 		},
 		options?.remoteProxyConnectionString
 	);

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

@@ -166,6 +166,9 @@ async function resolveDevConfig(
 		inferOriginFromRoutes: input.dev?.inferOriginFromRoutes ?? true,
 		enableContainers:
 			input.dev?.enableContainers ?? config.dev.enable_containers,
+		privilegedContainers:
+			input.dev?.privilegedContainers ??
+			config.dev.privileged_containers,
 		dockerPath: input.dev?.dockerPath ?? getDockerPath(),
 		containerEngine: useContainers
 			? (input.dev?.containerEngine ??