feat: add --compute-driver-socket flag and External driver variant

Add ComputeDriverKind::External that connects to a pre-existing Unix
domain socket instead of spawning a driver subprocess. This enables
out-of-process compute drivers running as sidecar containers.

Changes:
- Add External variant to ComputeDriverKind enum with parser/display
- Add --compute-driver-socket CLI flag (+ OPENSHELL_COMPUTE_DRIVER_SOCKET env)
- Add --credentials-driver-socket CLI flag (+ OPENSHELL_CREDENTIALS_DRIVER_SOCKET env)
- Add compute_driver_socket and credentials_driver_socket to Config
- Add compute::external module with UDS connection logic (retry loop)
- Wire External arm in build_compute_runtime() reusing RemoteComputeDriver
- Add tests for External variant parsing and config acceptance

Ref: rossoctl/rossoctl#1353

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Paolo Dettori <dettori@us.ibm.com>

Author: pdettori

crates/openshell-core/src/config.rs

@@ -49,6 +49,7 @@ pub enum ComputeDriverKind {
     Kubernetes,
     Vm,
     Podman,
+    External,
 }
 
 impl ComputeDriverKind {
@@ -58,6 +59,7 @@ impl ComputeDriverKind {
             Self::Kubernetes => "kubernetes",
             Self::Vm => "vm",
             Self::Podman => "podman",
+            Self::External => "external",
         }
     }
 }
@@ -76,8 +78,9 @@ impl FromStr for ComputeDriverKind {
             "kubernetes" => Ok(Self::Kubernetes),
             "vm" => Ok(Self::Vm),
             "podman" => Ok(Self::Podman),
+            "external" => Ok(Self::External),
             other => Err(format!(
-                "unsupported compute driver '{other}'. expected one of: kubernetes, vm, podman"
+                "unsupported compute driver '{other}'. expected one of: kubernetes, vm, podman, external"
             )),
         }
     }
@@ -196,6 +199,18 @@ pub struct Config {
     /// allowing them to reach services running on the Docker host.
     #[serde(default)]
     pub host_gateway_ip: String,
+
+    /// Unix domain socket path to an external compute driver.
+    /// When set with `--driver external`, the gateway connects to this
+    /// pre-existing socket instead of spawning a driver subprocess.
+    #[serde(default)]
+    pub compute_driver_socket: String,
+
+    /// Unix domain socket path to a credentials driver.
+    /// When set, the gateway delegates credential resolution to this
+    /// out-of-process driver via the `CredentialsDriver` gRPC contract.
+    #[serde(default)]
+    pub credentials_driver_socket: String,
 }
 
 /// TLS configuration.
@@ -308,6 +323,8 @@ impl Config {
             ssh_session_ttl_secs: default_ssh_session_ttl_secs(),
             client_tls_secret_name: String::new(),
             host_gateway_ip: String::new(),
+            compute_driver_socket: String::new(),
+            credentials_driver_socket: String::new(),
         }
     }
 
@@ -451,6 +468,20 @@ impl Config {
         self.oidc = Some(oidc);
         self
     }
+
+    /// Set the Unix domain socket path for an external compute driver.
+    #[must_use]
+    pub fn with_compute_driver_socket(mut self, path: impl Into<String>) -> Self {
+        self.compute_driver_socket = path.into();
+        self
+    }
+
+    /// Set the Unix domain socket path for a credentials driver.
+    #[must_use]
+    pub fn with_credentials_driver_socket(mut self, path: impl Into<String>) -> Self {
+        self.credentials_driver_socket = path.into();
+        self
+    }
 }
 
 fn default_bind_address() -> SocketAddr {
@@ -522,6 +553,14 @@ mod tests {
         );
     }
 
