Skip to content

Networking

katamaran runs a patched gvproxy userspace network stack (libgvproxy.dylib) inside the katamaran-vm process. Frames move between the guest’s virtio-net device and gVisor’s TCP stack by direct function calls without an intermediate socket.

Standard Docker -p flags bind ports on 127.0.0.1 on your Mac:

Terminal window
docker run -d --rm -p 8080:80 nginx:alpine
curl http://127.0.0.1:8080/

The guest watches wildcard TCP listeners in the root network namespace (such as docker-proxy) via netlink sock_diag and asks gvproxy to expose those ports on macOS.

When auto_forward is enabled (the default), katamaran also forwards unpublished TCP ports that containers listen on inside their own network namespaces directly to 127.0.0.1:<port> on your Mac over virtio-vsock.

If you later publish the same port with -p, the explicit published port takes priority over the automatic forward.

Inspect active forwarded ports with kat status. To turn off automatic port forwarding:

Terminal window
kat config set auto_forward=off
kat restart

Containers reach services listening on 127.0.0.1 on your Mac through host.docker.internal (or host.internal). Both resolve to 192.168.127.254, which gvproxy maps to 127.0.0.1 on macOS:

Terminal window
docker run --rm alpine:3.24 wget -qO- http://host.docker.internal:3000/

dockerd is started with --host-gateway-ip=192.168.127.254, so --add-host myhost:host-gateway also routes to your Mac.

The guest’s /etc/resolv.conf points to the gvproxy gateway (192.168.127.1). gvproxy resolves names through the macOS system resolver (dns_sd), caches upstream answers, and coalesces concurrent identical lookups.

Because resolution goes through macOS, VPN split-DNS rules, /etc/hosts entries on macOS, and local .local or corporate domains work inside containers without manual DNS setup.

Traffic between containers on the same Docker bridge stays inside the Linux guest kernel. kat-init disables net.bridge.bridge-nf-call-iptables, net.bridge.bridge-nf-call-ip6tables, and net.bridge.bridge-nf-call-arptables at boot so Layer 2 bridged frames skip unnecessary IP netfilter hooks while Layer 3 NAT, published ports, and inter-bridge isolation remain active.

The guest network interface (eth0) and Docker bridges default to an MTU of 65520 bytes so bulk traffic between containers and macOS moves in large frames.