Expose resolved Docker endpoint and failure reason in diagnostics

Record the resolved Docker endpoint summary and last connection error in daemon startup state, surface them through the docker info API, and include the resolved endpoint details in coast doctor failures. Keep transport behavior unchanged.

Refs: #65

Co-authored-by: Codex <noreply@openai.com>

Author: agustif

coast-cli/src/commands/doctor.rs

@@ -99,8 +99,25 @@ pub async fn execute(args: &DoctorArgs) -> Result<()> {
 
     let db = rusqlite::Connection::open(&db_path).context("Failed to open state database")?;
 
-    let docker = coast_docker::host::connect_to_host_docker()
-        .context("Failed to connect to Docker. Is Docker running and is your active Docker context reachable?")?;
+    let probe = coast_docker::host::probe_host_docker();
+    let docker = match probe.docker {
+        Ok(docker) => docker,
+        Err(error) => {
+            let mut detail =
+                "Failed to connect to Docker. Is Docker running and is your active Docker context reachable?".to_string();
+            if let Some(endpoint) = probe.endpoint {
+                detail.push_str(&format!(
+                    "\nResolved endpoint source: {}\nResolved endpoint host: {}",
+                    coast_docker::host::docker_endpoint_source_label(&endpoint.source),
+                    endpoint.host
+                ));
+                if let Some(context) = endpoint.context {
+                    detail.push_str(&format!("\nResolved context: {context}"));
+                }
+            }
+            return Err(anyhow::anyhow!("{detail}\n{error}"));
+        }
+    };
 
     let mut fixes: Vec<String> = Vec::new();
     let mut findings: Vec<String> = Vec::new();

coast-core/src/protocol/api_types.rs

@@ -338,6 +338,10 @@ pub struct DockerInfoResponse {
     pub server_version: String,
     pub can_adjust: bool,
     pub provider: String,
+    pub endpoint_source: Option<String>,
+    pub endpoint_host: Option<String>,
+    pub context_name: Option<String>,
+    pub connect_error: Option<String>,
 }
 
 /// Response after requesting Docker Desktop settings to be opened.

coast-core/src/protocol/tests.rs

@@ -1026,13 +1026,23 @@ fn test_docker_info_response_serialization() {
         server_version: "28.3.3".to_string(),
         can_adjust: true,
         provider: "docker-desktop".to_string(),
+        endpoint_source: Some("config_context".to_string()),
+        endpoint_host: Some("unix:///Users/test/.orbstack/run/docker.sock".to_string()),
+        context_name: Some("orbstack".to_string()),
+        connect_error: None,
     };
     let json = serde_json::to_value(&resp).unwrap();
     assert_eq!(json["mem_total_bytes"], 8_589_934_592u64);
     assert_eq!(json["cpus"], 4);
     assert_eq!(json["os"], "Docker Desktop");
     assert_eq!(json["server_version"], "28.3.3");
     assert_eq!(json["can_adjust"], true);
+    assert_eq!(json["endpoint_source"], "config_context");
+    assert_eq!(
+        json["endpoint_host"],
+        "unix:///Users/test/.orbstack/run/docker.sock"
+    );
+    assert_eq!(json["context_name"], "orbstack");
 }
 
 #[test]

coast-daemon/src/api/query/docker.rs

@@ -7,6 +7,7 @@ use axum::{Json, Router};
 use tokio::sync::OnceCell;
 
 use coast_core::protocol::{DockerInfoResponse, OpenDockerSettingsResponse};
+use coast_docker::host::docker_endpoint_source_label;
 
 use crate::server::AppState;
 
@@ -53,6 +54,19 @@ async fn docker_info(State(state): State<Arc<AppState>>) -> Json<DockerInfoRespo
         server_version: String::new(),
         can_adjust: false,
         provider: String::new(),
