feat(install-vm): install gateway + vm driver, add --driver-dir resolution (#887)

Author: drew

architecture/gateway.md

@@ -99,7 +99,7 @@ The gateway boots in `main()` (`crates/openshell-server/src/main.rs`) and procee
    1. Connect to the persistence store (`Store::connect`), which auto-detects SQLite vs Postgres from the URL prefix and runs migrations.
    2. Create `ComputeRuntime` with a `ComputeDriver` implementation selected by `OPENSHELL_DRIVERS`:
       - `kubernetes` wraps `KubernetesComputeDriver` in `ComputeDriverService`, so the gateway uses the `openshell.compute.v1.ComputeDriver` RPC surface even without transport.
-      - `vm` spawns the sibling `openshell-driver-vm` binary as a local compute-driver process, connects to it over a Unix domain socket, and keeps the libkrun/rootfs runtime out of the gateway binary.
+      - `vm` spawns the standalone `openshell-driver-vm` binary as a local compute-driver process, resolves it from `--driver-dir`, conventional libexec install paths, or a sibling of the gateway binary, connects to it over a Unix domain socket, and keeps the libkrun/rootfs runtime out of the gateway binary.
    3. Build `ServerState` (shared via `Arc<ServerState>` across all handlers).
    4. **Spawn background tasks**:
       - `ComputeRuntime::spawn_watchers` -- consumes the compute-driver watch stream, republishes platform events, and runs a periodic `ListSandboxes` snapshot reconcile so the store-backed public sandbox reads stay aligned with the compute driver.
@@ -128,7 +128,7 @@ All configuration is via CLI flags with environment variable fallbacks. The `--d
 | `--grpc-endpoint` | `OPENSHELL_GRPC_ENDPOINT` | None | gRPC endpoint reachable from within the cluster (for sandbox callbacks) |
 | `--drivers` | `OPENSHELL_DRIVERS` | `kubernetes` | Compute backend to use. Current options are `kubernetes` and `vm`. |
 | `--vm-driver-state-dir` | `OPENSHELL_VM_DRIVER_STATE_DIR` | `target/openshell-vm-driver` | Host directory for VM sandbox rootfs, console logs, and runtime state |
-| `--vm-compute-driver-bin` | `OPENSHELL_VM_COMPUTE_DRIVER_BIN` | sibling `openshell-driver-vm` binary | Local VM compute-driver process spawned by the gateway |
+| `--driver-dir` | `OPENSHELL_DRIVER_DIR` | unset | Override directory for `openshell-driver-vm`. When unset, the gateway searches `~/.local/libexec/openshell`, `/usr/local/libexec/openshell`, `/usr/local/libexec`, then a sibling binary. |
 | `--vm-krun-log-level` | `OPENSHELL_VM_KRUN_LOG_LEVEL` | `1` | libkrun log level for VM helper processes |
 | `--vm-driver-vcpus` | `OPENSHELL_VM_DRIVER_VCPUS` | `2` | Default vCPU count for VM sandboxes |
 | `--vm-driver-mem-mib` | `OPENSHELL_VM_DRIVER_MEM_MIB` | `2048` | Default memory allocation for VM sandboxes in MiB |

crates/openshell-driver-vm/README.md

@@ -90,7 +90,7 @@ target/debug/openshell-gateway \
   --vm-driver-state-dir $PWD/target/openshell-vm-driver-dev
 ```
 
-The gateway discovers `openshell-driver-vm` as a sibling of its own binary. Pass `--vm-compute-driver-bin /path/to/openshell-driver-vm` (or set `OPENSHELL_VM_COMPUTE_DRIVER_BIN`) to override.
+The gateway resolves `openshell-driver-vm` in this order: `--driver-dir`, conventional install locations (`~/.local/libexec/openshell`, `/usr/local/libexec/openshell`, `/usr/local/libexec`), then a sibling of the gateway binary.
 
 ## Flags
 
@@ -99,7 +99,7 @@ The gateway discovers `openshell-driver-vm` as a sibling of its own binary. Pass
 | `--drivers vm` | `OPENSHELL_DRIVERS` | `kubernetes` | Select the VM compute driver. |
 | `--grpc-endpoint URL` | `OPENSHELL_GRPC_ENDPOINT` | — | Required. URL the sandbox guest calls back to. Use a host alias that resolves to the gateway's host from inside the VM (gvproxy answers `host.containers.internal` and `host.openshell.internal` to `192.168.127.1`). |
 | `--vm-driver-state-dir DIR` | `OPENSHELL_VM_DRIVER_STATE_DIR` | `target/openshell-vm-driver` | Per-sandbox rootfs, console logs, and the `compute-driver.sock` UDS. |
-| `--vm-compute-driver-bin PATH` | `OPENSHELL_VM_COMPUTE_DRIVER_BIN` | sibling of gateway binary | Override the driver binary path. |
+| `--driver-dir DIR` | `OPENSHELL_DRIVER_DIR` | unset | Override the directory searched for `openshell-driver-vm`. |
 | `--vm-driver-vcpus N` | `OPENSHELL_VM_DRIVER_VCPUS` | `2` | vCPUs per sandbox. |
 | `--vm-driver-mem-mib N` | `OPENSHELL_VM_DRIVER_MEM_MIB` | `2048` | Memory per sandbox, in MiB. |
 | `--vm-krun-log-level N` | `OPENSHELL_VM_KRUN_LOG_LEVEL` | `1` | libkrun verbosity (0–5). |

crates/openshell-driver-vm/start.sh

@@ -57,7 +57,6 @@ export OPENSHELL_SSH_GATEWAY_HOST="${OPENSHELL_SSH_GATEWAY_HOST:-127.0.0.1}"
 export OPENSHELL_SSH_GATEWAY_PORT="${OPENSHELL_SSH_GATEWAY_PORT:-${SERVER_PORT}}"
 export OPENSHELL_SSH_HANDSHAKE_SECRET="${OPENSHELL_SSH_HANDSHAKE_SECRET:-dev-vm-driver-secret}"
 export OPENSHELL_VM_DRIVER_STATE_DIR="${STATE_DIR}"
-export OPENSHELL_VM_COMPUTE_DRIVER_BIN="${OPENSHELL_VM_COMPUTE_DRIVER_BIN:-${ROOT}/target/debug/openshell-driver-vm}"
 
 echo "==> Starting OpenShell server with VM compute driver"
 exec "${ROOT}/target/debug/openshell-gateway"

crates/openshell-server/src/cli.rs

@@ -121,9 +121,13 @@ struct Args {
     )]
     vm_driver_state_dir: PathBuf,
 
