fix(embed): fall back to iptables-legacy when nft backend is unsupported (#74)

* fix(embed): fall back to iptables-legacy when nft backend is unsupported

Rancher Desktop with VZ virtualization (no Rosetta) runs a minimal
ARM64 kernel that lacks CONFIG_NF_TABLES. The entrypoint now probes
iptables-nft first, falls back to iptables-legacy, and aborts if
neither works — network isolation is never silently skipped.

* docs(installation): add Docker runtime compatibility matrix

* fix(entrypoint): include actual error in iptables fallback message

* docs: clarify iptables fallback chain in runtime compatibility notes

* chore: bump Go to 1.26.2

* chore: revert Go version to 1.26.1 (nixpkgs-unstable lacks 1.26.2)

---------

Co-authored-by: OpenCode Agent <agent@opencode>

Author: thejoeejoee

docs/explanation/network-isolation.md

@@ -60,3 +60,11 @@ Any containers the agent starts through dind inherit the dind daemon's network c
 - The root filesystem is not read-only
 
 These gaps are intentional or accepted tradeoffs, not oversights. The goal of jailoc is to protect your internal network and keep the agent's state from bleeding into your host environment — not to prevent the agent from doing its job on the public internet.
+
+## Kernel requirements
+
+The iptables rules require the container runtime's Linux kernel to support **netfilter**. On startup, jailoc probes the default `iptables` (nft backend) first; if that fails, it falls back to `iptables-legacy`. If neither backend works, the container aborts because network isolation cannot be enforced.
+
+Most Docker runtimes ship kernels with full netfilter support, but some minimal hypervisor configurations do not. Rancher Desktop using VZ virtualization without Rosetta on macOS is a known case — its ARM64 kernel lacks netfilter entirely, so both backends fail with `Protocol not supported`.
+
+See [Installation — Docker runtime compatibility](../how-to/installation.md#docker-runtime-compatibility) for a full list of tested runtimes.

docs/how-to/installation.md

@@ -6,6 +6,31 @@ This guide covers installation methods and the prerequisites you need before run
 
 - **Docker Engine** must be running on your machine. jailoc communicates with the Docker daemon directly.
 - No `docker compose` CLI plugin is required. jailoc embeds the Compose SDK and manages containers without it.
+- The container runtime's Linux kernel must support **netfilter** (iptables). jailoc uses iptables rules inside the container to enforce [network isolation](../explanation/network-isolation.md). Runtimes whose kernel lacks netfilter support cannot run jailoc.
+
+### Docker runtime compatibility
+
+| Runtime | Platform | Status | Notes |
+|---------|----------|--------|-------|
+| Docker Engine | Linux | ✅ | Native performance, no VM overhead |
+| OrbStack | macOS | ✅ | Lightweight VM, fast file I/O — recommended on macOS |
+| Docker Desktop | macOS / Linux | ✅ | VirtioFS file sharing; higher memory footprint than OrbStack |
+| Colima | macOS | ✅ | Lima-based VM; performance depends on VM type (`vz` faster than `qemu`) |
+| Podman | macOS | ✅ | VM-based on macOS; comparable to Docker Desktop |
+| Rancher Desktop (VZ + Rosetta) | macOS | ✅ | Rosetta provides a more complete kernel with netfilter support |
+| Rancher Desktop (VZ, no Rosetta) | macOS | ❌ | VZ hypervisor without Rosetta runs a minimal ARM64 kernel that lacks netfilter — jailoc probes both `iptables-nft` and `iptables-legacy` but neither works, so startup is aborted |
+| Docker Engine (rootless) | Linux | ⚠️ | Untested — DinD sidecar requires `--privileged`, which rootless mode may not support |
+| WSL2 + Docker | Windows | ⚠️ | Untested — the Linux binary may work under WSL2 with Docker Engine installed inside the distribution |
+
+jailoc connects to whichever Docker daemon your current **docker context** points to. If your runtime uses a non-default socket path (common with Colima or Podman), make sure the active context is set correctly:
+
+```bash
+# list available contexts
+docker context ls
+
+# switch to a specific runtime
+docker context use colima
+```
 
 ---
 

internal/embed/assets/entrypoint.sh

@@ -1,17 +1,39 @@
 #!/bin/bash
 set -euo pipefail
 
+# --- Detect working iptables variant ---
+# Ubuntu 24.04 defaults to iptables-nft, which requires kernel nf_tables support.
+# Some environments (e.g. Rancher Desktop with VZ virtualization) lack this kernel
+# module, so we fall back to iptables-legacy. Abort if neither works — network
+# isolation is non-negotiable.
+if iptables -L -n >/dev/null 2>&1; then
+  IPT=iptables
+else
+  IPTABLES_ERROR="$(iptables -L -n 2>&1 || true)"
+  if command -v iptables-legacy >/dev/null 2>&1 && iptables-legacy -L -n >/dev/null 2>&1; then
+    IPT=iptables-legacy
+    if [ -n "$IPTABLES_ERROR" ]; then
+      echo "jailoc: iptables unusable ($IPTABLES_ERROR), using iptables-legacy" >&2
+    else
+      echo "jailoc: iptables unusable, using iptables-legacy" >&2
+    fi
+  else
+    echo "jailoc: FATAL: no working iptables found, cannot enforce network isolation" >&2
+    exit 1
+  fi
+fi
+
 # --- Allow infrastructure targets ---
-iptables -I OUTPUT -d dind -j ACCEPT
+$IPT -I OUTPUT -d dind -j ACCEPT
 
 HOST_IP=$(getent hosts host.docker.internal | awk '{print $1}' || true)
 if [ -n "$HOST_IP" ]; then
-  iptables -I OUTPUT -d "$HOST_IP" -j ACCEPT
+  $IPT -I OUTPUT -d "$HOST_IP" -j ACCEPT
 fi
 
 for GW in $(awk '$3 != "00000000" && $3 != "Gateway" {print $3}' /proc/net/route | sort -u); do
   GW_IP=$(printf '%d.%d.%d.%d' "0x${GW:6:2}" "0x${GW:4:2}" "0x${GW:2:2}" "0x${GW:0:2}")
-  iptables -I OUTPUT -d "$GW_IP" -j ACCEPT
+  $IPT -I OUTPUT -d "$GW_IP" -j ACCEPT
 done
 
 # --- Allow hostnames from config ---
@@ -25,7 +47,7 @@ if [ -f "$ALLOWED_HOSTS" ]; then
     RESOLVED=$(getent hosts "$line" | awk '{print $1}' || true)
     if [ -n "$RESOLVED" ]; then
       for IP in $RESOLVED; do
-        iptables -I OUTPUT -d "$IP" -j ACCEPT
+        $IPT -I OUTPUT -d "$IP" -j ACCEPT
         echo "jailoc: allow $line ($IP)"
       done
     else
@@ -41,8 +63,8 @@ if [ -f /etc/resolv.conf ]; then
       if [[ "$value" == *:* ]]; then
         continue
       fi
-      iptables -I OUTPUT -p udp -d "$value" --dport 53 -j ACCEPT
-      iptables -I OUTPUT -p tcp -d "$value" --dport 53 -j ACCEPT
+      $IPT -I OUTPUT -p udp -d "$value" --dport 53 -j ACCEPT
+      $IPT -I OUTPUT -p tcp -d "$value" --dport 53 -j ACCEPT
     fi
   done < /etc/resolv.conf
 fi
@@ -55,20 +77,20 @@ if [ -f "$ALLOWED_NETWORKS" ]; then
     line="${line// /}"
     [ -z "$line" ] && continue
 
-    iptables -I OUTPUT -d "$line" -j ACCEPT
+    $IPT -I OUTPUT -d "$line" -j ACCEPT
     echo "jailoc: allow network $line"
   done < "$ALLOWED_NETWORKS"
 fi
 
 # --- Allow replies to inbound connections on the published service port ---
-iptables -A OUTPUT -p tcp --sport 4096 -m conntrack --ctstate ESTABLISHED -j ACCEPT
+$IPT -A OUTPUT -p tcp --sport 4096 -m conntrack --ctstate ESTABLISHED -j ACCEPT
 
 # --- Block private/internal networks ---
-iptables -A OUTPUT -d 10.0.0.0/8 -j DROP
-iptables -A OUTPUT -d 172.16.0.0/12 -j DROP
-iptables -A OUTPUT -d 192.168.0.0/16 -j DROP
-iptables -A OUTPUT -d 169.254.0.0/16 -j DROP
-iptables -A OUTPUT -d 100.64.0.0/10 -j DROP
+$IPT -A OUTPUT -d 10.0.0.0/8 -j DROP
+$IPT -A OUTPUT -d 172.16.0.0/12 -j DROP
+$IPT -A OUTPUT -d 192.168.0.0/16 -j DROP
+$IPT -A OUTPUT -d 169.254.0.0/16 -j DROP
+$IPT -A OUTPUT -d 100.64.0.0/10 -j DROP
 
 chown -R 1000:1000 /home/agent/.local /home/agent/.cache 2>/dev/null || true
 chown 1000:1000 /home/agent/.claude 2>/dev/null || true