+        endpoint_source: state
+            .docker_endpoint
+            .as_ref()
+            .map(|endpoint| docker_endpoint_source_label(&endpoint.source).to_string()),
+        endpoint_host: state
+            .docker_endpoint
+            .as_ref()
+            .map(|endpoint| endpoint.host.clone()),
+        context_name: state
+            .docker_endpoint
+            .as_ref()
+            .and_then(|endpoint| endpoint.context.clone()),
+        connect_error: state.docker_connect_error.clone(),
     });
 
     let Some(docker) = state.docker.as_ref() else {
@@ -81,6 +95,19 @@ async fn docker_info(State(state): State<Arc<AppState>>) -> Json<DockerInfoRespo
         server_version,
         can_adjust,
         provider,
+        endpoint_source: state
+            .docker_endpoint
+            .as_ref()
+            .map(|endpoint| docker_endpoint_source_label(&endpoint.source).to_string()),
+        endpoint_host: state
+            .docker_endpoint
+            .as_ref()
+            .map(|endpoint| endpoint.host.clone()),
+        context_name: state
+            .docker_endpoint
+            .as_ref()
+            .and_then(|endpoint| endpoint.context.clone()),
+        connect_error: state.docker_connect_error.clone(),
     })
 }
 

coast-daemon/src/api/tests.rs

@@ -1391,6 +1391,10 @@ mod tests {
             .unwrap();
         let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
         assert_eq!(json["connected"], false);
+        assert!(json.get("endpoint_source").is_some());
+        assert!(json.get("endpoint_host").is_some());
+        assert!(json.get("context_name").is_some());
+        assert!(json.get("connect_error").is_some());
     }
 
     #[tokio::test]

coast-daemon/src/server.rs

@@ -21,6 +21,7 @@ use crate::analytics::{self, AnalyticsClient, CommandSource};
 use crate::api::streaming::spawn_agent_shell_if_configured;
 use crate::handlers;
 use crate::state::StateDb;
