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-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.
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 gatewayto fail with a misleading retry loop when Podman is running but the socket path doesn't match:Proposed Design
Document the
OPENSHELL_PODMAN_SOCKEToverride and the dynamic lookup command in:debug-openshell-clusterskill — add a diagnostic step that checks for macOS socket path mismatch when the Podman driver fails.Recommended workaround to document:
This queries Podman for the current socket path dynamically, so it always resolves correctly regardless of what temp directory macOS assigns.
Alternatives Considered
/var/folders/path — Unreliable because macOS rotates this directory.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-podmanis~/.local/share/containers/podman/machine/podman.sock, which does not exist on macOS when Podman is installed viabrew. The actual socket is at a path like/var/folders/9k/4zb7qbss3p51dl6ldl1wbnfc0000gn/T/podman/podman-machine-default-api.sock. Usingmise run gateway:dockerworks as a fallback when Docker is the intended runtime.