Skip to content

feat: run compute drivers as launched child processes #5384

Open

Description

@elezar

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:

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 desktop that 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

  1. added
    retired:area:gatewayRetired; do not apply. See #5151 for item-specific migration to the current taxonomy.
    on Nov 9, 2026
  2. added
    area:driversCompute and secret drivers, host OS/architecture support, backend isolation, and lifecycle.
    topic:architectureSystem design, component boundaries, data/control flow, architectural decisions, and RFCs.
    topic:extensionsExtension APIs and integration points, consistent design, and external use cases.
    and removed
    retired:area:gatewayRetired; do not apply. See #5151 for item-specific migration to the current taxonomy.
    on Nov 15, 2026
  3. changed the title [-]feat: run compute drivers as launched external processes[/-] [+]feat: run compute drivers as launched child processes[/+] on Nov 20, 2026
  4. elezar commented on Nov 20, 2026

    @elezar
    ContributorAuthor

    Recording consequences of moving Podman to the launcher (work on #5385).

    The gateway no longer links openshell-driver-podman. Auto-detection runs openshell-driver-podman probe instead of the in-process is_available, and the Podman driver runs only as a launched process. The gateway still has the compute-driver-podman feature, 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.

    probe takes no startup document. It reports {"available": bool, "reason"?: string} and reads only the process environment, which is all is_available read. This differs from the #5387 design, which has probe take the document. We can add the document later if a driver needs config to decide availability.

    Consequences until preflight exists (adding Podman to the VM note on #5387):

    • validate_config is removed from the Podman factory, and supports_config_preflight returns false, so openshell-gateway config preflight rejects a configuration that selects Podman. Packaged installs run it as ExecStartPre.
    • Podman now needs the openshell-driver-podman binary beside the gateway or in a libexec path. Packaging does not ship it yet.
    • The VM host-tool preflight tests in crates/openshell-gateway/tests/config_preflight.rs are ignored until preflight returns that check.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:driversCompute and secret drivers, host OS/architecture support, backend isolation, and lifecycle.topic:architectureSystem design, component boundaries, data/control flow, architectural decisions, and RFCs.topic:extensionsExtension APIs and integration points, consistent design, and external use cases.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions