boxlite-ai / boxlite-ai/boxlite

Feature Request: Enable Docker Bridge Networking in libkrunfw Kernel

Open
#276 4 comments 3 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2.3k
Forks
179
Avg merge
23h 25m
Merged PRs (30d)
121

Description

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.

Contributor guide

Open the contributing guide

Research direction

Start by locating the libkrunfw kernel configuration and checking how the shipped 6.12.62 kernel is built. Verify the listed bridge, veth, namespace, netfilter, and NAT settings against the observed `unshare --net` and `docker network create` failures. Done means Docker Compose custom bridge networks work inside the boxlite VM without requiring host networking.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, linux
Domain
devops, networking, operating-systems
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.