Investigated the Podman compute driver's container creation path on macOS with podman machine (Apple HV / gvproxy).
Root cause found in crates/openshell-driver-podman/src/container.rs:
The container spec unconditionally injects hostadd entries using Podman's host-gateway magic word:
hostadd: vec![
"host.containers.internal:host-gateway".into(),
"host.openshell.internal:host-gateway".into(),
],
On macOS, podman machine runs the Podman API inside a Linux VM. The host-gateway keyword fails because the VM cannot resolve the macOS host's IP — Podman returns:
Error: preparing container for attach: unable to replace "host-gateway"
of host entry "host.containers.internal:host-gateway":
host containers internal IP address is empty
This prevents any sandbox container from being created via the Podman driver on macOS.
Additional finding: check_subuid_range() in driver.rs reads /etc/subuid which doesn't exist on macOS, generating a confusing warning at startup. The check is meaningless on macOS since podman machine runs as root inside the Linux VM.
Verified: DNS resolution via aardvark-dns works — host.containers.internal resolves to 192.168.127.254 (gvproxy's standard GatewayVirtualIp) on the bridge network. The macOS host is reachable at that IP from inside containers.
Related: #1519 reports the same networking problem through the Docker driver path (Podman with libkrun detected as Docker). This issue covers the native Podman driver path.
Actual behavior: openshell sandbox create fails immediately on macOS with the Podman driver. The Podman API rejects the container spec because host-gateway cannot resolve inside podman machine.
Expected behavior: The Podman driver should detect macOS and inject the macOS host's IP explicitly instead of relying on host-gateway.
Add a host_gateway_ip config field to PodmanComputeConfig (mirroring the Docker driver's existing host_gateway_ip pattern). When set, the container spec uses the explicit IP instead of host-gateway:
hostadd: match &config.host_gateway_ip {
Some(ip) => vec![
format!("host.containers.internal:{ip}"),
format!("host.openshell.internal:{ip}"),
],
None => vec![
"host.containers.internal:host-gateway".into(),
"host.openshell.internal:host-gateway".into(),
],
},
On macOS, host_gateway_ip defaults to 192.168.127.254 — gvproxy's standard GatewayVirtualIp constant from containers/gvisor-tap-vsock. Overridable via OPENSHELL_PODMAN_HOST_GATEWAY_IP for non-standard network configurations. On Linux, the field is None and existing host-gateway behavior is unchanged.
Also gates check_subuid_range() behind !cfg!(target_os = "macos") to suppress the irrelevant warning.
Tested end-to-end on macOS (Apple Silicon) with podman machine:
- Gateway starts, connects to Podman, auto-detects gRPC endpoint
- Sandbox container created and started — no
host-gateway error
/etc/hosts inside container shows 192.168.127.254 for both host aliases
- Supervisor authenticates via gateway-minted JWT and connects back successfully
- Sandbox reaches healthy state
- macOS with
podman machine running (Apple HV or QEMU)
- Build and start the gateway with
OPENSHELL_DRIVERS=podman
openshell sandbox create --name test
- Container creation fails with
host containers internal IP address is empty
- OS: macOS (Darwin 25.5.0, arm64)
- Podman Client: 5.8.1 (darwin/arm64)
- Podman Server: 5.5.2 (linux/arm64, inside podman machine)
- podman machine: Apple HV, Fedora CoreOS 41
- OpenShell: dev branch
Investigated the Podman compute driver's container creation path on macOS with podman machine (Apple HV / gvproxy).
Root cause found in
crates/openshell-driver-podman/src/container.rs:The container spec unconditionally injects
hostaddentries using Podman'shost-gatewaymagic word:On macOS,
podman machineruns the Podman API inside a Linux VM. Thehost-gatewaykeyword fails because the VM cannot resolve the macOS host's IP — Podman returns:This prevents any sandbox container from being created via the Podman driver on macOS.
Additional finding:
check_subuid_range()indriver.rsreads/etc/subuidwhich doesn't exist on macOS, generating a confusing warning at startup. The check is meaningless on macOS since podman machine runs as root inside the Linux VM.Verified: DNS resolution via aardvark-dns works —
host.containers.internalresolves to192.168.127.254(gvproxy's standardGatewayVirtualIp) on the bridge network. The macOS host is reachable at that IP from inside containers.Related: #1519 reports the same networking problem through the Docker driver path (Podman with libkrun detected as Docker). This issue covers the native Podman driver path.
Actual behavior:
openshell sandbox createfails immediately on macOS with the Podman driver. The Podman API rejects the container spec becausehost-gatewaycannot resolve insidepodman machine.Expected behavior: The Podman driver should detect macOS and inject the macOS host's IP explicitly instead of relying on
host-gateway.Add a
host_gateway_ipconfig field toPodmanComputeConfig(mirroring the Docker driver's existinghost_gateway_ippattern). When set, the container spec uses the explicit IP instead ofhost-gateway:On macOS,
host_gateway_ipdefaults to192.168.127.254— gvproxy's standardGatewayVirtualIpconstant fromcontainers/gvisor-tap-vsock. Overridable viaOPENSHELL_PODMAN_HOST_GATEWAY_IPfor non-standard network configurations. On Linux, the field isNoneand existinghost-gatewaybehavior is unchanged.Also gates
check_subuid_range()behind!cfg!(target_os = "macos")to suppress the irrelevant warning.Tested end-to-end on macOS (Apple Silicon) with podman machine:
host-gatewayerror/etc/hostsinside container shows192.168.127.254for both host aliasespodman machinerunning (Apple HV or QEMU)OPENSHELL_DRIVERS=podmanopenshell sandbox create --name testhost containers internal IP address is empty