fix(docker): reach a WSL 2 gateway through Docker Desktop's host alias

The Docker driver defaulted the supervisor's gateway endpoint to
127.0.0.1. When the gateway runs inside a WSL 2 distribution and the
daemon is Docker Desktop, the host-networked supervisor runs in Docker
Desktop's VM, whose loopback is not the distribution's, so every
sandbox failed with ControlSupervisorStartFailed.

When grpc_endpoint is unset, detect that combination from the gateway
host's kernel release and the daemon's reported operating system, and
default to host.docker.internal, which Docker Desktop routes to the
Windows host that WSL forwards the gateway's loopback listener from.
The generated server certificate already includes that name. Docker
Engine inside WSL and Docker Desktop outside WSL keep the loopback
default, and an explicit grpc_endpoint still wins.

Closes #3880

Signed-off-by: fede-kamel <fkamelhar@gmail.com>

Author: fede-kamel

crates/openshell-driver-docker/README.md

@@ -168,12 +168,19 @@ the supervisor companion. The workload never receives the sandbox JWT, gateway
 client TLS key, policy authority, or interception CA private key.
 
 When no endpoint is configured, the supervisor connects to
-`127.0.0.1:<gateway-port>`. Set `grpc_endpoint` when the gateway is not on the
-Docker daemon host. A configured HTTPS server certificate must include the
-endpoint host in its subject alternative names.
-
-The driver publishes host loopback as the backend address for
-`host.openshell.internal`. Policy DNS resolves that reserved name through the
+`127.0.0.1:<gateway-port>`. When the gateway runs inside a WSL 2 distribution
+and the daemon is Docker Desktop, the default is
+`host.docker.internal:<gateway-port>` instead: Docker Desktop's host network is
+its own VM, and WSL forwards the gateway's loopback listener to the Windows
+host that `host.docker.internal` names. Set `grpc_endpoint` when the gateway is
+not on the Docker daemon host. A configured HTTPS server certificate must
+include the endpoint host in its subject alternative names; the generated
+certificate includes `host.docker.internal`.
+
+When the endpoint is an IP address or `localhost`, the driver publishes that
+address as the backend address for `host.openshell.internal`. A named endpoint,
+including the WSL 2 Docker Desktop default, is left to Docker's name
+resolution and does not pin `host.openshell.internal`. Policy DNS resolves that reserved name through the
 mediated path, so policies can reach host services without a Docker bridge,
 container DNS alias, or another gateway listener.
 

crates/openshell-driver-docker/src/lib.rs

