Repository navigation
docs: document macOS Podman socket path mismatch and dynamic lookup #1690
Description
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:
- User-facing docs — the Podman section of the quickstart or a compute drivers reference page.
debug-openshell-clusterskill — 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 inspectin 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.
Activity
johntmyers commentedon Jun 2, 2026
Does #1536 potentially address any of this? @krishicks
krishicks commentedon Jun 2, 2026
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.sockon macOS. Note that on my box, with Podman installed not bybrew,~/.local/share/containers/podman/machine/podman.sockis a symlink to a temp path under/var/folderslike the OP.I did just install podman via
brewand can confirm it does not write~/.local/share/containers/podman/machine/podman.sock.It's unfortunate Podman is so inconsistent between distributions.
maxamillion commentedon Jun 29, 2026
github-actions commentedon Aug 30, 2026
This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.
docs(podman): document macOS socket path mismatch and dynamic lookup
fix(podman): resolve macOS Podman socket dynamically (NVIDIA#3135)