feat(server): connect external compute driver via acquired UDS endpoint

Splits ComputeRuntime construction so that the gateway can dispatch to
an out-of-tree compute driver process listening on a Unix domain socket
the operator already owns, without adding a fifth `ComputeDriverKind`
variant.

* `ComputeRuntime::from_driver` now takes `Option<ComputeDriverKind>`;
  the four in-tree constructors wrap their kind in `Some(...)`. Out-of-
  tree drivers pass `None` so callers keyed off the enum skip the
  in-tree match.
* `connect_external_compute_driver` produces a tonic `Channel` over a
  pre-existing UDS path, mirroring the vm driver's connector. A
  `#[cfg(not(unix))]` stub returns the same error the vm path uses.
* `ComputeRuntime::new_remote_external` consumes the channel via the
  existing `RemoteComputeDriver` proxy and skips both shutdown cleanup
  and managed-process supervision (the operator owns the lifecycle).
* `from_driver` logs the `driver_name` advertised by `GetCapabilities`
  whenever `driver_kind` is `None`, so operators can confirm the
  gateway connected to the driver they expect.
* `build_compute_runtime` short-circuits to the external path when
  `Config.external_compute_driver_socket` is set, before consulting
  `--drivers` / auto-detect.

The four in-tree backends (Kubernetes, Vm, Docker, Podman) keep their
existing dispatch arms unchanged.

Signed-off-by: st-gr <38470677+st-gr@users.noreply.github.com>

Author: st-gr

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

