Repository navigation
Description
Part of #5200.
User Story
As an OpenShell Maintainer I want the desktop drivers to exist in their own repository so that their ownership and maintenance can be considered separately to core OpenShell. That requires the gateway to run them as separate processes it launches.
Problem Statement
The gateway compiles Docker and Podman in-process behind the default in-tree-compute-drivers feature and registers them through in-process factories. The VM driver is already a gateway-launched subprocess, but through VM-specific code in crates/openshell-gateway/src/vm.rs. There is no generic way to launch and configure an external driver, and operator-managed external drivers cannot use features such as additional CA trust.
Impact / Why This Matters
Core cannot build or release without the Docker and Podman crates, and the desktop drivers cannot move. See #5200.
Proposed Design
The gateway discovers a driver binary, writes a versioned startup document, launches the process with --config <path>, and talks to it over the existing ComputeDriver gRPC contract on a Unix socket. Driver names, auto-detect order, and driver_config tables are unchanged. The driver validates its own config.
Sub-issues:
- feat: pass launched drivers a versioned startup document #5385 Startup document
- feat: launch external compute drivers from a generic launcher #5386 Launcher
- feat: add probe, preflight, capability fields, and driver selection for launched drivers #5387
probe,preflight, capability fields, and driver selection - refactor: launch the VM driver through the generic launcher #5388 Migrate the VM driver to the launcher
Acceptance Criteria
- The VM driver passes its existing e2e, including
vm-additional-ca-e2e, with no VM-specific gateway code. - All sub-issues are complete.
Alternatives Considered
- A gateway binary built by
desktopthat links core's server crates and registers drivers in-process. Avoids a launcher, but makes the Rust factory trait a public API and produces two gateway binaries. - Keep drivers linked and delegate ownership with CODEOWNERS. Least work, but everyone still shares one repository and release machinery.
Agent Investigation
- The gateway can reach a driver three ways today: linked in-process (Docker, Podman, Kubernetes), a gateway-managed subprocess (VM,
ManagedDriverProcess), and an operator-managed external driver.
Activity
[-]feat: run compute drivers as launched external processes[/-][+]feat: run compute drivers as launched child processes[/+]elezar commentedon Nov 20, 2026
Recording consequences of moving Podman to the launcher (work on #5385).
The gateway no longer links
openshell-driver-podman. Auto-detection runsopenshell-driver-podman probeinstead of the in-processis_available, and the Podman driver runs only as a launched process. The gateway still has thecompute-driver-podmanfeature, which now gates the launcher path and not the driver crate. Because Podman is no longer in the gateway process, I also dropped its in-process tracing registration (with_in_process_tracing), as VM already does. The launched driver sets up its own tracing from the telemetry settings in the startup document.probetakes no startup document. It reports{"available": bool, "reason"?: string}and reads only the process environment, which is allis_availableread. This differs from the #5387 design, which hasprobetake the document. We can add the document later if a driver needs config to decide availability.Consequences until
preflightexists (adding Podman to the VM note on #5387):validate_configis removed from the Podman factory, andsupports_config_preflightreturnsfalse, soopenshell-gateway config preflightrejects a configuration that selects Podman. Packaged installs run it asExecStartPre.openshell-driver-podmanbinary beside the gateway or in a libexec path. Packaging does not ship it yet.crates/openshell-gateway/tests/config_preflight.rsare ignored untilpreflightreturns that check.