fix(driver-podman): resolve Podman socket via auto-detection

Align Podman socket selection with the existing Docker model: explicit
config wins, otherwise probe openshell-core for a responsive socket.
This also fixes the original HOME-unset panic, since resolution no
longer hardcodes a per-OS default path.

- add detect_podman_socket() in openshell-core, mirroring
  detect_docker_socket
- PodmanComputeConfig.socket_path is now Option<PathBuf>, no default
- remove default_socket_path() (podman driver) and podman_socket_path()
  (vm driver), both replaced by the shared detector
- update server env override and CLI for the new Option type
- add tests: responsive-candidate detection in openshell-core, and
  config-error (not panic) when no socket is configured or reachable

Author: mesutoezdil

crates/openshell-core/src/config.rs

@@ -171,9 +171,19 @@ pub fn detect_driver() -> Option<ComputeDriverKind> {
 }
 
 fn is_podman_available() -> bool {
-    podman_socket_candidates()
+    detect_podman_socket().is_some()
+}
+
+/// Return the first responsive Podman API socket, or `None` if none respond.
+pub fn detect_podman_socket() -> Option<PathBuf> {
+    detect_podman_socket_from_candidates(&podman_socket_candidates())
+}
+
+fn detect_podman_socket_from_candidates(candidates: &[PathBuf]) -> Option<PathBuf> {
+    candidates
         .iter()
-        .any(|path| podman_socket_responds(path))
+        .find(|path| podman_socket_responds(path))
+        .cloned()
 }
 
 fn podman_socket_candidates() -> Vec<PathBuf> {
@@ -972,8 +982,9 @@ mod tests {
         ComputeDriverKind, Config, DEFAULT_SERVICE_ROUTING_DOMAIN, GatewayInterceptorBindingPolicy,
         GatewayInterceptorConfig, GatewayInterceptorFailurePolicy, GatewayJwtConfig,
         GatewayProviderProfileSourceConfig, detect_docker_socket_from_candidates, detect_driver,
-        docker_host_unix_socket_path, docker_socket_responds, is_unix_socket,
-        normalize_compute_driver_name, podman_socket_candidates_from_env, podman_socket_responds,
+        detect_podman_socket_from_candidates, docker_host_unix_socket_path, docker_socket_responds,
+        is_unix_socket, normalize_compute_driver_name, podman_socket_candidates_from_env,
+        podman_socket_responds,
     };
     #[cfg(unix)]
     use std::io::{Read as _, Write as _};
@@ -1349,6 +1360,34 @@ mod tests {
         )));
     }
 