-    /// VM compute-driver binary spawned by the gateway.
-    #[arg(long, env = "OPENSHELL_VM_COMPUTE_DRIVER_BIN")]
-    vm_compute_driver_bin: Option<PathBuf>,
+    /// Directory searched for compute-driver binaries (e.g.
+    /// `openshell-driver-vm`) when an explicit binary override isn't
+    /// configured. When unset, the gateway searches
+    /// `$HOME/.local/libexec/openshell`, `/usr/local/libexec/openshell`,
+    /// `/usr/local/libexec`, then a sibling of the gateway binary.
+    #[arg(long, env = "OPENSHELL_DRIVER_DIR")]
+    driver_dir: Option<PathBuf>,
 
     /// libkrun log level used by the VM helper.
     #[arg(
@@ -262,7 +266,7 @@ async fn run_from_args(args: Args) -> Result<()> {
 
     let vm_config = VmComputeConfig {
         state_dir: args.vm_driver_state_dir,
-        compute_driver_bin: args.vm_compute_driver_bin,
+        driver_dir: args.driver_dir,
         krun_log_level: args.vm_krun_log_level,
         vcpus: args.vm_vcpus,
         mem_mib: args.vm_mem_mib,

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

@@ -51,15 +51,17 @@ use tonic::transport::Endpoint;
 #[cfg(unix)]
 use tower::service_fn;
 
+const DRIVER_BIN_NAME: &str = "openshell-driver-vm";
+
 /// Configuration for launching and talking to the VM compute driver.
 #[derive(Debug, Clone)]
 pub struct VmComputeConfig {
     /// Working directory for VM driver sandbox state.
     pub state_dir: PathBuf,
 
-    /// Optional override for the `openshell-driver-vm` binary path.
-    /// When `None`, the gateway resolves a sibling of its own executable.
-    pub compute_driver_bin: Option<PathBuf>,
+    /// Directory to search for compute-driver binaries before the gateway
+    /// falls back to its conventional install paths and sibling binary.
+    pub driver_dir: Option<PathBuf>,
 
     /// libkrun log level used by the VM driver helper.
     pub krun_log_level: u32,
@@ -104,13 +106,24 @@ impl VmComputeConfig {
     pub const fn default_mem_mib() -> u32 {
         2048
     }
+
+    #[must_use]
+    fn default_driver_search_dirs(home: Option<PathBuf>) -> Vec<PathBuf> {
+        let mut dirs = Vec::new();
+        if let Some(home) = home {
+            dirs.push(home.join(".local").join("libexec").join("openshell"));
+        }
+        push_unique_path(&mut dirs, PathBuf::from("/usr/local/libexec/openshell"));
+        push_unique_path(&mut dirs, PathBuf::from("/usr/local/libexec"));
+        dirs
+    }
 }
 
 impl Default for VmComputeConfig {
     fn default() -> Self {
         Self {
             state_dir: Self::default_state_dir(),
-            compute_driver_bin: None,
+            driver_dir: None,
             krun_log_level: Self::default_krun_log_level(),
             vcpus: Self::default_vcpus(),
             mem_mib: Self::default_mem_mib(),
@@ -129,31 +142,66 @@ pub(crate) struct VmGuestTlsPaths {
     pub(crate) key: PathBuf,
 }
 
-/// Resolve the `openshell-driver-vm` binary path, falling back to a sibling
-/// of the gateway's own executable when an override is not supplied.
+/// Resolve the `openshell-driver-vm` binary path.
+///
+/// Resolution order:
+/// 1. `{driver_dir}/openshell-driver-vm`, where `driver_dir` comes from
+///    `--driver-dir` / `OPENSHELL_DRIVER_DIR`.
+/// 2. Conventional install directories:
+///    `~/.local/libexec/openshell`, `/usr/local/libexec/openshell`,
+///    `/usr/local/libexec`.
+/// 3. Sibling of the gateway's own executable (last-resort fallback so
+///    local development builds still work out of the box).
 pub(crate) fn resolve_compute_driver_bin(vm_config: &VmComputeConfig) -> Result<PathBuf> {
-    let path = if let Some(path) = vm_config.compute_driver_bin.clone() {
-        path
-    } else {
-        let current_exe = std::env::current_exe()
-            .map_err(|e| Error::config(format!("failed to resolve current executable: {e}")))?;
-        let Some(parent) = current_exe.parent() else {
-            return Err(Error::config(format!(
-                "current executable '{}' has no parent directory",
-                current_exe.display()
-            )));
-        };
-        parent.join("openshell-driver-vm")
-    };
+    let mut searched: Vec<PathBuf> = Vec::new();
+
+    // 1. Configured driver directory, or the conventional install locations
+    // when no explicit override is configured.
+    for dir in resolve_driver_search_dirs(vm_config) {
+        let candidate = dir.join(DRIVER_BIN_NAME);
+        if candidate.is_file() {
+            return Ok(candidate);
+        }
+        push_unique_path(&mut searched, candidate);
+    }
 
-    if !path.is_file() {
+    // 2. Sibling-of-gateway fallback.
+    let current_exe = std::env::current_exe()
+        .map_err(|e| Error::config(format!("failed to resolve current executable: {e}")))?;
+    let Some(parent) = current_exe.parent() else {
         return Err(Error::config(format!(
-            "vm compute driver binary '{}' does not exist; set --vm-compute-driver-bin or OPENSHELL_VM_COMPUTE_DRIVER_BIN",
-            path.display()
+            "current executable '{}' has no parent directory",
+            current_exe.display()
         )));
+    };
+    let sibling = parent.join(DRIVER_BIN_NAME);
+    if sibling.is_file() {
+        return Ok(sibling);
+    }
+    push_unique_path(&mut searched, sibling);
+
+    let searched_display = searched
+        .iter()
+        .map(|p| format!("'{}'", p.display()))
+        .collect::<Vec<_>>()
+        .join(", ");
+    Err(Error::config(format!(
+        "vm compute driver binary not found (searched {searched_display}); install it under --driver-dir / OPENSHELL_DRIVER_DIR, a conventional libexec path such as ~/.local/libexec/openshell or /usr/local/libexec{{,/openshell}}, or place it next to the gateway binary"
+    )))
+}
+
+fn resolve_driver_search_dirs(vm_config: &VmComputeConfig) -> Vec<PathBuf> {
+    if let Some(dir) = vm_config.driver_dir.clone() {
+        vec![dir]
+    } else {
+        VmComputeConfig::default_driver_search_dirs(std::env::var_os("HOME").map(PathBuf::from))
     }
+}
 
-    Ok(path)
+fn push_unique_path(paths: &mut Vec<PathBuf>, path: PathBuf) {
+    if !paths.iter().any(|existing| existing == &path) {
+        paths.push(path);
+    }
 }
 
 /// Path of the Unix domain socket the driver will listen on.
@@ -353,10 +401,56 @@ async fn connect_compute_driver(socket_path: &std::path::Path) -> Result<Channel
 
 #[cfg(all(test, unix))]
 mod tests {
-    use super::{VmComputeConfig, compute_driver_guest_tls_paths};
+    use super::{
+        VmComputeConfig, compute_driver_guest_tls_paths, resolve_compute_driver_bin,
+        resolve_driver_search_dirs,
+    };
     use openshell_core::{Config, TlsConfig};
+    use std::os::unix::fs::PermissionsExt;
+    use std::path::PathBuf;
     use tempfile::tempdir;
 
+    #[test]
+    fn resolve_driver_bin_uses_driver_dir_when_binary_present() {
+        let dir = tempdir().unwrap();
+        let bin = dir.path().join("openshell-driver-vm");
+        std::fs::write(&bin, "#!/bin/sh\n").unwrap();
+        std::fs::set_permissions(&bin, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+        let vm_config = VmComputeConfig {
+            driver_dir: Some(dir.path().to_path_buf()),
+            ..Default::default()
+        };
+        assert_eq!(resolve_compute_driver_bin(&vm_config).unwrap(), bin);
+    }
+
+    #[test]
+    fn resolve_driver_bin_error_mentions_driver_dir_hint() {
+        let dir = tempdir().unwrap(); // empty — no driver binary present
+
+        let vm_config = VmComputeConfig {
+            driver_dir: Some(dir.path().to_path_buf()),
+            ..Default::default()
+        };
+        let err = resolve_compute_driver_bin(&vm_config)
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("--driver-dir"));
+        assert!(err.contains("OPENSHELL_DRIVER_DIR"));
+        assert!(err.contains("openshell-driver-vm"));
+    }
+
+    #[test]
+    fn resolve_driver_search_dirs_include_usr_local_libexec_fallbacks() {
+        let dirs = resolve_driver_search_dirs(&VmComputeConfig {
+            driver_dir: None,
+            ..Default::default()
+        });
+
+        assert!(dirs.contains(&PathBuf::from("/usr/local/libexec/openshell")));
+        assert!(dirs.contains(&PathBuf::from("/usr/local/libexec")));
+    }
+
     #[test]
     fn vm_compute_driver_tls_requires_explicit_guest_bundle() {
         let dir = tempdir().unwrap();