fix(gateway): keep vm driver opt-in (#1375)

Author: drew

crates/openshell-server/src/lib.rs

@@ -699,12 +699,16 @@ async fn build_compute_runtime(
 
 fn configured_compute_driver(config: &Config) -> Result<ComputeDriverKind> {
     match config.compute_drivers.as_slice() {
-        [] => openshell_core::config::detect_driver().ok_or_else(|| {
-            Error::config(
+        [] => match openshell_core::config::detect_driver() {
+            Some(ComputeDriverKind::Vm) => Err(Error::config(
+                "vm compute driver is opt-in only; set --drivers vm or OPENSHELL_DRIVERS=vm",
+            )),
+            Some(driver) => Ok(driver),
+            None => Err(Error::config(
                 "no compute driver configured and auto-detection found no suitable driver; \
                 set --drivers or OPENSHELL_DRIVERS to kubernetes, podman, docker, or vm",
-            )
-        }),
+            )),
+        },
         [
             driver @ (ComputeDriverKind::Kubernetes
             | ComputeDriverKind::Vm
@@ -789,7 +793,7 @@ mod tests {
         // depending on the environment. This test verifies the auto-detection path
         // is taken rather than immediately returning an error.
         let result = configured_compute_driver(&config);
-        // Either we get a detected driver or an error about none being detected
+        // Either we get a detected driver or an error about none being detected.
         match result {
             Ok(driver) => {
                 assert!(
@@ -805,7 +809,7 @@ mod tests {
             Err(e) => {
                 assert!(
                     e.to_string()
-                        .contains("no compute driver configured and none detected"),
+                        .contains("auto-detection found no suitable driver"),
                     "unexpected error: {e}"
                 );
             }

docs/reference/sandbox-compute-drivers.mdx

@@ -75,6 +75,18 @@ The gateway uses the VM compute driver to create VM-backed sandboxes. MicroVM re
 
 For maintainer-level implementation details, refer to the [VM driver README](https://github.com/NVIDIA/OpenShell/blob/main/crates/openshell-driver-vm/README.md).
 
+### Enable the VM Driver
+
+The VM driver is opt-in. Release packages can install `openshell-driver-vm`, but the gateway does not select it unless you configure the driver explicitly.
+
+For a one-off gateway process, pass `--drivers vm`:
+
+```shell
+openshell-gateway --drivers vm
+```
+
+For a service, set `OPENSHELL_DRIVERS=vm` in the service environment file and restart the service. Homebrew creates `$(brew --prefix)/var/openshell/gateway.env` with a commented `OPENSHELL_DRIVERS=vm` entry. Debian and RPM user services read `~/.config/openshell/gateway.env`.
+
 | Option | Environment variable | Description |
 |---|---|---|
 | `--drivers vm` | `OPENSHELL_DRIVERS=vm` | Select the VM compute driver. VM is never auto-detected. |

python/openshell/release_formula_test.py

@@ -51,7 +51,8 @@ def test_generate_homebrew_formula_uses_tagged_macos_driver_asset_without_defaul
         "v0.0.10/openshell-driver-vm-aarch64-apple-darwin.tar.gz"
     ) in formula
     assert 'sha256 "' + "b" * 64 + '"' in formula
-    assert "OPENSHELL_DRIVERS" not in formula
+    assert "OPENSHELL_DRIVERS:" not in formula
+    assert "#OPENSHELL_DRIVERS=vm" in formula
     assert 'OPENSHELL_DRIVER_DIR: "#{opt_libexec}"' in formula
     assert (
         'OPENSHELL_DOCKER_SUPERVISOR_IMAGE: "ghcr.io/nvidia/openshell/supervisor:0.0.10"'
@@ -61,6 +62,8 @@ def test_generate_homebrew_formula_uses_tagged_macos_driver_asset_without_defaul
         'docker_tls_dir="${OPENSHELL_DOCKER_TLS_DIR:-${HOME}/.local/state/openshell/homebrew/tls}"'
     ) in formula
     assert 'export OPENSHELL_DOCKER_TLS_CA="${docker_tls_dir}/ca.crt"' in formula
+    assert 'gateway_env="#{var}/openshell/gateway.env"' in formula
+    assert '. "${gateway_env}"' in formula
     assert 'OPENSHELL_DOCKER_TLS_CA: "#{var}/openshell/tls/ca.crt"' not in formula
     assert "entitlements.atomic_write" in formula
     assert "brew services restart openshell" in formula

tasks/scripts/release.py

@@ -300,6 +300,13 @@ def install
       export OPENSHELL_DOCKER_TLS_CERT="${{docker_tls_dir}}/client/tls.crt"
       export OPENSHELL_DOCKER_TLS_KEY="${{docker_tls_dir}}/client/tls.key"
 
+      gateway_env="#{{var}}/openshell/gateway.env"
+      if [ -f "${{gateway_env}}" ]; then
+        set -a
+        . "${{gateway_env}}"
+        set +a
+      fi
+
       exec "#{{opt_bin}}/openshell-gateway"
     SH
     chmod 0755, libexec/"openshell-gateway-homebrew-service"
@@ -311,6 +318,25 @@ def post_install
     (var/"log/openshell").mkpath
     system bin/"openshell-gateway", "generate-certs", "--output-dir", var/"openshell/tls", "--server-san", "host.openshell.internal"
 
+    gateway_env = var/"openshell/gateway.env"
+    unless gateway_env.exist?
+      gateway_env.atomic_write <<~ENV
+        # OpenShell Gateway Environment Configuration
+        # Edit freely; this file is not overwritten.
+        #
+        # Uncomment to force the VM compute driver. Leaving this unset keeps
+        # normal Podman/Docker/Kubernetes auto-detection.
+        #OPENSHELL_DRIVERS=vm
+
+        # VM driver paths configured by the Homebrew service.
+        #OPENSHELL_VM_DRIVER_STATE_DIR=#{{var}}/openshell/vm-driver
+        #OPENSHELL_VM_TLS_CA=#{{var}}/openshell/tls/ca.crt
+        #OPENSHELL_VM_TLS_CERT=#{{var}}/openshell/tls/client/tls.crt
+        #OPENSHELL_VM_TLS_KEY=#{{var}}/openshell/tls/client/tls.key
+      ENV
+      chmod 0600, gateway_env
+    end
+
     entitlements = var/"openshell/openshell-driver-vm.entitlements.plist"
     entitlements.atomic_write <<~XML
       <?xml version="1.0" encoding="UTF-8"?>