Skip to content

[BUG] Strix fails to connect to Docker on macOS #164

@rexgnu

Description

@rexgnu

Describe the bug
On macOS with Docker Desktop running, Strix reports "DOCKER NOT AVAILABLE" and fails to start, even though docker ps works and containers are running.

This happens because check_docker_connection() relies on docker.from_env(), which on this machine defaults to the Linux-style socket unix:///var/run/docker.sock. On this macOS setup, that socket does not exist; Docker Desktop exposes its socket at ~/.docker/run/docker.sock (and/or ~/Library/Containers/com.docker.docker/Data/docker.raw.sock), so the Python Docker client cannot connect.

Why this only affects some macOS users

  • On some systems, DOCKER_HOST is set (by Docker Desktop, shell config, or alternative runtimes like colima), so docker.from_env() connects successfully via that endpoint.
  • On others, /var/run/docker.sock is present or symlinked to the real Docker Desktop socket, so the Linux-style default still works.
  • On this machine, DOCKER_HOST is empty and /var/run/docker.sock does not exist, while ~/.docker/run/docker.sock does. That combination exposes the bug.

To Reproduce
Steps to reproduce the behavior:

  1. On macOS, install and start Docker Desktop.
  2. Confirm Docker CLI works: docker ps returns running containers.
  3. Ensure DOCKER_HOST is not set in the shell environment.
  4. Confirm /var/run/docker.sock does not exist, but ~/.docker/run/docker.sock does.
  5. Run: poetry run strix --target https://settle-cardhouse-prod.appspot.com
  6. Observe the "DOCKER NOT AVAILABLE" startup error.

Expected behavior

  • Strix should detect and connect to Docker Desktop’s socket on macOS (e.g. ~/.docker/run/docker.sock or ~/Library/Containers/com.docker.docker/Data/docker.raw.sock) when DOCKER_HOST is unset and /var/run/docker.sock is missing.
  • Error messages should provide OS-appropriate guidance:
    • On macOS: suggest ensuring Docker Desktop is running (e.g. open -a Docker).
    • On Linux: suggest relevant service commands (e.g. sudo systemctl start docker).

Environment

  • OS: macOS (Darwin)
  • Docker: Docker Desktop
  • docker CLI: works (docker ps succeeds)
  • DOCKER_HOST: unset
  • /var/run/docker.sock: missing
  • ~/.docker/run/docker.sock: present

Screenshots

Image

System Information:

  • OS: macOS 26.1
  • Strix Version or Commit: 0.4.0
  • Python Version: 3.13.17
  • LLM Used: N/A
  • Docker: Docker Desktop
  • docker CLI: works (docker ps succeeds)
  • DOCKER_HOST: unset
  • /var/run/docker.sock: missing
  • ~/.docker/run/docker.sock: present

Additional context
The docker CLI works correctly because it uses Docker contexts, but the Python docker library's from_env() method doesn't automatically detect Docker Desktop's socket location on macOS. The fix should detect the platform and try macOS-specific socket paths before falling back to the default behavior.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions