feat(docker): add cli fallback for docker connection checks

Implement a two-phase approach for checking Docker availability.
The system now tries the Docker SDK first and falls back to
`docker info` via CLI if the SDK fails. This improves support
for remote Docker setups (like VirtualBox or DOCKER_HOST) where
the SDK might not inherit the correct shell environment.

- Update check_docker_connection to include subprocess fallback
- Improve error messages to cover remote Docker host scenarios
- Update unit tests to reflect new connection logic and messages

Author: Hamza5

apps/file-brain/file_brain/services/docker_manager.py

@@ -134,7 +134,7 @@ def _get_friendly_error_message(self, error_msg: str) -> Optional[str]:
         )
 
         if is_connection_error:
-            return "Docker Desktop is likely not running. Please start Docker Desktop and try again."
+            return "Docker is not reachable. If you are using Docker Desktop, please start it and try again."
 
         if "permission denied" in error_msg_lower:
             return (
@@ -357,12 +357,22 @@ def check_docker_connection(self) -> Dict[str, any]:
         """
         Check if we can actually connect to the Docker daemon.
 
+        Uses a two-phase approach:
+        1. Try the Docker SDK (docker.from_env()) which reads DOCKER_HOST / Docker SDK env vars.
+        2. If that fails, fall back to running `docker info` via CLI subprocess, which respects
+           Docker Desktop contexts and system-level DOCKER_HOST configurations.
+
+        This handles users pointing the Docker CLI at a remote daemon (e.g. VirtualBox VM)
+        where the SDK may not automatically pick up the active Docker context.
+
         Returns:
             Dictionary with success and error message
         """
         if not self.docker_cmd:
             return {"success": False, "error": "Docker not found"}
 
+        # Try Docker SDK
+        sdk_error: Optional[str] = None
         try:
             import docker
 
@@ -371,11 +381,38 @@ def check_docker_connection(self) -> Dict[str, any]:
             client.close()
             return {"success": True}
         except Exception as e:
-            error_msg = str(e)
+            sdk_error = str(e)
+            logger.debug(f"Docker SDK connection failed: {sdk_error} — will try CLI fallback")
+
+        # CLI fallback via `docker info` — respects Docker contexts and system-level config
+        try:
+            result = subprocess.run(
+                [self.docker_cmd, "info"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if result.returncode == 0:
+                logger.info("Docker daemon reachable via CLI (SDK fallback succeeded)")
+                return {"success": True}
+
+            # CLI also failed — build the best error message we can
+            cli_error = result.stderr or result.stdout or sdk_error or "unknown error"
+            friendly_msg = self._get_friendly_error_message(cli_error) or self._get_friendly_error_message(
+                sdk_error or ""
+            )
+            return {
+                "success": False,
+                "error": friendly_msg or f"Failed to connect to Docker: {cli_error}",
+            }
+        except Exception as cli_exc:
+            # Both SDK and CLI failed; surface the clearest error
+            error_msg = sdk_error or str(cli_exc)
             friendly_msg = self._get_friendly_error_message(error_msg)
-            if friendly_msg:
-                return {"success": False, "error": friendly_msg}
-            return {"success": False, "error": f"Failed to connect to Docker: {error_msg}"}
+            return {
+                "success": False,
+                "error": friendly_msg or f"Failed to connect to Docker: {error_msg}",
+            }
 
     def _pull_images_docker_sdk(self, images: List[str], progress_callback=None):
         """Pull images using Docker SDK with progress streaming (non-blocking)"""

apps/file-brain/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "file-brain"
-version = "0.1.26a1"
+version = "0.1.26a2"
 description = "Smart local file search engine that understands your files"
 authors = [{ name = "Hamza Abbad", email = "contact@file-brain.com" }]
 readme = "README.md"

apps/file-brain/tests/unit/test_docker_manager_errors.py

@@ -23,11 +23,11 @@ def test_friendly_error_message(docker_manager):
     msg = docker_manager._get_friendly_error_message(
         "Error response from daemon: Dial pipe //./pipe/docker_engine: The system cannot find the file specified."
     )
-    assert "Docker Desktop is likely not running" in msg
+    assert "Docker is not reachable" in msg
 
     # Test connection error (Mac/Linux connection refused)
     msg = docker_manager._get_friendly_error_message("Connection refused")
-    assert "Docker Desktop is likely not running" in msg
+    assert "Docker is not reachable" in msg
 
     # Test permission error - now handled
     msg = docker_manager._get_friendly_error_message("permission denied while trying to connect to the Docker daemon")
@@ -65,17 +65,24 @@ def test_check_docker_connection_success(docker_manager):
 
 
 def test_check_docker_connection_failure(docker_manager):
-    """Test failed docker connection check."""
+    """Test failed docker connection check - both SDK and CLI fallback fail."""
     mock_docker_module = MagicMock()
     mock_docker_module.from_env.side_effect = Exception("Error while fetching server API version")
 
+    # Mock subprocess.run so the CLI fallback also fails
+    mock_cli_result = MagicMock()
+    mock_cli_result.returncode = 1
+    mock_cli_result.stdout = ""
+    mock_cli_result.stderr = "Error while fetching server API version"
+
     with patch.dict(sys.modules, {"docker": mock_docker_module}):
-        docker_manager.docker_cmd = "docker"
+        with patch("subprocess.run", return_value=mock_cli_result):
+            docker_manager.docker_cmd = "docker"
 
-        result = docker_manager.check_docker_connection()
+            result = docker_manager.check_docker_connection()
 
     assert result["success"] is False
-    assert "Docker Desktop is likely not running" in result["error"]
+    assert "Docker is not reachable" in result["error"]
 
 
 @patch("subprocess.run")
@@ -109,4 +116,4 @@ def test_start_services_connection_failure(mock_run, docker_manager):
     assert result["success"] is False
     # The start_services method uses logical OR: friendly_msg or f"Failed..."
     # So if friendly_msg is returned, it is used.
-    assert "Docker Desktop is likely not running" in result["error"]
+    assert "Docker is not reachable" in result["error"]