bug: gateway crash-loops on macOS — binds to VM-internal podman bridge IP (10.89.0.1) on host

[kaovilai]

Description

brew services restart openshell on macOS results in a crash loop. The gateway process starts, binds successfully to 127.0.0.1:17670, but then also attempts to bind to 10.89.0.1:17670 — the gateway IP of the openshell-docker podman network. On macOS with podman machine (libkrun), this address only exists inside the Linux VM and is not reachable from the host. The bind fails with EADDRNOTAVAIL (os error 49), the process exits, and launchd respawns it every ~10 seconds.

Actual behavior: Gateway crash-loops, brew services list shows error status with exit code 1.

Expected behavior: Gateway should not attempt to bind to podman bridge IPs on macOS, since they are VM-internal addresses unreachable from the host.

Reproduction Steps

1. Install openshell via Homebrew on macOS (Apple Silicon)
2. Have podman machine running (libkrun)
3. brew services restart openshell
4. brew services list shows openshell error 1

Logs

stderr (/opt/homebrew/var/log/openshell/openshell-gateway.err.log):

Error:   × transport error: failed to bind to 10.89.0.1:17670: Can't assign requested
  │ address (os error 49)

Repeats every ~10 seconds as launchd respawns.

stdout (/opt/homebrew/var/log/openshell/openshell-gateway.out.log):

INFO openshell_server::cli: Starting OpenShell server bind=127.0.0.1:17670
INFO openshell_server: Using compute driver driver=docker
INFO openshell_server: Server listening address=127.0.0.1:17670

The primary bind to 127.0.0.1:17670 succeeds, but a secondary bind to the podman bridge gateway IP fails.

system log shows the spawn/inactive cycle:

Successfully spawned openshell-gateway-homebrew-service[60695] because semaphore
service inactive: homebrew.mxcl.openshell

Analysis

The openshell-docker podman network has subnet 10.89.0.0/24 with gateway 10.89.0.1. The gateway binary discovers this network and tries to also listen on the bridge gateway IP. On Linux (native podman), this would work because the bridge interface exists on the host. On macOS with podman machine (libkrun/Apple HV), all podman networking is inside the VM — 10.89.0.1 is not a host-side address.

$ ifconfig | grep 10.89
(no output — address does not exist on host)

$ podman network inspect openshell-docker | jq '.[0].subnets'
[{"subnet": "10.89.0.0/24", "gateway": "10.89.0.1"}]

Environment

• OS: macOS (Darwin 25.4.0, Apple Silicon)
• OpenShell: 0.0.39 (Homebrew, built from source)
• Podman: 5.8.2 (libkrun VM type)
• Podman machine: running

Related Issues

• bug: Podman driver fails on macOS with stale Podman machine — host-gateway unresolvable #1307 — same class of issue: podman bridge IPs are VM-internal on macOS. That issue covers host-gateway resolution in container hostadd; this issue is about the gateway server itself binding to the bridge IP.

Proposed Fix

When running on macOS with podman machine, the gateway should skip binding to podman bridge network gateway IPs (they are unreachable from the host). The gateway could:

1. Detect macOS + podman machine and only bind to the configured OPENSHELL_BIND_ADDRESS
2. Probe whether the bridge IP is actually assigned to a local interface before attempting to bind
3. Treat the bridge bind failure as non-fatal (log a warning, continue with 127.0.0.1 listener only)

Note

Responses generated with Claude