feat(packaging): ship openshell-driver-vm in an RPM subpackage

.github/workflows/branch-e2e.yml

@@ -216,7 +216,7 @@ jobs:
 
   build-rpm:
     name: Build RPM packages
-    needs: [pr_metadata, version, build-binaries]
+    needs: [pr_metadata, version, build-binaries, build-vm-driver]
     if: needs.pr_metadata.outputs.run_integration == 'true'
     permissions:
       actions: read

.github/workflows/build-rpm.yml

@@ -90,10 +90,16 @@ jobs:
           name: openshell-prover-${{ inputs.prover-target }}
           path: package-binaries/
 
+      - name: Download VM driver artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: openshell-driver-vm-${{ inputs.gateway-target }}
+          path: package-binaries/
+
       - name: Configure package inputs
         run: |
           set -euo pipefail
-          chmod +x package-binaries/openshell{,-gateway,-prover}
+          chmod +x package-binaries/openshell{,-gateway,-prover,-driver-vm}
           ls -lah package-binaries
 
       - name: Mark workspace safe for git
@@ -124,6 +130,19 @@ jobs:
           echo "=== Built RPMs ==="
           ls -lah artifacts/
 
+      - name: Verify installed VM driver RPM
+        run: |
+          set -euo pipefail
+          vm_rpms=(artifacts/openshell-driver-vm-[0-9]*.rpm)
+          test "${#vm_rpms[@]}" -eq 1
+          test -f "${vm_rpms[0]}"
+          rpm -qlp "${vm_rpms[0]}" | grep -Fx /usr/libexec/openshell/openshell-driver-vm
+          rpm -qpR "${vm_rpms[0]}" | grep -Fx 'e2fsprogs >= 1.43'
+          rpm -qpR "${vm_rpms[0]}" | grep -Fx "openshell-gateway = $(rpm -qp --qf '%{VERSION}-%{RELEASE}' "${vm_rpms[0]}")"
+          dnf install -y artifacts/openshell-[0-9]*.rpm artifacts/openshell-gateway-[0-9]*.rpm "${vm_rpms[0]}"
+          /usr/libexec/openshell/openshell-driver-vm --version
+          bash tasks/scripts/test-rpm-vm-install.sh
+
       - name: Upload RPM artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:

.github/workflows/release-build.yml

@@ -217,7 +217,7 @@ jobs:
 
   build-rpm:
     name: Build RPM Packages
-    needs: [compute-versions, build-binaries]
+    needs: [compute-versions, build-binaries, build-vm-driver]
     uses: ./.github/workflows/rpm-package.yml
     with:
       checkout-ref: ${{ needs.compute-versions.outputs.source_sha }}

.github/workflows/release-dev.yml

@@ -248,7 +248,7 @@ jobs:
 
   build-rpm:
     name: Build RPM Packages
-    needs: [compute-versions, build-binaries]
+    needs: [compute-versions, build-binaries, build-vm-driver]
     uses: ./.github/workflows/rpm-package.yml
     with:
       checkout-ref: ${{ github.sha }}

crates/openshell-driver-vm/README.md

@@ -327,7 +327,10 @@ auto-detection. Set `OPENSHELL_COMPUTE_DRIVER=vm` to force the VM driver.
 
 On RPM-family Linux x86_64 and aarch64 systems, `install.sh` installs the
 `openshell` and `openshell-gateway` RPM packages from the selected release tag.
-The RPM gateway package is configured for the Podman driver.
+Install the matching `openshell-driver-vm` RPM separately to use MicroVMs; it
+places the driver under `/usr/libexec/openshell` and requires `e2fsprogs`.
+The RPM gateway package remains configured for Podman until you select
+`compute_driver = "vm"` in gateway TOML.
 
 On Apple Silicon macOS, `install.sh` stages the generated `openshell.rb`
 formula from the selected release in the `nvidia/openshell` Homebrew tap.

deploy/rpm/CONFIGURATION.md

@@ -32,6 +32,36 @@ interface.
 this, the gateway auto-detects in order: Kubernetes, Podman, Docker. Pinning
 prevents unexpected driver selection if Docker is also installed on the host.
 
+### MicroVM driver
+
+On a Fedora or RHEL host with KVM, install the optional VM driver RPM:
+
+```shell
+sudo dnf install openshell-driver-vm
+```
+
+The package installs `/usr/libexec/openshell/openshell-driver-vm`, which the
+gateway searches without a `driver_dir` override. It requires the matching
+`openshell-gateway` build and `e2fsprogs` 1.43 or newer. In your existing
+`~/.config/openshell/gateway.toml`, change the gateway selector to:
+
+```toml
+[openshell.gateway]
+compute_driver = "vm"
+```
+
+Keep the other settings in that file. Check the selected VM host tools, then
+restart the service:
+
+```shell
+openshell-gateway config preflight --path ~/.config/openshell/gateway.toml
+systemctl --user restart openshell-gateway
+```
+
+The RPM default remains Podman until you select `vm`. See the [VM driver
+configuration](https://docs.nvidia.com/openshell/latest/how-it-works/gateways/configuration#microvm)
+for VM-specific settings.
+
 ### Customizing the configuration
 
 Edit `~/.config/openshell/gateway.toml` directly. The package-owned template at
@@ -319,6 +349,7 @@ For air-gapped environments:
 | Purpose | Path |
 |---------|------|
 | Gateway binary | `/usr/bin/openshell-gateway` |
+| Optional VM driver binary | `/usr/libexec/openshell/openshell-driver-vm` |
 | CLI binary | `/usr/bin/openshell` |
 | Systemd user unit | `/usr/lib/systemd/user/openshell-gateway.service` |
 | Default TOML config template (read-only) | `/usr/share/openshell-gateway/gateway.toml.default` |

deploy/rpm/QUICKSTART.md

@@ -157,7 +157,7 @@ openshell sandbox provider attach <sandbox> openai
 ## Next steps
 
 - See CONFIGURATION.md for TLS settings, environment variables, and
-  file locations.
+  file locations, including how to install and select the optional MicroVM driver.
 - See TROUBLESHOOTING.md for CLI compatibility notes, remote access,
   and common issues.
 - Run `man openshell` for the CLI reference.