From d2e2f95d47c458ef9b31423a1c1393593d6ffab0 Mon Sep 17 00:00:00 2001
From: Sam Estep <sam@samestep.com>
Date: Sun, 12 Jul 2026 15:42:24 -0400
Subject: [PATCH] Document cellular hotspot MTU fix for Lima VMs

When the Mac host is on a cellular hotspot, the vzNAT interface's
default 1500-byte MTU exceeds what the end-to-end path supports,
creating a path MTU black hole: DNS, ping, and TCP handshakes work,
but HTTPS connections hang after sending the TLS ClientHello. Add a
troubleshooting subsection to the Lima section explaining the
symptom, the diagnosis, and how to persist a lower MTU on lima0 via
a Netplan override.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/README.md b/README.md
index 0b50976..d548c6f 100644
--- a/README.md
+++ b/README.md
@@ -255,6 +255,46 @@ And run this repo's script to generate `~/.ssh/tailnet`:
 tailnet
 ```
 
+### Cellular hotspot MTU
+
+When the Mac is connected to the Internet through a cellular hotspot, the end-to-end path may not support the 1500-byte MTU that the `vzNAT` interface advertises, causing a [path MTU black hole](https://en.wikipedia.org/wiki/Path_MTU_Discovery#Problems): DNS, `ping`, and TCP handshakes all work, but HTTPS connections hang right after sending the TLS ClientHello, so tools like `apt` (against HTTPS repos) and Claude Code time out while small-packet traffic looks healthy.
+
+The `vzNAT` interface is normally named `lima0`, and it takes priority over Lima's user-mode `eth0` because of its lower route metric. Confirm that Internet traffic uses it:
+
+```sh
+ip route get 8.8.8.8
+```
+
+Then lower its MTU (use 1280 instead if 1400 still fails):
+
+```sh
+sudo ip link set dev lima0 mtu 1400
+```
+
+To make that persist across reboots, create a Netplan override, substituting the MAC address reported by `ip link show lima0`:
+
+```sh
+sudo tee /etc/netplan/99-lima-mtu.yaml >/dev/null <<'EOF'
+network:
+  version: 2
+  ethernets:
+    lima0:
+      match:
+        macaddress: "52:55:55:25:b0:2c"
+      mtu: 1400
+EOF
+sudo chmod 600 /etc/netplan/99-lima-mtu.yaml
+sudo netplan generate
+sudo netplan try
+```
+
+After rebooting, verify the setting and HTTPS connectivity:
+
+```sh
+ip link show lima0
+curl -fsS https://download.docker.com/ >/dev/null
+```
+
 ## [Tart](tart)
 
 This config can be used for macOS VMs created with [Tart](https://tart.run/), which comes with the host-side macOS config in this repo. First, download a macOS image: