Add ContainerOptions.allowPrivileged for FUSE in local-dev Docker containers

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. Without those three knobs the
mount("fuse", ...) syscall inside the container fails.

Add a new boolean to ContainerOptions in workerd.capnp, off by default:

  struct ContainerOptions {
    imageName       @0 :Text;
    allowPrivileged @1 :Bool = false;  # NEW
  }

When set on a DurableObjectNamespace's container config, ContainerClient
adds the minimum HostConfig fields needed for FUSE to the
POST /containers/create payload:

  - CapAdd: ["SYS_ADMIN"]                 (for the mount() syscall)
  - Devices: [/dev/fuse]                  (so the kernel has something to open)
  - SecurityOpt: ["apparmor:unconfined"]  (bypasses the default docker
                                           apparmor profile's mount block)

No Privileged=true. Mirrors what Cloudflare's production container
runtime effectively provides for FUSE workers, without granting all
Linux capabilities or full /dev passthrough.

server.c++ reads the flag from the per-DO ContainerOptions config and
threads it through to the ContainerClient constructor. Off by default
means existing configs are unaffected. Only the local Docker code path
is touched; production is unaffected.

Also adds missing $Json.name annotations to docker_api::DeviceMapping
fields in docker-api.capnp so they serialize as PathOnHost /
PathInContainer / CgroupPermissions to match the Docker API. This is
load-bearing for the Devices bind above — without it, the entry
serializes as camelCase and Docker silently ignores it. Before this PR
no call site populated Devices, so the missing annotations were latent.

Follows the existing pattern of createSidecarContainer() which already
sets CapAdd=[NET_ADMIN] for its own need at container-client.c++:1958.

The matching workers-sdk PR
(cloudflare/workers-sdk#13748) adds
`dev.enable_containers_privileged_mode` and
`--enable-containers-privileged-mode` so wrangler / vite-plugin users
can opt in.

End-to-end reproduction (libc mount("fuse", ...) syscall succeeding
inside the container with the flag set, and failing without it) at
https://github.com/Ben2W/workerd-fuse-local-repro

Signed-off-by: Ben Werner <bewerner23@gmail.com>

Author: Ben2W

src/workerd/server/container-client-test.c++

@@ -195,5 +195,58 @@ KJ_TEST("ContainerCreateRequest encodes HostConfig Dns") {
   KJ_EXPECT(decodedDns[1] == "8.8.8.8");
 }
 
+KJ_TEST("ContainerCreateRequest encodes privileged FUSE HostConfig") {
+  capnp::JsonCodec codec;
+  codec.handleByAnnotation<docker_api::Docker::ContainerCreateRequest>();
+
+  capnp::MallocMessageBuilder message;
+  auto root = message.initRoot<docker_api::Docker::ContainerCreateRequest>();
+  root.setImage("test-image");
+
+  auto hostConfig = root.initHostConfig();
+
+  auto capAdd = hostConfig.initCapAdd(1);
+  capAdd.set(0, "SYS_ADMIN");
+
+  auto devices = hostConfig.initDevices(1);
+  auto fuseDev = devices[0];
+  fuseDev.setPathOnHost("/dev/fuse");
+  fuseDev.setPathInContainer("/dev/fuse");
+  fuseDev.setCgroupPermissions("rwm");
+
+  auto securityOpt = hostConfig.initSecurityOpt(1);
+  securityOpt.set(0, "apparmor:unconfined");
+
+  auto json = codec.encode(root);
+  auto jsonText = json.asPtr();
+
+  KJ_EXPECT(jsonText.contains("\"CapAdd\""));
+  KJ_EXPECT(jsonText.contains("\"SYS_ADMIN\""));
+  KJ_EXPECT(jsonText.contains("\"Devices\""));
+  KJ_EXPECT(jsonText.contains("\"PathOnHost\":\"/dev/fuse\""));
+  KJ_EXPECT(jsonText.contains("\"PathInContainer\":\"/dev/fuse\""));
+  KJ_EXPECT(jsonText.contains("\"CgroupPermissions\":\"rwm\""));
+  KJ_EXPECT(jsonText.contains("\"SecurityOpt\""));
+  KJ_EXPECT(jsonText.contains("\"apparmor:unconfined\""));
+
+  auto decoded = decodeJsonResponse<docker_api::Docker::ContainerCreateRequest>(jsonText);
+  auto decodedRoot = decoded->getRoot<docker_api::Docker::ContainerCreateRequest>();
+  auto decodedHostConfig = decodedRoot.getHostConfig();
+  auto decodedCapAdd = decodedHostConfig.getCapAdd();
+  auto decodedDevices = decodedHostConfig.getDevices();
+  auto decodedSecurityOpt = decodedHostConfig.getSecurityOpt();
+
+  KJ_REQUIRE(decodedCapAdd.size() == 1);
+  KJ_EXPECT(decodedCapAdd[0] == "SYS_ADMIN");
+
+  KJ_REQUIRE(decodedDevices.size() == 1);
+  KJ_EXPECT(decodedDevices[0].getPathOnHost() == "/dev/fuse");
+  KJ_EXPECT(decodedDevices[0].getPathInContainer() == "/dev/fuse");
+  KJ_EXPECT(decodedDevices[0].getCgroupPermissions() == "rwm");
+
+  KJ_REQUIRE(decodedSecurityOpt.size() == 1);
+  KJ_EXPECT(decodedSecurityOpt[0] == "apparmor:unconfined");
+}
+
 }  // namespace
 }  // namespace workerd::server

