Skip to content

Enable FUSE in workerd's local-dev Docker container client #6596

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: main
Choose a base branch
from
+21 −3
Open

Enable FUSE in workerd's local-dev Docker container client #6596

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
18 changes: 18 additions & 0 deletions src/workerd/server/container-client.c++
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1698,6 +1698,24 @@ kj::Promise<void> ContainerClient::createContainer(kj::StringPtr effectiveImage,
}
}

// Docker doesn't grant FUSE access by default — enable the minimum permissions for it.
{
auto capAdd = hostConfig.initCapAdd(1);
capAdd.set(0, "SYS_ADMIN");
Copy link
Copy Markdown
Contributor

@ask-bonk ask-bonk Bot Apr 17, 2026

Choose a reason for hiding this comment

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

Since the sidecar container (line 1976) already uses initCapAdd(1) for NET_ADMIN, this follows the existing pattern well. However, if FUSE support is eventually gated behind an opt-in, this block should be conditional. Even if it stays unconditional, consider adding a brief rationale comment explaining why SYS_ADMIN specifically (i.e., FUSE needs the mount() syscall) so future readers don't mistake it for an oversight.

}
{
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");
Copy link
Copy Markdown
Contributor

@ask-bonk ask-bonk Bot Apr 17, 2026

Choose a reason for hiding this comment

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

Nit: apparmor:unconfined is a no-op on macOS (Docker Desktop runs a Linux VM that may or may not have AppArmor). Not a problem — Docker just ignores unknown security options — but worth a brief comment noting it's Linux-specific, similar to how gatewayForPlatform (line 873) documents its macOS behavior.

Copy link
Copy Markdown
Author

@Ben2W Ben2W Apr 17, 2026

Choose a reason for hiding this comment

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

Addressed in 67aeb3b

}
Comment on lines +1701 to +1717
Copy link
Copy Markdown
Contributor

@ask-bonk ask-bonk Bot Apr 17, 2026

Choose a reason for hiding this comment

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

This unconditionally grants SYS_ADMIN, maps /dev/fuse, and disables AppArmor for every container created via local dev, regardless of whether the user's workload uses FUSE. CAP_SYS_ADMIN is one of the most powerful Linux capabilities — it covers mount(), setns(), unshare(), bpf(), and more. Granting it by default to all local containers when only a small subset need FUSE seems overly broad.

A few options to consider:

  1. Opt-in flag: Gate this behind a configuration option (the approach mentioned in 🐛 Bug Report — Runtime APIs: No privileged mode option for Containers local development #5609). Users who need FUSE explicitly enable it.
  2. Check for /dev/fuse on the host: Only add the device mapping and capabilities if /dev/fuse actually exists on the host. This is a lighter heuristic.
  3. At minimum, add a comment explaining the security trade-off so future readers understand why every local container gets SYS_ADMIN.

I'd defer to the maintainers on which approach they prefer, but option 1 seems safest for a first pass — it avoids surprising users who don't need FUSE with elevated container privileges.


auto response = co_await dockerApiRequest(network, kj::str(dockerPath), kj::HttpMethod::POST,
kj::str("/containers/create?name=", containerName), codec.encode(jsonRoot));

Expand Down
6 changes: 3 additions & 3 deletions src/workerd/server/docker-api.capnp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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");
}
Comment on lines 34 to 38
Copy link
Copy Markdown
Author

@Ben2W Ben2W Apr 17, 2026

Choose a reason for hiding this comment

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

Docker's API uses PascalCase keys for these fields (PathOnHost / PathInContainer / CgroupPermissions). Without these $Json.name annotations, capnp's JSON codec emits the source field names in camelCase, which Docker silently ignores


struct DeviceRequest {
Expand Down
Loading