+    #[cfg(unix)]
+    #[test]
+    fn podman_socket_detection_returns_the_responsive_candidate() {
+        let temp_dir = tempfile::tempdir().expect("create temp dir");
+        let inactive_path = temp_dir.path().join("inactive.sock");
+        let inactive_listener = UnixListener::bind(&inactive_path).expect("bind inactive socket");
+        drop(inactive_listener);
+
+        let responsive_path = temp_dir.path().join("responsive.sock");
+        let listener = UnixListener::bind(&responsive_path).expect("bind responsive socket");
+        let handle = std::thread::spawn(move || {
+            let (mut stream, _) = listener.accept().expect("accept podman probe");
+            let mut request = [0_u8; 128];
+            let _ = stream.read(&mut request).expect("read podman probe");
+            stream
+                .write_all(
+                    b"HTTP/1.1 200 OK\r\nLibpod-Api-Version: 5.8.2\r\nContent-Length: 2\r\n\r\nOK",
+                )
+                .expect("write podman ping response");
+        });
+
+        assert_eq!(
+            detect_podman_socket_from_candidates(&[inactive_path, responsive_path.clone(),]),
+            Some(responsive_path)
+        );
+        handle.join().expect("probe server exits");
+    }
+
     #[test]
     #[allow(unsafe_code)] // std::env::set_var/remove_var require unsafe in Rust 2024
     fn detect_driver_prefers_kubernetes_when_k8s_env_is_set() {

crates/openshell-driver-podman/src/config.rs

@@ -70,9 +70,11 @@ impl FromStr for ImagePullPolicy {
 #[serde(default, deny_unknown_fields)]
 pub struct PodmanComputeConfig {
     /// Path to the Podman API Unix socket.
-    /// Default: `$XDG_RUNTIME_DIR/podman/podman.sock` (Linux),
-    /// `$HOME/.local/share/containers/podman/machine/podman.sock` (macOS).
-    pub socket_path: PathBuf,
+    ///
+    /// `None` means auto-detect: the driver probes
+    /// [`openshell_core::config::detect_podman_socket`] for the first
+    /// responsive candidate when it starts.
+    pub socket_path: Option<PathBuf>,
     /// Default OCI image for sandboxes.
     pub default_image: String,
     /// Image pull policy for sandbox images.
@@ -215,38 +217,12 @@ impl PodmanComputeConfig {
             String::new()
         }
     }
-
-    /// Resolve the default socket path from the environment.
-    ///
-    /// - **macOS**: `$HOME/.local/share/containers/podman/machine/podman.sock`
-    ///   (the symlink created by `podman machine` pointing to the VM API socket).
-    /// - **Linux**: `$XDG_RUNTIME_DIR/podman/podman.sock` when set (by
-    ///   `pam_systemd`/logind), otherwise `/run/user/{uid}/podman/podman.sock`
-    ///   using the real UID via `getuid()`.
-    #[must_use]
-    pub fn default_socket_path() -> PathBuf {
-        #[cfg(target_os = "macos")]
-        {
-            let home = std::env::var("HOME").expect("HOME must be set on macOS");
-            PathBuf::from(home).join(".local/share/containers/podman/machine/podman.sock")
-        }
-        #[cfg(target_os = "linux")]
-        {
-            std::env::var("XDG_RUNTIME_DIR").map_or_else(
-                |_| {
-                    let uid = rustix::process::getuid().as_raw();
-                    PathBuf::from(format!("/run/user/{uid}/podman/podman.sock"))
-                },
-                |xdg| PathBuf::from(xdg).join("podman/podman.sock"),
-            )
-        }
-    }
 }
 
 impl Default for PodmanComputeConfig {
     fn default() -> Self {
         Self {
-            socket_path: Self::default_socket_path(),
+            socket_path: None,
             default_image: openshell_core::image::default_sandbox_image(),
             image_pull_policy: ImagePullPolicy::default(),
             grpc_endpoint: String::new(),
@@ -296,39 +272,6 @@ impl std::fmt::Debug for PodmanComputeConfig {
 mod tests {
     use super::*;
 
-    /// Serialises env-mutating tests so that parallel test threads cannot
-    /// observe each other's changes to `XDG_RUNTIME_DIR`.
-    static ENV_LOCK: std::sync::LazyLock<std::sync::Mutex<()>> =
-        std::sync::LazyLock::new(|| std::sync::Mutex::new(()));
-
-    #[test]
-    #[cfg(target_os = "linux")]
-    fn default_socket_path_respects_xdg_runtime_dir() {
-        let _guard = ENV_LOCK
-            .lock()
-            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        temp_env::with_vars([("XDG_RUNTIME_DIR", Some("/tmp/test-xdg"))], || {
-            let path = PodmanComputeConfig::default_socket_path();
-            assert_eq!(path, PathBuf::from("/tmp/test-xdg/podman/podman.sock"));
-        });
-    }
-
-    #[test]
-    #[cfg(target_os = "linux")]
-    fn default_socket_path_falls_back_to_uid() {
-        let _guard = ENV_LOCK
-            .lock()
-            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        temp_env::with_vars([("XDG_RUNTIME_DIR", None::<&str>)], || {
-            let path = PodmanComputeConfig::default_socket_path();
-            let uid = rustix::process::getuid().as_raw();
-            assert_eq!(
-                path,
-                PathBuf::from(format!("/run/user/{uid}/podman/podman.sock"))
-            );
-        });
-    }
-
     #[test]
     fn default_config_sets_health_check_interval() {
         let cfg = PodmanComputeConfig::default();
@@ -382,21 +325,6 @@ mod tests {
         assert!(err.to_string().contains("sandbox_pids_limit"));
     }
 
-    #[test]
-    #[cfg(target_os = "macos")]
-    fn default_socket_path_uses_podman_machine_on_macos() {
-        let _guard = ENV_LOCK
-            .lock()
-            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        temp_env::with_vars([("HOME", Some("/Users/testuser"))], || {
-            let path = PodmanComputeConfig::default_socket_path();
-            assert_eq!(
-                path,
-                PathBuf::from("/Users/testuser/.local/share/containers/podman/machine/podman.sock")
-            );
-        });
-    }
-
     // ── TLS config validation ─────────────────────────────────────────
 
     #[test]

crates/openshell-driver-podman/src/container.rs

@@ -1808,7 +1808,7 @@ mod tests {
 
     fn test_config() -> PodmanComputeConfig {
         PodmanComputeConfig {
-            socket_path: std::path::PathBuf::from("/tmp/test.sock"),
+            socket_path: Some(std::path::PathBuf::from("/tmp/test.sock")),
             default_image: "test-image:latest".to_string(),
             grpc_endpoint: "http://localhost:50051".to_string(),
             host_gateway_ip: String::new(),

crates/openshell-driver-podman/src/driver.rs

@@ -163,16 +163,32 @@ impl PodmanComputeDriver {
         const MAX_PING_RETRIES: u32 = 5;
         const PING_RETRY_DELAY: Duration = Duration::from_secs(2);
 
-        if !config.socket_path.exists() {
+        // Explicit configuration wins; otherwise probe for a responsive socket.
+        // Unlike Docker, Podman has no single well-known default path, so
+        // there is no further fallback if neither resolves.
+        let socket_path = config
+            .socket_path
+            .clone()
+            .or_else(openshell_core::config::detect_podman_socket)
+            .ok_or_else(|| {
+                PodmanApiError::InvalidInput(
+                    "no responsive Podman API socket found; set OPENSHELL_PODMAN_SOCKET \
+                     or configure socket_path"
+                        .to_string(),
+                )
+            })?;
+        config.socket_path = Some(socket_path.clone());
+
+        if !socket_path.exists() {
             if cfg!(target_os = "macos") {
                 warn!(
-                    path = %config.socket_path.display(),
+                    path = %socket_path.display(),
                     "Podman socket not found; is podman machine running? \
                      Try `podman machine start` or set OPENSHELL_PODMAN_SOCKET to override."
                 );
             } else {
                 warn!(
-                    path = %config.socket_path.display(),
+                    path = %socket_path.display(),
                     "Podman socket not found; is the Podman service running? \
                      Set OPENSHELL_PODMAN_SOCKET or XDG_RUNTIME_DIR to override."
                 );
@@ -186,7 +202,7 @@ impl PodmanComputeDriver {
         config.validate_runtime_limits()?;
         config.validate_host_gateway_ip()?;
 
-        let client = PodmanClient::new(config.socket_path.clone());
+        let client = PodmanClient::new(socket_path);
 
         // Verify connectivity, retrying briefly to tolerate transient socket
         // unavailability (e.g. podman.socket restarting after a package
@@ -774,7 +790,7 @@ impl PodmanComputeDriver {
         gpu_inventory: CdiGpuInventory,
         allow_all_default_gpu: bool,
     ) -> Self {
-        let client = PodmanClient::new(config.socket_path.clone());
+        let client = PodmanClient::new(config.socket_path.clone().unwrap_or_default());
         let refresh_inventory = gpu_inventory.clone();
         Self {
             client,
@@ -850,6 +866,59 @@ mod tests {
     use std::fs;
     use std::path::PathBuf;
 
+    // ── socket resolution ───────────────────────────────────────────────
+
+    /// Restores env vars on drop, even if the test body panics.
+    struct EnvVarGuard(Vec<(&'static str, Option<String>)>);
+
+    impl EnvVarGuard {
+        #[allow(unsafe_code)] // std::env::set_var requires unsafe in Rust 2024
+        fn set(vars: &[(&'static str, &str)]) -> Self {
+            let saved = vars
+                .iter()
+                .map(|(name, value)| {
+                    let previous = std::env::var(name).ok();
+                    unsafe { std::env::set_var(name, value) };
+                    (*name, previous)
+                })
+                .collect();
+            Self(saved)
+        }
+    }
+
+    impl Drop for EnvVarGuard {
+        #[allow(unsafe_code)] // std::env::set_var/remove_var require unsafe in Rust 2024
+        fn drop(&mut self) {
+            for (name, previous) in &self.0 {
+                unsafe {
+                    match previous {
+                        Some(value) => std::env::set_var(name, value),
+                        None => std::env::remove_var(name),
+                    }
+                }
+            }
+        }
+    }
+
+    #[tokio::test]
+    async fn new_returns_config_error_when_no_socket_is_configured_or_detected() {
+        let _guard = EnvVarGuard::set(&[
+            ("OPENSHELL_PODMAN_SOCKET", "/nonexistent/podman.sock"),
+            ("XDG_RUNTIME_DIR", "/nonexistent/xdg"),
+            ("HOME", "/nonexistent/home"),
+        ]);
+
+        let config = PodmanComputeConfig {
+            socket_path: None,
+            ..PodmanComputeConfig::default()
+        };
+        let err = PodmanComputeDriver::new(config)
+            .await
+            .expect_err("no socket is configured or reachable");
+
+        assert!(err.to_string().contains("no responsive Podman API socket"));
+    }
+
     fn cdi_devices_config(device_ids: &[&str]) -> prost_types::Struct {
         prost_types::Struct {
             fields: std::iter::once((
@@ -1245,7 +1314,7 @@ mod tests {
 
     fn test_driver(socket_path: PathBuf) -> PodmanComputeDriver {
         let config = PodmanComputeConfig {
-            socket_path,
+            socket_path: Some(socket_path),
             stop_timeout_secs: 10,
             ..PodmanComputeConfig::default()
         };
@@ -1453,7 +1522,7 @@ mod tests {
             )],
         );
         let config = PodmanComputeConfig {
-            socket_path: socket_path.clone(),
+            socket_path: Some(socket_path.clone()),
             enable_bind_mounts: true,
             ..PodmanComputeConfig::default()
         };

crates/openshell-driver-podman/src/grpc.rs

@@ -179,7 +179,7 @@ mod tests {
 
     fn test_service(socket_path: PathBuf) -> ComputeDriverService {
         let config = PodmanComputeConfig {
-            socket_path,
+            socket_path: Some(socket_path),
             stop_timeout_secs: 10,
             ..PodmanComputeConfig::default()
         };

crates/openshell-driver-podman/src/main.rs

@@ -114,12 +114,8 @@ async fn main() -> Result<()> {
         )
         .init();
 
-    let socket_path = args
-        .podman_socket
-        .unwrap_or_else(PodmanComputeConfig::default_socket_path);
-
     let driver = PodmanComputeDriver::new(PodmanComputeConfig {
-        socket_path,
+        socket_path: args.podman_socket,
         default_image: args.sandbox_image.unwrap_or_default(),
         image_pull_policy: args.sandbox_image_pull_policy,
         grpc_endpoint: args.grpc_endpoint.unwrap_or_default(),

crates/openshell-driver-vm/src/driver.rs

@@ -3270,10 +3270,9 @@ async fn connect_local_container_engine() -> Option<Docker> {
         return Some(docker);
     }
 
-    let podman_socket = podman_socket_path();
-    if podman_socket.exists()
-        && let Ok(docker) =
-            Docker::connect_with_unix(podman_socket.to_str()?, 120, bollard::API_DEFAULT_VERSION)
+    let podman_socket = openshell_core::config::detect_podman_socket()?;
+    if let Ok(docker) =
+        Docker::connect_with_unix(podman_socket.to_str()?, 120, bollard::API_DEFAULT_VERSION)
         && docker.ping().await.is_ok()
     {
         info!(
@@ -3286,25 +3285,6 @@ async fn connect_local_container_engine() -> Option<Docker> {
     None
 }
 
-/// Podman user socket path for the current platform.
-fn podman_socket_path() -> PathBuf {
-    #[cfg(target_os = "macos")]
-    {
-        let home = std::env::var("HOME").unwrap_or_default();
-        PathBuf::from(home).join(".local/share/containers/podman/machine/podman.sock")
-    }
-    #[cfg(target_os = "linux")]
-    {
-        std::env::var("XDG_RUNTIME_DIR").map_or_else(
-            |_| {
-                let uid = nix::unistd::getuid();
-                PathBuf::from(format!("/run/user/{uid}/podman/podman.sock"))
-            },
-            |xdg| PathBuf::from(xdg).join("podman/podman.sock"),
-        )
-    }
-}
-
 fn is_openshell_local_build_image_ref(image_ref: &str) -> bool {
     image_ref.starts_with("openshell/sandbox-from:")
 }

crates/openshell-server/src/compute/driver_config.rs

@@ -195,7 +195,7 @@ fn apply_vm_runtime_defaults(cfg: &mut VmComputeConfig, context: DriverStartupCo
 
 fn apply_podman_env_overrides(podman: &mut PodmanComputeConfig) {
     if let Ok(p) = std::env::var("OPENSHELL_PODMAN_SOCKET") {
-        podman.socket_path = PathBuf::from(p);
+        podman.socket_path = Some(PathBuf::from(p));
     }
     if let Ok(ip) = std::env::var("OPENSHELL_PODMAN_HOST_GATEWAY_IP") {
         podman.host_gateway_ip = ip;