Podman compatibility: OpenShell gateway fails with 'host-gateway' on macOS

[rajmayank93]

NemoClaw's onboarding process fails when using Podman on macOS due to OpenShell's use of the host-gateway special value, which is not supported by Podman on macOS.

Environment

• OS: macOS 26.2 (Sequoia)
• Architecture: Apple M3 Pro (ARM64)
• Podman version: 5.4.1
• OpenShell version: 0.0.6
• NemoClaw version: From main branch

Steps to Reproduce

1. Install Podman on macOS (with Podman machine running)
2. Run ./install.sh or nemoclaw onboard
3. Onboarding fails at step [2/7] Starting OpenShell gateway

Error Output

Deploying local gateway nemoclaw...
  Checking Docker
  Downloading gateway
  Initializing environment
Error:   × failed to start gateway container
  ╰─▶ Docker responded with status code 500: failed to create new hosts file:
      unable to replace "host-gateway" of host entry
      "host.docker.internal:host-gateway": host containers internal IP address
      is empty

  Command failed (exit 1): openshell gateway start --name nemoclaw

Root Cause

OpenShell uses the Docker host-gateway special value when creating containers with --add-host=host.docker.internal:host-gateway. This feature is not supported by Podman on macOS because Podman doesn't set the host_containers_internal_ip configuration value.

Technical Details

1. OpenShell calls Docker API to create containers with host.docker.internal:host-gateway
2. Podman's macOS implementation doesn't support host-gateway keyword
3. Even setting host_containers_internal_ip = "10.88.0.1" in ~/.config/containers/containers.conf doesn't work on macOS
4. The gateway IP is 10.88.0.1 in Podman networks, but Podman can't resolve host-gateway to this IP

Verification

# This works (explicit IP):
podman run --rm --add-host=host.docker.internal:10.88.0.1 alpine cat /etc/hosts

# This fails (host-gateway keyword):
podman run --rm --add-host=host.docker.internal:host-gateway alpine cat /etc/hosts
# Error: unable to replace "host-gateway" of host entry

Current Workarounds

Partial Fixes Applied

I've made the following improvements to improve Podman detection:

1. Modified bin/lib/onboard.js to detect both Docker and Podman
2. Modified bin/lib/runner.js to auto-detect Podman machine socket
3. Modified scripts/install.sh to detect Apple Silicon even when running under Rosetta

These fixes allow NemoClaw to properly detect and use Podman, but the host-gateway issue in OpenShell remains.

Proposed Solutions

Option 1: Document Podman Limitation (Quick)

Add a note in README that Podman on macOS is not supported, and users should use Docker Desktop or Colima.

Option 2: Patch OpenShell Dependency (Medium)

• Fork/patch OpenShell to not use host-gateway on Podman
• Detect Podman and use explicit gateway IP (10.88.0.1)
• Submit upstream PR to OpenShell

Option 3: Use Colima by Default (Recommended)

• Update installer to prefer Colima over Podman on macOS
• Colima provides full Docker API compatibility
• Already partially implemented in install script

Option 4: Add Podman Configuration Script (Complex)

• Create a platform-specific setup script for Podman
• Might require Podman upstream changes to support host-gateway on macOS

Additional Context

Related Podman issues:

• Podman on macOS doesn't properly implement host-gateway: https://github.com/containers/podman/issues/
• This is a known limitation in Podman's macOS implementation

The install script attempted to install Colima but failed when running under Rosetta. A native ARM64 terminal would allow Colima installation as a fallback.

Impact

This blocks Podman-only users on macOS from using NemoClaw. Users must either:

1. Switch to native ARM64 terminal and let installer use Colima
2. Install Docker Desktop manually
3. Wait for Podman or OpenShell fixes

Files Modified (for Podman detection improvements)

• bin/lib/onboard.js - Added Podman fallback detection
• bin/lib/runner.js - Added Podman socket auto-detection
• scripts/install.sh - Added Apple Silicon detection under Rosetta
• ~/.config/containers/containers.conf - Attempted host_containers_internal_ip configuration (didn't work)

Would appreciate guidance on which solution direction is preferred for this project.
EOF
)"

[brianwtaylor]

PR #144 adds Podman socket detection with Colima fallback priority. PR #224 extends this to also detect the Docker Desktop socket on macOS.

-brian

[kjw3]

#295 added platform detection. Podman will work with OpenShell if rootful podman is enabled. We will be dependent on OpenShell full support for Podman though before adding it to NemoClaw installer.

[wscurran]

Thanks for the report, @rajmayank93. Podman on macOS is now a first-class supported runtime as of #1359. The onboarding flow now detects Podman sockets correctly (machine socket, XDG_RUNTIME_DIR, /run/podman), and the CoreDNS patching was updated to use the container's default-gateway IP instead of resolv.conf — removing the dependency on host-gateway that Podman doesn't support on macOS.

Please give it another run with a current build and let us know if anything's still off.