Skip to content

feat: pass launched drivers a versioned startup document #5385

Open

Description

@elezar

Part of #5200 and #5384.

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. Launched drivers need a stable way to receive configuration.

Problem Statement

The gateway starts the VM driver with one command-line flag per setting, built by the append_*_args functions in vm.rs. That does not scale to more drivers, puts settings in the process list, and has no version to refuse on mismatch.

Impact / Why This Matters

Every launched driver needs the gateway's context and its own config. Without a versioned document, a gateway and a driver from different releases cannot detect that they disagree.

Proposed Design

The gateway writes one document with mode 0600 into a private 0700 directory and passes --config <path>. It has two parts:

  • Gateway context, with a fixed schema defined in the driver SDK and a schema version: bind address, log level, TLS CA, telemetry endpoints, upstream proxy, and the network trust bundle.
  • Driver config, the driver_config table from gateway configuration, opaque to the gateway.

The network trust bundle is passed as the staged artifact's path, digest, and certificate count, as the VM driver receives it today. The driver verifies and snapshots the file. The PEM bytes do not cross the process boundary.

Acceptance Criteria

  • The document and its schema version are defined in openshell-driver-sdk.
  • The VM append_*_args flags become fields of the document.
  • The document schema is covered by breaking-change detection, as the proto is.
  • A driver refuses a document whose schema version it does not accept, with an error naming both versions.
  • The document is created with mode 0600 in a 0700 directory and contains no secrets that would otherwise appear in argv.

Alternatives Considered

  • Keep one flag per setting. Simple for one driver, but argv grows with each setting and secrets can appear in the process list.
  • Environment variables. Also visible to other processes in some environments, and unversioned.

Agent Investigation

  • The trust bundle is staged by the gateway as a 0444 file in a 0700 directory (crates/openshell-server/src/network_trust.rs). The VM driver receives its path, digest, and certificate count as flags (vm.rs) and reads and verifies the file itself.
  • The artifact must be readable by the driver, which holds for host-local drivers.

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:apiPublic APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards.
    topic:extensionsExtension APIs and integration points, consistent design, and external use cases.
    topic:securityVulnerability management, security analysis/auditing, bypass detection, and abuse prevention.
    and removed
    retired:area:gatewayRetired; do not apply. See #5151 for item-specific migration to the current taxonomy.
    on Nov 15, 2026
  3. elezar commented on Nov 20, 2026

    @elezar
    ContributorAuthor

    Design note: startup document

    Format and location

    A single TOML document, schema_version plus two tables, defined in a new crate crates/openshell-driver-sdk. The crate is created here and #5383 extends it later, so the startup document does not wait for the SDK carve-out. It depends only on serde and toml, not on openshell-core, so the carve-out and consumption from another repository stay possible.

    schema_version = 1
    
    [gateway]
    bind_socket = "..."
    expected_peer_pid = 1234
    log_level = "info"
    gateway_name = "..."
    # admission, tls_ca, telemetry, upstream_proxy, network_trust
    
    [driver_config]
    # the operator's driver_config table, passed through unchanged
    • gateway has a fixed schema with deny_unknown_fields. Optional fields are omitted when unset, since TOML has no null.
    • driver_config is a toml::Table, opaque to the gateway. The driver deserializes it into its own type, as the in-process factories do today (driver_config_from_context), so there is no TOML-to-JSON conversion.
    • network_trust carries the staged artifact's path, digest, and certificate count only. The PEM bytes do not cross the process boundary.
    • admission mirrors DriverAdmissionConfig as plain SDK types, since the SDK cannot depend on openshell-core.
    • A driver refuses a document whose schema_version it does not accept: "startup document schema version X, driver supports Y". Parsing is bounded in size.

    Types are defined in the SDK, not shared with the gateway

    The SDK defines every document type itself and imports nothing from openshell-server or openshell-core. This keeps operator-facing config changes from becoming schema changes, and lets drivers in other repositories use the SDK without core. The cost is a second definition of some data, such as the OTLP export endpoints and protocols, the upstream proxy settings, and admission. The gateway converts its resolved config into the document in one place, and a test builds a document from a fully populated gateway config so a field added on one side and missed on the other fails.

    Mapping from the VM flags

    append_*_args in crates/openshell-gateway/src/vm.rs becomes document construction:

    Flags today Document
    --bind-socket, --expected-peer-pid, --log-level, --gateway-name gateway
    --admission-config-json gateway.admission
    OTLP endpoint, protocol, CA, cert, and key flags gateway.telemetry
    --upstream-proxy* gateway.upstream_proxy
    --additional-ca-bundle, -digest, -certificate-count gateway.network_trust
    --grpc-endpoint, --state-dir, images, vcpus, memory, krun log level, sandbox uid and gid, rootfs tar settings, guest TLS CA, SPIFFE, bind mounts driver_config

    OTLP headers stay in OTEL_EXPORTER_OTLP_TRACES_HEADERS, as today. They are a secret that is already kept out of argv, and the document must contain no secrets that would otherwise appear in argv.

    Out of scope for this issue

    Creating the 0600 file in a 0700 directory and passing --config <path> belongs to the launcher (#5386). #5385 provides the types, serialization, and the bounded, version-checked parse. Moving the VM driver onto the document is #5388.

    Breaking-change detection

    The acceptance criterion asks for detection "as the proto is". I propose deferring it: generate a JSON Schema from the SDK types and diff it in CI against the base branch, modeled on check-protobuf-compatibility. It adds no new types or fields, so it can land later without rework, and the first generated schema becomes the baseline.

    Until then:

    • a golden test parses and re-serializes a fully populated example document committed to the SDK, so removing or renaming a field fails the test and shows in the diff;
    • the crate README states that a change that breaks existing documents bumps SCHEMA_VERSION;
    • deny_unknown_fields stops a newer gateway from sending a field an older driver ignores.

    This is a convention plus a test, not CI enforcement. I propose tracking the schema diff as a follow-up that lands before any driver moves out of this repository, and leaving this criterion unchecked here.

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:apiPublic APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards.topic:extensionsExtension APIs and integration points, consistent design, and external use cases.topic:securityVulnerability management, security analysis/auditing, bypass detection, and abuse prevention.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions