Feature Request: Enable Docker Bridge Networking in libkrunfw Kernel

[fetta]

I ran into a limitations when trying to run a docker compose setup with a bridge networking inside my boxlite VM. I have a workaround - changing the docker compose setup to network=host, but it's a workaround. Would be cool if bridge networks were supported inside the VM.

My claude ran the analysis on the repo where I have code provisioning the environment and looked up boxlite and boxrun repos (I hope) and came with the following report:

Feature Request: Enable Docker Bridge Networking in libkrunfw Kernel

Summary

The libkrunfw kernel shipped with boxlite lacks the kernel modules required for Docker bridge networking, making it impossible to run Docker Compose stacks that use custom networks.

Problem

Docker Compose stacks typically create bridge networks for inter-container communication. Inside a boxlite VM, Docker starts with bridge: "none" because the libkrunfw kernel (6.12.62) does not include the necessary networking subsystems.

Specifically, these kernel features are missing:

Kernel Config	Purpose
CONFIG_BRIDGE	Linux bridge device (Docker bridge networks)
CONFIG_VETH	Virtual ethernet pairs (connects containers to bridges)
CONFIG_NETFILTER	Packet filtering framework
CONFIG_NF_NAT	NAT support (Docker port mapping)
CONFIG_NET_NS	Network namespace support (container network isolation)
CONFIG_IPTABLE_NAT / CONFIG_NF_TABLES	iptables/nftables NAT rules

Additionally, /lib/modules does not exist in the VM, so these cannot be loaded after boot — they would need to be compiled into the kernel or shipped as modules.

Observed behavior

• unshare --net fails with "Operation not permitted"
• /proc/sys/net/bridge/ does not exist
• docker network create fails
• Docker Compose with custom networks fails entirely
• Only --network=host works for individual containers

Expected behavior

Docker Compose stacks with custom bridge networks should work inside boxlite VMs, as Docker is a primary use case for development sandboxes.

Environment

• boxlite/boxrun v0.2.0
• Kernel: Linux version 6.12.62 (root@libkrunfw)
• Host: macOS with Apple Silicon (via Hypervisor.framework)

Suggested Fix

Add the following to the libkrunfw kernel configuration:

CONFIG_BRIDGE=y
CONFIG_BRIDGE_NETFILTER=y
CONFIG_VETH=y
CONFIG_NET_NS=y
CONFIG_NETFILTER=y
CONFIG_NETFILTER_XTABLES=y
CONFIG_NF_CONNTRACK=y
CONFIG_NF_NAT=y
CONFIG_NF_TABLES=y
CONFIG_NFT_NAT=y
CONFIG_IPTABLE_NAT=y
CONFIG_IPTABLE_FILTER=y

These could be built-in (=y) rather than modules (=m) to avoid needing a /lib/modules directory.

Impact

This limitation prevents any multi-container Docker Compose workflow from running inside boxlite VMs, which is a common development pattern (e.g., app + database + message queue stacks). Currently the only workaround is network_mode: host on all services, which requires modifying compose files and changing service discovery from DNS-based to localhost port-based.

[DorianZheng]

Hi @fetta. Thanks for the discussion. I did a deeper check and wanted to clarify the failure mode.

This is not primarily a CONFIG_NET_NS issue. In the affected lineage (v0.2.x), Docker Compose appears to fail at the bridge network creation step because bridge/netfilter support is missing in the guest kernel (CONFIG_BRIDGE and CONFIG_NETFILTER disabled; on older aarch64 builds, CONFIG_VETH was also missing).

Could we support this via an optional kernel profile (for DinD/Compose use cases), while keeping the current minimal profile as default?

Proposed profile enables:
CONFIG_BRIDGE, CONFIG_BRIDGE_NETFILTER, CONFIG_NETFILTER, CONFIG_NETFILTER_XTABLES, CONFIG_NF_CONNTRACK, CONFIG_NF_NAT, CONFIG_NF_TABLES, CONFIG_NFT_NAT, CONFIG_IPTABLE_FILTER, CONFIG_IPTABLE_NAT (and CONFIG_VETH where needed).

That seems like the best tradeoff:

• Default remains lean/smaller attack surface (current gvproxy-first model)
• Users who need Docker bridge networking can opt in

If helpful, I can test a candidate build with a reproducible Compose stack and report exact pass/fail results.

[fetta]

Thanks for looking into that so quickly. I had this issue with any docker compose file with networks: ... : bridge and while I have a workaround, having this available would bring a lot of value.

Needing to enable this via cli arguments (I'm using boxrun) makes sense if this makes the vm heavier.

Can't share the docker compose I'm working with though, I might try to reproduce the setup in a few days as I'm swamped with commitments until Thursday EOD.

[DorianZheng]

Thanks for looking into that so quickly. I had this issue with any docker compose file with networks: ... : bridge and while I have a workaround, having this available would bring a lot of value.

Needing to enable this via cli arguments (I'm using boxrun) makes sense if this makes the vm heavier.

Can't share the docker compose I'm working with though, I might try to reproduce the setup in a few days as I'm swamped with commitments until Thursday EOD.

Will take a look ASAP

[shivansh31414]

Thanks for opening this issue and explaining the missing kernel configs. I’d like to help by reproducing the problem with a simple Docker Compose setup and confirming the failure. I can also test candidate builds if you provide one with the suggested configs enabled, and share logs/results. Additionally, I’d be happy to contribute documentation about the current limitation and workarounds (network_mode: host) so users understand the impact until bridge networking is supported.