Repository navigation
Description
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_configtable 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_*_argsflags 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
0444file in a0700directory (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
elezar commentedon Nov 20, 2026
Design note: startup document
Format and location
A single TOML document,
schema_versionplus two tables, defined in a new cratecrates/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 onserdeandtoml, not onopenshell-core, so the carve-out and consumption from another repository stay possible.gatewayhas a fixed schema withdeny_unknown_fields. Optional fields are omitted when unset, since TOML has no null.driver_configis atoml::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_trustcarries the staged artifact's path, digest, and certificate count only. The PEM bytes do not cross the process boundary.admissionmirrorsDriverAdmissionConfigas plain SDK types, since the SDK cannot depend onopenshell-core.schema_versionit 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-serveroropenshell-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_*_argsincrates/openshell-gateway/src/vm.rsbecomes document construction:--bind-socket,--expected-peer-pid,--log-level,--gateway-namegateway--admission-config-jsongateway.admissiongateway.telemetry--upstream-proxy*gateway.upstream_proxy--additional-ca-bundle,-digest,-certificate-countgateway.network_trust--grpc-endpoint,--state-dir, images, vcpus, memory, krun log level, sandbox uid and gid, rootfs tar settings, guest TLS CA, SPIFFE, bind mountsdriver_configOTLP 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:
SCHEMA_VERSION;deny_unknown_fieldsstops 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.