src/workerd/server/container-client.c++

@@ -939,7 +939,8 @@ ContainerClient::ContainerClient(capnp::ByteStreamFactory& byteStreamFactory,
     kj::TaskSet& waitUntilTasks,
     kj::Promise<void> pendingCleanup,
     kj::Function<void(kj::Promise<void>)> cleanupCallback,
-    ChannelTokenHandler& channelTokenHandler)
+    ChannelTokenHandler& channelTokenHandler,
+    bool allowPrivileged)
     : byteStreamFactory(byteStreamFactory),
       timer(timer),
       network(network),
@@ -948,6 +949,7 @@ ContainerClient::ContainerClient(capnp::ByteStreamFactory& byteStreamFactory,
       sidecarContainerName(kj::encodeUriComponent(kj::str(containerName, "-proxy"))),
       imageName(kj::mv(imageName)),
       containerEgressInterceptorImage(kj::mv(containerEgressInterceptorImage)),
+      allowPrivileged(allowPrivileged),
       waitUntilTasks(waitUntilTasks),
       pendingCleanup(kj::mv(pendingCleanup).fork()),
       cleanupCallback(kj::mv(cleanupCallback)),
@@ -1722,6 +1724,27 @@ kj::Promise<void> ContainerClient::createContainer(kj::StringPtr effectiveImage,
     }
   }
 
+  // Docker doesn't grant FUSE access by default — when the user opts in via
+  // ContainerOptions.allowPrivileged, enable the minimum permissions for it.
+  if (allowPrivileged) {
+    {
+      auto capAdd = hostConfig.initCapAdd(1);
+      capAdd.set(0, "SYS_ADMIN");
+    }
+    {
+      auto devices = hostConfig.initDevices(1);
+      auto fuseDev = devices[0];
+      fuseDev.setPathOnHost("/dev/fuse");
+      fuseDev.setPathInContainer("/dev/fuse");
+      fuseDev.setCgroupPermissions("rwm");
+    }
+    {
+      // Linux-only: no-op on hosts without AppArmor (e.g. macOS).
+      auto securityOpt = hostConfig.initSecurityOpt(1);
+      securityOpt.set(0, "apparmor:unconfined");
+    }
+  }
+
   auto response = co_await dockerApiRequest(network, kj::str(dockerPath), kj::HttpMethod::POST,
       kj::str("/containers/create?name=", containerName), codec.encode(jsonRoot));
 

src/workerd/server/container-client.h

@@ -68,7 +68,8 @@ class ContainerClient final: public rpc::Container::Server, public kj::Refcounte
       kj::TaskSet& waitUntilTasks,
       kj::Promise<void> pendingCleanup,
       kj::Function<void(kj::Promise<void>)> cleanupCallback,