@@ -883,9 +883,16 @@ impl DockerComputeDriver {
         let gateway_port = gateway_bind_address.port();
         let mut docker_config = docker_config.clone();
         if docker_config.grpc_endpoint.trim().is_empty() {
+            let network = DockerSupervisorNetwork::detect(&info, gateway_host_is_wsl());
             docker_config.grpc_endpoint = default_docker_supervisor_grpc_endpoint(
                 gateway_port,
                 docker_guest_tls_configured(&docker_config),
+                network,
+            );
+            info!(
+                grpc_endpoint = %docker_config.grpc_endpoint,
+                ?network,
+                "Auto-detected Docker supervisor gRPC endpoint"
             );
         }
         Url::parse(&docker_config.grpc_endpoint).map_err(|error| {
@@ -6509,9 +6516,65 @@ fn docker_guest_tls_configured(docker_config: &DockerComputeConfig) -> bool {
         && docker_config.guest_tls_key.is_some()
 }
 
-fn default_docker_supervisor_grpc_endpoint(gateway_port: u16, tls: bool) -> String {
+/// Where the host-networked supervisor container can reach a gateway that
+/// listens on loopback.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum DockerSupervisorNetwork {
+    /// The container host network shares the gateway's loopback: Docker
+    /// Engine on the gateway host, or Docker Desktop with host networking
+    /// on the machine that runs the gateway.
+    GatewayLoopback,
+    /// The gateway runs inside a WSL 2 distribution and the daemon is Docker
+    /// Desktop. Docker Desktop's host network is its own VM, not the
+    /// distribution, so loopback does not reach the gateway. WSL forwards
+    /// the gateway's loopback listener to Windows, which Docker Desktop
+    /// exposes to containers as `host.docker.internal`.
+    WslDockerDesktop,
+}
+
+impl DockerSupervisorNetwork {
+    fn detect(info: &SystemInfo, gateway_in_wsl: bool) -> Self {
+        if gateway_in_wsl && docker_info_reports_docker_desktop(info) {
+            Self::WslDockerDesktop
+        } else {
+            Self::GatewayLoopback
+        }
+    }
+
+    fn gateway_host(self) -> &'static str {
+        match self {
+            Self::GatewayLoopback => "127.0.0.1",
+            Self::WslDockerDesktop => HOST_DOCKER_INTERNAL,
+        }
+    }
+}
+
+fn default_docker_supervisor_grpc_endpoint(
+    gateway_port: u16,
+    tls: bool,
+    network: DockerSupervisorNetwork,
+) -> String {
     let scheme = if tls { "https" } else { "http" };
-    format!("{scheme}://127.0.0.1:{gateway_port}")
+    let host = network.gateway_host();
+    format!("{scheme}://{host}:{gateway_port}")
+}
+
+fn docker_info_reports_docker_desktop(info: &SystemInfo) -> bool {
+    info.operating_system
+        .as_deref()
+        .is_some_and(|os| os.trim().eq_ignore_ascii_case("docker desktop"))
+}
+
+/// Whether the gateway process itself runs inside WSL. This is about the
+/// gateway host, not the daemon: Docker Engine installed inside a WSL
+/// distribution shares the gateway's loopback and needs no alias.
+fn gateway_host_is_wsl() -> bool {
+    std::fs::read_to_string("/proc/sys/kernel/osrelease")
+        .is_ok_and(|release| kernel_release_is_wsl(&release))
+}
+
+fn kernel_release_is_wsl(release: &str) -> bool {
+    release.to_ascii_lowercase().contains("microsoft")
 }
 
 pub(crate) fn docker_guest_tls_paths(

crates/openshell-driver-docker/src/tests.rs

@@ -2932,16 +2932,77 @@ fn docker_supervisor_leaves_named_gateway_hosts_to_dns() {
 
 #[test]
 fn docker_supervisor_defaults_to_the_primary_loopback_endpoint() {
+    let network = DockerSupervisorNetwork::GatewayLoopback;
     assert_eq!(
-        default_docker_supervisor_grpc_endpoint(17_670, false),
+        default_docker_supervisor_grpc_endpoint(17_670, false, network),
         "http://127.0.0.1:17670"
     );
     assert_eq!(
-        default_docker_supervisor_grpc_endpoint(17_670, true),
+        default_docker_supervisor_grpc_endpoint(17_670, true, network),
         "https://127.0.0.1:17670"
     );
 }
 
+#[test]
+fn docker_supervisor_reaches_wsl_gateway_through_docker_desktop_host_alias() {
+    let network = DockerSupervisorNetwork::WslDockerDesktop;
+    assert_eq!(
+        default_docker_supervisor_grpc_endpoint(17_670, true, network),
+        "https://host.docker.internal:17670"
+    );
+    // A named endpoint is resolved by Docker Desktop, not pinned by the driver.
+    assert_eq!(
+        docker_supervisor_host_aliases("https://host.docker.internal:17670"),
+        None
+    );
+}
+
+fn docker_desktop_wsl2_info() -> SystemInfo {
+    SystemInfo {
+        kernel_version: Some("6.6.87.2-microsoft-standard-WSL2".to_string()),
+        operating_system: Some("Docker Desktop".to_string()),
+        name: Some("docker-desktop".to_string()),
+        ..Default::default()
+    }
+}
+
+#[test]
+fn docker_supervisor_network_uses_host_alias_for_wsl_gateway_on_docker_desktop() {
+    assert_eq!(
+        DockerSupervisorNetwork::detect(&docker_desktop_wsl2_info(), true),
+        DockerSupervisorNetwork::WslDockerDesktop
+    );
+}
+
+#[test]
+fn docker_supervisor_network_keeps_loopback_for_docker_desktop_outside_wsl() {
+    // macOS and Windows-native gateways share Docker Desktop's host network.
+    assert_eq!(
+        DockerSupervisorNetwork::detect(&docker_desktop_wsl2_info(), false),
+        DockerSupervisorNetwork::GatewayLoopback
+    );
+}
+
+#[test]
+fn docker_supervisor_network_keeps_loopback_for_docker_engine_inside_wsl() {
+    let info = SystemInfo {
+        kernel_version: Some("6.6.87.2-microsoft-standard-WSL2".to_string()),
+        operating_system: Some("Ubuntu 24.04.4 LTS".to_string()),
+        ..Default::default()
+    };
+    assert_eq!(
+        DockerSupervisorNetwork::detect(&info, true),
+        DockerSupervisorNetwork::GatewayLoopback
+    );
+}
+
+#[test]
+fn kernel_release_detects_wsl() {
+    assert!(kernel_release_is_wsl("6.18.40.1-microsoft-standard-WSL2\n"));
+    assert!(kernel_release_is_wsl("4.4.0-19041-Microsoft"));
+    assert!(!kernel_release_is_wsl("6.8.0-60-generic"));
+}
+
 #[test]
 fn build_container_create_body_limits_writable_runtime_storage_to_supervisor_ca() {
     let create_body = build_container_create_body(&test_sandbox(), &runtime_config()).unwrap();

docs/how-it-works/gateways/configuration.mdx

@@ -911,7 +911,8 @@ image_pull_policy  = "if_not_present"
 # Value assigned to the openshell.sandbox_namespace label on sandbox containers.
 sandbox_label      = "docker-dev"
 # Optional override. When omitted, the host-networked supervisor uses the
-# gateway's primary loopback endpoint.
+# gateway's primary loopback endpoint, or host.docker.internal when the
+# gateway runs inside WSL 2 with Docker Desktop.
 grpc_endpoint      = "https://127.0.0.1:17670"
 # Workload-side runtime. Defaults to the gateway version.
 # sandbox_runtime_image = "ghcr.io/nvidia/openshell/sandbox:<version>"

docs/how-it-works/sandboxes/runtimes.mdx

@@ -94,7 +94,7 @@ socket_path = "/var/run/docker.sock"
 
 Common options in `[openshell.drivers.docker]` are `socket_path`, `grpc_endpoint`, `sandbox_runtime_image`, `supervisor_image`, `image_pull_policy`, and `sandbox_pids_limit`. When `socket_path` is unset, the driver uses the socket found by auto-detection.
 
-Docker Desktop must have host networking enabled, and it cannot use Enhanced Container Isolation. Set `grpc_endpoint` when sandboxes cannot reach the gateway on host loopback. For GPU sandboxes, configure Docker CDI before starting the gateway.
+Docker Desktop must have host networking enabled, and it cannot use Enhanced Container Isolation. When the gateway runs inside WSL 2 with Docker Desktop, the driver connects sandboxes to the gateway through `host.docker.internal` automatically. Set `grpc_endpoint` when sandboxes cannot reach the gateway on host loopback. For GPU sandboxes, configure Docker CDI before starting the gateway.
 
 ### Docker Corporate Proxy Egress