fix(e2e): separate Podman Machine loopback listeners

[matthewgrossman]

Summary

TL;DR: Running mise run e2e:podman on macOS previously failed because Podman Machine routed its internal host callback to the same address and port as the main OpenShell gateway listener. The harness now gives the main gateway and Podman callbacks distinct loopback addresses, so the command can spin up the gateway and run the Podman E2E suite successfully on macOS.

Related Issue

Fixes #2607

Changes

• Bind the macOS Podman E2E primary gateway listener to [::1]:PORT; keep native Linux on 127.0.0.1:PORT.
• Register the macOS CLI endpoint as https://localhost:PORT, relying on standard macOS IPv6-first localhost resolution while preserving a valid TLS DNS name.
• Preserve that CLI authority for SSH follow-on connections when the gateway reports ::1.
• Keep the Podman callback listener on 127.0.0.1:PORT with its restricted authorization scope; do not broaden either listener to 0.0.0.0.
• Add focused SSH authority regression coverage and align the published driver guide and debug-openshell-cluster guidance.

Testing

• mise run pre-commit passes
• mise run test passes
• cargo test -p openshell-core resolve_ssh_gateway passes
• mise run e2e:podman passes on macOS Podman Machine

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-2622.docs.buildwithfern.com/openshell

[matthewgrossman]

gator-agent

PR Review Status

Validation: PR #2622 is project-valid because it is a maintainer-authored, concentrated fix for validated issue #2607 covering macOS Podman Machine gateway loopback behavior, with matching driver-guide and debugging-skill updates.
Head SHA: eb77ee64c2ebc5df36e1726b4a096f563260025a
Base SHA: 85d992f768bf2152fc5b815fc4031c61eae1ac52
Merge base SHA: f383ee1038f91921e104405cd01e4150d533fdbe
Patch ID: bdb936589103f37cbb7d356b0f62788ea662bd19
Gator payload: 2
Review mode: initial
Previous reviewed SHA: none

Blocking findings:

• No blocking findings remain.

Carried findings:

• None

Non-blocking suggestions:

• None

Docs: Updated in docs/reference/sandbox-compute-drivers.mdx; no navigation change needed because the existing Reference folder already includes this page.

E2E: Applied test:e2e because the change affects Podman gateway listener/callback behavior and the Podman e2e harness.

Next state: gator:watch-pipeline

[github-actions]

Label test:e2e applied for eb77ee6. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[matthewgrossman]

gator-agent

PR Review Status

Validation: PR #2622 remains project-valid because it is a maintainer-authored, concentrated fix for validated issue #2607 covering macOS Podman Machine gateway loopback behavior, with matching driver-guide and debugging-skill updates.
Head SHA: 7debf050bffd19d810b520867ba4f7c09ea28880
Base SHA: 85d992f768bf2152fc5b815fc4031c61eae1ac52
Merge base SHA: f383ee1038f91921e104405cd01e4150d533fdbe
Patch ID: e6e560d6d4e65571a575f5efaf76b529b42191a6
Gator payload: 2
Review mode: follow_up
Previous reviewed SHA: eb77ee64c2ebc5df36e1726b4a096f563260025a

Blocking findings:

• GATOR-7debf050-01: The latest delta removed the explicit proxy bypass from the managed Podman gateway health probe, so proxied developer or CI environments can fail before the E2E command runs even when the gateway is healthy.

Carried findings:

• None

Docs: Already updated in docs/reference/sandbox-compute-drivers.mdx; no navigation change needed because the existing Reference folder already includes this page.

E2E: test:e2e remains required because the change affects Podman gateway listener/callback behavior and the Podman E2E harness.

Next state: gator:in-review

[matthewgrossman]

gator-agent

PR Review Status

Validation: PR #2622 remains project-valid because it is a maintainer-authored, concentrated fix for validated issue #2607 covering macOS Podman Machine gateway loopback behavior, with matching driver-guide and debugging-skill updates.
Head SHA: 4962e225e7834fb88a47ee0d82a125824cc92be4
Base SHA: 85d992f768bf2152fc5b815fc4031c61eae1ac52
Merge base SHA: f383ee1038f91921e104405cd01e4150d533fdbe
Patch ID: e6186410199d33f4e291dd37e98a84f9a354fc08
Gator payload: 2
Review mode: follow_up
Previous reviewed SHA: 7debf050bffd19d810b520867ba4f7c09ea28880

Blocking findings:

• No blocking findings remain. GATOR-7debf050-01 is resolved by the latest delta restoring curl --noproxy '*' on the managed Podman gateway health probe.

Carried findings:

• None

Docs: Already updated in docs/reference/sandbox-compute-drivers.mdx; no navigation change needed because the existing Reference folder already includes this page.

E2E: test:e2e remains required because the change affects Podman gateway listener/callback behavior and the Podman E2E harness.

Next state: gator:watch-pipeline

[matthewgrossman]

gator-agent

Monitoring Complete

PR #2622 has been merged, so gator monitoring is complete.

Head SHA: 0e3069a5dcaaf31f8b8bd425ee3da1f73c7a7cb3
Gator payload: 2
Merged at: 2026-08-07T17:55:27Z

Final action: removing active gator:* monitoring labels.