-      ChannelTokenHandler& channelTokenHandler);
+      ChannelTokenHandler& channelTokenHandler,
+      bool allowPrivileged);
 
   ~ContainerClient() noexcept(false);
 
@@ -104,6 +105,11 @@ class ContainerClient final: public rpc::Container::Server, public kj::Refcounte
   // Container egress interceptor image name (sidecar for egress proxy)
   kj::String containerEgressInterceptorImage;
 
+  // When true, createContainer() injects the HostConfig fields needed for FUSE
+  // (CAP_SYS_ADMIN, /dev/fuse, AppArmor unconfined). See ContainerOptions in
+  // workerd.capnp.
+  bool allowPrivileged;
+
   kj::TaskSet& waitUntilTasks;
 
   // Forked promise representing pending cleanup from a previous ContainerClient for the same

src/workerd/server/docker-api.capnp

@@ -32,9 +32,9 @@ struct Docker {
   }
 
   struct DeviceMapping {
-    pathOnHost @0 :Text;
-    pathInContainer @1 :Text;
-    cgroupPermissions @2 :Text;
+    pathOnHost @0 :Text $Json.name("PathOnHost");
+    pathInContainer @1 :Text $Json.name("PathInContainer");
+    cgroupPermissions @2 :Text $Json.name("CgroupPermissions");
   }
 
   struct DeviceRequest {

src/workerd/server/server.c++

@@ -2936,6 +2936,7 @@ class Server::WorkerService final: public Service,
         KJ_IF_SOME(config, containerOptions) {
           KJ_ASSERT(config.hasImageName(), "Image name is required");
           auto imageName = config.getImageName();
+          bool allowPrivileged = config.getAllowPrivileged();
           kj::String containerId;
           KJ_SWITCH_ONEOF(id) {
             KJ_CASE_ONEOF(globalId, kj::Own<ActorIdFactory::ActorId>) {
@@ -2947,7 +2948,8 @@ class Server::WorkerService final: public Service,
           }
 
           container = ns.getContainerClient(
-              kj::str("workerd-", KJ_ASSERT_NONNULL(uniqueKey), "-", containerId), imageName);
+              kj::str("workerd-", KJ_ASSERT_NONNULL(uniqueKey), "-", containerId), imageName,
+              allowPrivileged);
         }
 
         auto actor = actorClass->newActor(getTracker(), Worker::Actor::cloneId(id),
@@ -2992,7 +2994,7 @@ class Server::WorkerService final: public Service,
     }
 
     kj::Own<ContainerClient> getContainerClient(
-        kj::StringPtr containerId, kj::StringPtr imageName) {
+        kj::StringPtr containerId, kj::StringPtr imageName, bool allowPrivileged) {
       KJ_IF_SOME(existingClient, containerClients.find(containerId)) {
         return existingClient->addRef();
       }
@@ -3050,7 +3052,8 @@ class Server::WorkerService final: public Service,
           kj::str(dockerPathRef), kj::str(containerId), kj::str(imageName),
           kj::str(KJ_ASSERT_NONNULL(containerEgressInterceptorImage,
               "containerEgressInterceptorImage must be configured for containers.")),
-          waitUntilTasks, kj::mv(previousCleanup), kj::mv(cleanupCallback), channelTokenHandler);
+          waitUntilTasks, kj::mv(previousCleanup), kj::mv(cleanupCallback), channelTokenHandler,
+          allowPrivileged);
 
       // Store raw pointer in map (does not own)
       containerClients.insert(kj::str(containerId), client.get());

src/workerd/server/workerd.capnp

@@ -673,6 +673,13 @@ struct Worker {
       imageName @0 :Text;
       # Image name to be used to create the container using supported provider.
       # By default, we pull the "latest" tag of this image.
+
+      allowPrivileged @1 :Bool = false;
+      # When true, workerd creates the container with the elevated permissions
+      # needed for FUSE in local dev: CAP_SYS_ADMIN, /dev/fuse passthrough, and
+      # AppArmor unconfined. Off by default — only set this from a dev-only
+      # config path. Has no effect on production Cloudflare Containers, which
+      # use a different runtime path.
     }
   }