+    #[test]
+    fn compute_driver_kind_parses_external() {
+        assert_eq!(
+            "external".parse::<ComputeDriverKind>().unwrap(),
+            ComputeDriverKind::External
+        );
+    }
+
     #[test]
     fn compute_driver_kind_rejects_unknown_values() {
         let err = "docker".parse::<ComputeDriverKind>().unwrap_err();

crates/openshell-server/src/cli.rs

@@ -233,6 +233,18 @@ struct Args {
     /// Keycloak: "scope". Okta: "scp". Leave empty to disable scope enforcement.
     #[arg(long, env = "OPENSHELL_OIDC_SCOPES_CLAIM", default_value = "")]
     oidc_scopes_claim: String,
+
+    /// Unix domain socket path to an external compute driver.
+    /// Use with `--driver external` to delegate ComputeDriver RPCs to a
+    /// pre-existing out-of-process driver (e.g. a sidecar container).
+    #[arg(long, env = "OPENSHELL_COMPUTE_DRIVER_SOCKET")]
+    compute_driver_socket: Option<PathBuf>,
+
+    /// Unix domain socket path to a credentials driver.
+    /// When set, the gateway delegates credential resolution to this
+    /// out-of-process driver via the CredentialsDriver gRPC contract.
+    #[arg(long, env = "OPENSHELL_CREDENTIALS_DRIVER_SOCKET")]
+    credentials_driver_socket: Option<PathBuf>,
 }
 
 pub fn command() -> Command {
@@ -349,6 +361,14 @@ async fn run_from_args(args: Args) -> Result<()> {
         config = config.with_host_gateway_ip(ip);
     }
 
+    if let Some(socket) = args.compute_driver_socket {
+        config = config.with_compute_driver_socket(socket.to_string_lossy());
+    }
+
+    if let Some(socket) = args.credentials_driver_socket {
+        config = config.with_credentials_driver_socket(socket.to_string_lossy());
+    }
+
     if let Some(issuer) = args.oidc_issuer {
         config = config.with_oidc(openshell_core::OidcConfig {
             issuer,

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

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Kagenti Authors
+// SPDX-License-Identifier: Apache-2.0
+
+//! External compute driver: connect to a pre-existing Unix domain socket.
+//!
+//! Unlike the VM driver ([`super::vm`]) which spawns and manages a subprocess,
+//! the external driver assumes the socket is already listening (e.g. a sidecar
+//! container in the same pod). The gateway just connects to it.
+
+#[cfg(unix)]
+use hyper_util::rt::TokioIo;
+use openshell_core::{Error, Result};
+#[cfg(unix)]
+use std::time::Duration;
+#[cfg(unix)]
+use tokio::net::UnixStream;
+use tonic::transport::Channel;
+#[cfg(unix)]
+use tonic::transport::Endpoint;
+#[cfg(unix)]
+use tower::service_fn;
+
+/// Connect to an external compute driver at the given Unix domain socket path.
+///
+/// Retries for up to 10 seconds to allow the sidecar time to start.
+#[cfg(unix)]
+pub(crate) async fn connect(socket_path: &std::path::Path) -> Result<Channel> {
+    let mut last_error: Option<String> = None;
+    for _ in 0..100 {
+        match connect_once(socket_path).await {
+            Ok(channel) => return Ok(channel),
+            Err(err) => last_error = Some(err.to_string()),
+        }
+        tokio::time::sleep(Duration::from_millis(100)).await;
+    }
+
+    Err(Error::execution(format!(
+        "timed out waiting for external compute driver socket '{}': {}",
+        socket_path.display(),
+        last_error.unwrap_or_else(|| "unknown error".to_string())
+    )))
+}
+
+#[cfg(unix)]
+async fn connect_once(socket_path: &std::path::Path) -> Result<Channel> {
+    let socket_path = 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| {
+            Error::execution(format!(
+                "failed to connect to external compute driver socket '{}': {e}",
+                display_path.display()
+            ))
+        })
+}
+
+#[cfg(not(unix))]
+pub(crate) async fn connect(_socket_path: &std::path::Path) -> Result<Channel> {
+    Err(Error::config(
+        "the external compute driver requires unix domain socket support",
+    ))
+}

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

@@ -3,6 +3,7 @@
 
 //! Gateway-owned compute orchestration over a pluggable compute backend.
 
+pub(crate) mod external;
 pub mod vm;
 
 pub use vm::VmComputeConfig;

crates/openshell-server/src/lib.rs

@@ -408,6 +408,26 @@ async fn build_compute_runtime(
             .await
             .map_err(|e| Error::execution(format!("failed to create compute runtime: {e}")))
         }
+        ComputeDriverKind::External => {
+            if config.compute_driver_socket.is_empty() {
+                return Err(Error::config(
+                    "--compute-driver-socket is required when using the external compute driver",
+                ));
+            }
+            let socket_path = std::path::Path::new(&config.compute_driver_socket);
+            let channel = compute::external::connect(socket_path).await?;
+            ComputeRuntime::new_remote_vm(
+                channel,
+                None,
+                store,
+                sandbox_index,
+                sandbox_watch_bus,
+                tracing_log_bus,
+                supervisor_sessions,
+            )
+            .await
+            .map_err(|e| Error::execution(format!("failed to create compute runtime: {e}")))
+        }
     }
 }
 
@@ -419,7 +439,8 @@ fn configured_compute_driver(config: &Config) -> Result<ComputeDriverKind> {
         [
             driver @ (ComputeDriverKind::Kubernetes
             | ComputeDriverKind::Vm
-            | ComputeDriverKind::Podman),
+            | ComputeDriverKind::Podman
+            | ComputeDriverKind::External),
         ] => Ok(*driver),
         drivers => Err(Error::config(format!(
             "multiple compute drivers are not supported yet; configured drivers: {}",
@@ -494,4 +515,13 @@ mod tests {
             ComputeDriverKind::Vm
         );
     }
+
+    #[test]
+    fn configured_compute_driver_accepts_external() {
+        let config = Config::new(None).with_compute_drivers([ComputeDriverKind::External]);
+        assert_eq!(
+            configured_compute_driver(&config).unwrap(),
+            ComputeDriverKind::External
+        );
+    }
 }