@@ -35,15 +35,20 @@ use openshell_driver_kubernetes::{
 use openshell_driver_podman::{
     ComputeDriverService as PodmanDriverService, PodmanComputeConfig, PodmanComputeDriver,
 };
+use hyper_util::rt::TokioIo;
 use prost::Message;
 use std::fmt;
 use std::net::SocketAddr;
+use std::path::{Path, PathBuf};
 use std::pin::Pin;
 use std::sync::Arc;
 use std::time::Duration;
 use tokio::sync::Mutex;
-use tonic::transport::Channel;
+#[cfg(unix)]
+use tokio::net::UnixStream;
+use tonic::transport::{Channel, Endpoint};
 use tonic::{Code, Request, Status};
+use tower::service_fn;
 use tracing::{info, warn};
 
 type DriverWatchStream = Pin<Box<dyn Stream<Item = Result<WatchSandboxesEvent, Status>> + Send>>;
@@ -101,11 +106,11 @@ pub use openshell_core::ComputeDriverError as ComputeError;
 #[derive(Debug)]
 pub struct ManagedDriverProcess {
     child: std::sync::Mutex<Option<tokio::process::Child>>,
-    socket_path: std::path::PathBuf,
+    socket_path: PathBuf,
 }
 
 impl ManagedDriverProcess {
-    pub(crate) fn new(child: tokio::process::Child, socket_path: std::path::PathBuf) -> Self {
+    pub(crate) fn new(child: tokio::process::Child, socket_path: PathBuf) -> Self {
         Self {
             child: std::sync::Mutex::new(Some(child)),
             socket_path,
@@ -243,7 +248,7 @@ impl fmt::Debug for ComputeRuntime {
 impl ComputeRuntime {
     #[allow(clippy::too_many_arguments)]
     async fn from_driver(
-        driver_kind: ComputeDriverKind,
+        driver_kind: Option<ComputeDriverKind>,
         driver: SharedComputeDriver,
         shutdown_cleanup: Option<Arc<dyn ShutdownCleanup>>,
         startup_resume: Option<Arc<dyn StartupResume>>,
@@ -256,15 +261,24 @@ impl ComputeRuntime {
         _allows_loopback_endpoints: bool,
         gateway_bind_addresses: Vec<SocketAddr>,
     ) -> Result<Self, ComputeError> {
-        let default_image = driver
+        let capabilities = driver
             .get_capabilities(Request::new(GetCapabilitiesRequest {}))
             .await
             .map_err(compute_error_from_status)?
-            .into_inner()
-            .default_image;
+            .into_inner();
+        // For out-of-tree drivers (driver_kind = None), log the name the
+        // driver advertises in GetCapabilities so operators can confirm
+        // the gateway is talking to the driver they expect.
+        if driver_kind.is_none() {
+            info!(
+                driver_name = %capabilities.driver_name,
+                "External compute driver connected"
+            );
+        }
+        let default_image = capabilities.default_image;
         Ok(Self {
             driver,
-            driver_kind: Some(driver_kind),
+            driver_kind,
             shutdown_cleanup,
             startup_resume,
             _driver_process: driver_process,
@@ -308,7 +322,7 @@ impl ComputeRuntime {
         let startup_resume: Arc<dyn StartupResume> = driver.clone();
         let driver: SharedComputeDriver = driver;
         Self::from_driver(
-            ComputeDriverKind::Docker,
+            Some(ComputeDriverKind::Docker),
             driver,
             Some(shutdown_cleanup),
             Some(startup_resume),
@@ -337,7 +351,7 @@ impl ComputeRuntime {
             .map_err(|err| ComputeError::Message(err.to_string()))?;
         let driver: SharedComputeDriver = Arc::new(ComputeDriverService::new(driver));
         Self::from_driver(
-            ComputeDriverKind::Kubernetes,
+            Some(ComputeDriverKind::Kubernetes),
             driver,
             None,
             None,
@@ -364,7 +378,7 @@ impl ComputeRuntime {
     ) -> Result<Self, ComputeError> {
         let driver: SharedComputeDriver = Arc::new(RemoteComputeDriver::new(channel));
         Self::from_driver(
-            ComputeDriverKind::Vm,
+            Some(ComputeDriverKind::Vm),
             driver,
             None,
             None,
@@ -380,6 +394,39 @@ impl ComputeRuntime {
         .await
     }
 
+    /// Construct a runtime that proxies all sandbox lifecycle to an
+    /// out-of-tree compute driver listening on a pre-existing UDS endpoint.
+    ///
+    /// The driver process is operator-managed (not spawned by the gateway),
+    /// so no [`ManagedDriverProcess`] handle is attached. The advertised
+    /// `driver_name` from `GetCapabilities` is logged for diagnostics by
+    /// [`Self::from_driver`].
+    pub(crate) async fn new_remote_external(
+        channel: Channel,
+        store: Arc<Store>,
+        sandbox_index: SandboxIndex,
+        sandbox_watch_bus: SandboxWatchBus,
+        tracing_log_bus: TracingLogBus,
+        supervisor_sessions: Arc<SupervisorSessionRegistry>,
+    ) -> Result<Self, ComputeError> {
+        let driver: SharedComputeDriver = Arc::new(RemoteComputeDriver::new(channel));
+        Self::from_driver(
+            None,
+            driver,
+            None,
+            None,
+            None,
+            store,
+            sandbox_index,
+            sandbox_watch_bus,
+            tracing_log_bus,
+            supervisor_sessions,
+            true,
+            Vec::new(),
+        )
+        .await
+    }
+
     pub async fn new_podman(
         config: PodmanComputeConfig,
         store: Arc<Store>,
@@ -393,7 +440,7 @@ impl ComputeRuntime {
             .map_err(|err| ComputeError::Message(err.to_string()))?;
         let driver: SharedComputeDriver = Arc::new(PodmanDriverService::new(driver));
         Self::from_driver(
-            ComputeDriverKind::Podman,
+            Some(ComputeDriverKind::Podman),
             driver,
             None,
             None,
@@ -1250,6 +1297,38 @@ impl ComputeRuntime {
     }
 }
 
+/// Connect to an out-of-tree compute driver that is already listening on
+/// `socket_path` and return a tonic `Channel` speaking `compute_driver.proto`.
+///
+/// The gateway does not spawn or own the driver process — the operator is
+/// responsible for placing the driver alongside the gateway and granting the
+/// gateway uid read/write on the socket. The host portion of the URL is
+/// ignored because the connector resolves to the UDS rather than DNS.
+#[cfg(unix)]
+pub async fn connect_external_compute_driver(socket_path: &Path) -> Result<Channel, ComputeError> {
+    let socket_path: PathBuf = socket_path.to_path_buf();
+    let display_path = socket_path.clone();
+    Endpoint::from_static("http://[::]:50051")
+        .connect_with_connector(service_fn(move |_: tonic::transport::Uri| {
+            let socket_path = socket_path.clone();
+            async move { UnixStream::connect(socket_path).await.map(TokioIo::new) }
+        }))
+        .await
+        .map_err(|e| {
+            ComputeError::Message(format!(
+                "failed to connect to external compute driver socket '{}': {e}",
+                display_path.display()
+            ))
+        })
+}
+
+#[cfg(not(unix))]
+pub async fn connect_external_compute_driver(_socket_path: &Path) -> Result<Channel, ComputeError> {
+    Err(ComputeError::Message(
+        "the external compute driver requires unix domain socket support".to_string(),
+    ))
+}
+
 fn driver_sandbox_from_public(
     sandbox: &Sandbox,
     driver_kind: Option<ComputeDriverKind>,

crates/openshell-server/src/lib.rs

@@ -703,6 +703,26 @@ async fn build_compute_runtime(
     tracing_log_bus: TracingLogBus,
     supervisor_sessions: Arc<supervisor_session::SupervisorSessionRegistry>,
 ) -> Result<ComputeRuntime> {
+    if let Some(socket_path) = config.external_compute_driver_socket.as_deref() {
+        info!(
+            socket = %socket_path.display(),
+            "Using external compute driver"
+        );
+        let channel = compute::connect_external_compute_driver(socket_path)
+            .await
+            .map_err(|e| Error::execution(format!("failed to create compute runtime: {e}")))?;
+        return ComputeRuntime::new_remote_external(
+            channel,
+            store,
+            sandbox_index,
+            sandbox_watch_bus,
+            tracing_log_bus,
+            supervisor_sessions,
+        )
+        .await
+        .map_err(|e| Error::execution(format!("failed to create compute runtime: {e}")));
+    }
+
     let driver = configured_compute_driver(config)?;
     info!(driver = %driver, "Using compute driver");
     warn_if_kubernetes_sandbox_jwt_expiry_disabled(config, driver);