docs: document macOS Podman socket path mismatch and dynamic lookup

[abraham2512]

Problem Statement

On macOS, the Podman socket lives under /var/folders/ (e.g. /var/folders/9k/.../podman-machine-default-api.sock), not at the default path OpenShell checks (~/.local/share/containers/podman/machine/podman.sock). The /var/folders/ path can also change after a reboot since macOS rotates per-user temp directories.

This causes mise run gateway to fail with a misleading retry loop when Podman is running but the socket path doesn't match:

WARN openshell_driver_podman::driver: Podman socket not found; is podman machine running?
WARN openshell_driver_podman::driver: Podman socket not ready, retrying attempt=1 max_retries=5
...
Error: failed to create compute runtime: connection error: ...podman.sock: No such file or directory

Proposed Design

Document the OPENSHELL_PODMAN_SOCKET override and the dynamic lookup command in:

1. User-facing docs — the Podman section of the quickstart or a compute drivers reference page.
2. debug-openshell-cluster skill — add a diagnostic step that checks for macOS socket path mismatch when the Podman driver fails.

Recommended workaround to document:

export OPENSHELL_PODMAN_SOCKET="$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')"

This queries Podman for the current socket path dynamically, so it always resolves correctly regardless of what temp directory macOS assigns.

Alternatives Considered

• Hardcode the /var/folders/ path — Unreliable because macOS rotates this directory.
• Auto-detect via podman machine inspect in the driver — Would add a subprocess call to the hot path; the env var override is simpler and user-controlled.

Agent Investigation

Confirmed the issue locally. The default socket path in openshell-driver-podman is ~/.local/share/containers/podman/machine/podman.sock, which does not exist on macOS when Podman is installed via brew. The actual socket is at a path like /var/folders/9k/4zb7qbss3p51dl6ldl1wbnfc0000gn/T/podman/podman-machine-default-api.sock. Using mise run gateway:docker works as a fallback when Docker is the intended runtime.

[johntmyers]

Does #1536 potentially address any of this? @krishicks

[krishicks]

It does not; if the brew-installed Podman doesn't write ~/.local/share/containers/podman/machine/podman.sock, the Podman auto-detection won't detect it, nor will the Podman client work as it only considers ~/.local/share/containers/podman/machine/podman.sock on macOS. Note that on my box, with Podman installed not by brew, ~/.local/share/containers/podman/machine/podman.sock is a symlink to a temp path under /var/folders like the OP.

I did just install podman via brew and can confirm it does not write ~/.local/share/containers/podman/machine/podman.sock.

It's unfortunate Podman is so inconsistent between distributions.

[maxamillion]

📋 triage-agent

Triage Assessment

Classification: feature-valid (documentation/runbook gap)

Summary

This is a valid macOS Podman compatibility documentation issue. OpenShell already supports overriding the Podman API socket with OPENSHELL_PODMAN_SOCKET, but the published Podman docs and cluster-debugging skill do not show the dynamic podman machine inspect lookup needed for Homebrew Podman installs that do not create the expected ~/.local/share/containers/podman/machine/podman.sock symlink.

Investigation

• The Podman driver default still uses $HOME/.local/share/containers/podman/machine/podman.sock on macOS (crates/openshell-driver-podman/src/config.rs).
• The gateway/driver already accepts OPENSHELL_PODMAN_SOCKET (crates/openshell-server/src/lib.rs, crates/openshell-driver-podman/src/main.rs) and logs an override hint when the socket is missing (crates/openshell-driver-podman/src/driver.rs).
• PR fix(gateway): try harder to detect Podman #1536 improved Podman auto-detection for standard socket candidates, but it does not cover Homebrew Podman's case when the standard macOS symlink is absent and the active API socket is only discoverable through podman machine inspect.
• User-facing docs mention Podman driver setup in docs/reference/sandbox-compute-drivers.mdx and container-gateway Podman setup in docs/about/container-gateway.mdx, but they do not document the macOS dynamic socket lookup workaround.
• The debug-openshell-cluster skill has a Podman-backed gateway check, but it does not yet include a macOS socket-mismatch diagnostic.

Recommendation

Route this as a narrow documentation/support improvement: add the macOS podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}' workaround to the Podman docs and add a corresponding diagnostic step to debug-openshell-cluster. No state:agent-ready label should be applied by triage; a maintainer can decide when this is ready to build.