+use coast_docker::host::{docker_endpoint_source_label, DockerEndpoint};
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum UpdateOperationKind {
@@ -120,6 +121,10 @@ pub struct AppState {
     /// Bollard Docker client connected to the host daemon.
     /// None in test environments where Docker is not available.
     pub docker: Option<bollard::Docker>,
+    /// Resolved Docker endpoint metadata, if endpoint resolution succeeded.
+    pub docker_endpoint: Option<DockerEndpoint>,
+    /// Last Docker connection error captured at daemon startup, if any.
+    pub docker_connect_error: Option<String>,
     /// Broadcast channel for WebSocket event notifications.
     pub event_bus: tokio::sync::broadcast::Sender<CoastEvent>,
     /// Persistent PTY sessions for the host terminal feature.
@@ -186,11 +191,23 @@ pub struct AppState {
 impl AppState {
     /// Create a new `AppState` with the given state database and Docker client.
     pub fn new(db: StateDb) -> Self {
-        let docker = match coast_docker::host::connect_to_host_docker() {
-            Ok(docker) => Some(docker),
+        let probe = coast_docker::host::probe_host_docker();
+        let docker_endpoint = probe.endpoint.clone();
+        let (docker, docker_connect_error) = match probe.docker {
+            Ok(docker) => (Some(docker), None),
             Err(error) => {
-                warn!(error = %error, "Docker is unavailable at daemon startup");
-                None
+                if let Some(ref endpoint) = docker_endpoint {
+                    warn!(
+                        source = docker_endpoint_source_label(&endpoint.source),
+                        host = %endpoint.host,
+                        context = endpoint.context.as_deref().unwrap_or(""),
+                        error = %error,
+                        "Docker is unavailable at daemon startup"
+                    );
+                } else {
+                    warn!(error = %error, "Docker is unavailable at daemon startup");
+                }
+                (None, Some(error.to_string()))
             }
         };
         let (event_bus, _) = tokio::sync::broadcast::channel(256);
@@ -214,6 +231,8 @@ impl AppState {
         Self {
             db: Mutex::new(db),
             docker,
+            docker_endpoint,
+            docker_connect_error,
             event_bus,
             pty_sessions: Mutex::new(std::collections::HashMap::new()),
             exec_sessions: Mutex::new(std::collections::HashMap::new()),
@@ -249,6 +268,8 @@ impl AppState {
         Self {
             db: Mutex::new(db),
             docker: None,
+            docker_endpoint: None,
+            docker_connect_error: None,
             event_bus,
             pty_sessions: Mutex::new(std::collections::HashMap::new()),
             exec_sessions: Mutex::new(std::collections::HashMap::new()),
@@ -290,6 +311,11 @@ impl AppState {
             )
             .expect("bollard stub client creation should not fail"),
         );
+        s.docker_endpoint = Some(DockerEndpoint {
+            host: "http://127.0.0.1:0".to_string(),
+            source: coast_docker::host::DockerEndpointSource::EnvHost,
+            context: None,
+        });
         s
     }
 

coast-docker/src/host.rs

@@ -30,6 +30,21 @@ pub struct DockerEndpoint {
     pub context: Option<String>,
 }
 
+#[derive(Debug)]
+pub struct HostDockerProbe {
+    pub endpoint: Option<DockerEndpoint>,
+    pub docker: Result<Docker>,
+}
+
+pub fn docker_endpoint_source_label(source: &DockerEndpointSource) -> &'static str {
+    match source {
+        DockerEndpointSource::EnvHost => "env_host",
+        DockerEndpointSource::EnvContext => "env_context",
+        DockerEndpointSource::ConfigContext => "config_context",
+        DockerEndpointSource::DefaultLocal => "default_local",
+    }
+}
+
 #[derive(Debug, Deserialize)]
 struct DockerCliConfig {
     #[serde(rename = "currentContext")]
@@ -51,32 +66,49 @@ struct ContextEndpoint {
 }
 
 pub fn connect_to_host_docker() -> Result<Docker> {
-    connect_to_host_docker_with(
+    probe_host_docker().docker
+}
+
+pub fn probe_host_docker() -> HostDockerProbe {
+    probe_host_docker_with(
         env::var_os("DOCKER_CONFIG").map(PathBuf::from),
         env::var("DOCKER_HOST").ok(),
         env::var("DOCKER_CONTEXT").ok(),
     )
 }
 
-fn connect_to_host_docker_with(
+fn probe_host_docker_with(
     docker_config_dir: Option<PathBuf>,
     env_host: Option<String>,
     env_context: Option<String>,
-) -> Result<Docker> {
-    let endpoint = resolve_docker_endpoint(
+) -> HostDockerProbe {
+    let endpoint = match resolve_docker_endpoint(
         docker_config_dir.as_deref(),
         env_host.as_deref(),
         env_context.as_deref(),
-    )?;
+    ) {
+        Ok(endpoint) => endpoint,
+        Err(error) => {
+            return HostDockerProbe {
+                endpoint: None,
+                docker: Err(error),
+            };
+        }
+    };
 
-    match endpoint.source {
+    let docker = match endpoint.source {
         DockerEndpointSource::EnvHost => Docker::connect_with_defaults().map_err(|e| {
             CoastError::docker(format!(
                 "Failed to connect to Docker using DOCKER_HOST='{}'. Error: {e}",
                 endpoint.host
             ))
         }),
         _ => connect_to_endpoint(&endpoint),
+    };
+
+    HostDockerProbe {
+        endpoint: Some(endpoint),
+        docker,
     }
 }
 
@@ -394,4 +426,22 @@ mod tests {
 
         assert!(error.to_string().contains("Docker context 'missing'"));
     }
+
+    #[test]
+    fn probe_captures_endpoint_on_connection_failure() {
+        let temp = TempDir::new().unwrap();
+        write_json(
+            &temp.path().join("contexts/meta/hash/meta.json"),
+            r#"{"Name":"orbstack","Endpoints":{"docker":{"Host":"unix:///tmp/does-not-exist.sock"}}}"#,
+        );
+
+        let probe = probe_host_docker_with(
+            Some(temp.path().to_path_buf()),
+            None,
+            Some("orbstack".to_string()),
+        );
+
+        assert!(probe.endpoint.is_some());
+        assert!(probe.docker.is_err());
+    }
 }