refactor(config): enforce gateway schema version 2

.agents/skills/debug-openshell-cluster/SKILL.md

@@ -82,12 +82,26 @@ Before debugging the compute platform, inspect gateway logs for failures in depe
 For out-of-tree compute drivers, confirm the selected driver name and socket agree across CLI flags or `gateway.toml`, and that the operator-owned driver is running before the gateway starts:
 
 ```bash
-rg -n 'compute_drivers|socket_path' /etc/openshell/gateway.toml
+rg -n '^version|compute_driver|socket_path|guest_tls_' /etc/openshell/gateway.toml
 stat /run/openshell/<driver>.sock
 journalctl -u <driver-service> --no-pager --lines=200
 journalctl -u openshell-gateway --no-pager --lines=200
 ```
 
+Gateway configuration requires `[openshell] version = 2`, a singular
+`compute_driver` selector, and driver-owned settings under
+`[openshell.drivers.<name>]`. The gateway rejects legacy `compute_drivers`,
+`--drivers`, and `OPENSHELL_DRIVERS` selectors rather than silently migrating
+them. Homebrew and RPM package startup migrates only exact package-generated v1
+defaults. If an upgraded package still reports an unsupported version, inspect
+the active prefix or `~/.config/openshell/gateway.toml`; an edited v1 file must
+follow the published schema-v2 migration steps and must not be overwritten.
+Guest TLS CA, certificate, and key paths are the exception to driver ownership:
+configure the complete bundle under `[openshell.gateway]`, and the gateway
+injects it only into the selected local driver. TLS-enabled Docker, Podman, and
+VM drivers fail startup when neither those paths nor the package-managed local
+bundle is available; Kubernetes projects its bundle through a Secret.
+
 Custom names use `[openshell.drivers.<name>].socket_path`. A launch-time `--compute-driver-socket` override may also use `docker`, `podman`, `kubernetes`, or `vm`; the endpoint then takes precedence over built-in construction. First-party standalone drivers require the socket parent directory to be owned by the driver's effective UID, force its mode to `0700`, create the socket with mode `0600`, and accept only peers with that same UID. Check the parent and socket separately with `stat`; a gateway running under a different UID cannot connect even when filesystem permissions or group membership would otherwise allow it. Operator-supplied drivers must provide equivalent access control appropriate to their implementation. Check gateway logs for connection errors, `GetCapabilities` failures, or an unexpected advertised driver name. The advertised name is diagnostic metadata; negotiated features control optional behavior. The gateway does not create or supervise operator-supplied driver processes or sockets.
 
 For configured gateway interceptors, inspect `[[openshell.gateway.interceptors]]`, their Unix or network endpoints, and gateway startup logs:
@@ -620,6 +634,11 @@ Use the VM driver logs and host diagnostics available in the user's environment.
 
 - The VM driver process is running and reachable by the gateway.
 - The runtime rootfs exists and matches the expected architecture.
+- `mke2fs` or `mkfs.ext4` and `debugfs` from e2fsprogs are installed; explicit
+  `sandbox_uid`/`sandbox_gid` does not remove this prerequisite.
+- A persisted overlay identity error is resolved from its owner marker, overlay
+  upper layer, prepared rootfs, explicit config, or current image. Do not assign
+  `10001:10001` unless the persisted state reports that legacy identity.
 - Host virtualization support is enabled.
 - The sandbox supervisor can establish its callback connection to the gateway.
 

.agents/skills/test-release-canary/SKILL.md

@@ -23,6 +23,10 @@ does not contribute to product usage metrics.
 
 `install.sh` defaults to the *latest tagged* release — the canary is therefore checking that the most recent public release still installs, not the just-published `dev` build. The `kubernetes` job is the exception: it pins to `0.0.0-dev` chart + `:dev` images.
 
+The host-package jobs exercise fresh installs, not upgrades from a persisted
+schema-v1 gateway config. Validate Homebrew and RPM exact-default migration with
+the release-tooling and package lifecycle tests before relying on the canary.
+
 The canary does not install or import `@nvidia/openshell-sdk`. TypeScript SDK
 validation lives in the `TypeScript SDK` branch check, including a publish
 dry-run. The tagged release workflow publishes the package to GitHub Packages;
@@ -121,7 +125,7 @@ Loopback registration auto-derives the gateway name to `openshell` if `--name` i
 | Symptom | Likely cause | Where to look |
 |---|---|---|
 | `macos`/`ubuntu`/`fedora` job fails on `install.sh` | Latest tagged release missing an asset, checksum mismatch, or `install.sh` regression on this branch. | Job log around the `curl … install.sh \| sh` step. |
-| `macos`/`ubuntu`/`fedora` job fails on `openshell status` | Local gateway service did not start (systemd/brew/podman). Often a driver issue. | Service logs in the job log; `OPENSHELL_DRIVERS` env in the "Ensure …" step. |
+| `macos`/`ubuntu`/`fedora` job fails on `openshell status` | Local gateway service did not start (systemd/brew/podman). Often a driver issue. | Service logs in the job log; `OPENSHELL_COMPUTE_DRIVER` env in the "Ensure …" step. |
 | `kubernetes` job fails on `helm install --wait` | Chart did not deploy in 5 min — usually image pull failure or readiness probe failing. | "Diagnostics on failure" step dumps `helm status`, manifest, pod describe, pod logs. |
 | `kubernetes` job fails on `kubectl wait` | Gateway pod stuck `CrashLoopBackOff` or `ImagePullBackOff`. | Diagnostics dump; check `:dev` image existence at `ghcr.io/nvidia/openshell/gateway`. |
 | `kubernetes` job fails on `openshell gateway add` or `status` | Port-forward not reachable, or CLI/gateway proto mismatch. | `port-forward.log` and `openshell gateway list` in the diagnostics dump. |

.github/workflows/release-canary.yml

@@ -26,7 +26,7 @@ jobs:
     steps:
       - name: Ensure VM driver
         run: |
-          launchctl setenv OPENSHELL_DRIVERS vm
+          launchctl setenv OPENSHELL_COMPUTE_DRIVER vm
           launchctl setenv OPENSHELL_TELEMETRY_ENABLED "$OPENSHELL_TELEMETRY_ENABLED"
 
       - name: Install and check status
@@ -48,7 +48,7 @@ jobs:
           fi
           sudo systemctl start docker || sudo service docker start
           mkdir -p "${HOME}/.config/openshell"
-          printf 'OPENSHELL_DRIVERS=docker\nOPENSHELL_TELEMETRY_ENABLED=%s\n' \
+          printf 'OPENSHELL_COMPUTE_DRIVER=docker\nOPENSHELL_TELEMETRY_ENABLED=%s\n' \
             "$OPENSHELL_TELEMETRY_ENABLED" > "${HOME}/.config/openshell/gateway.env"
           docker info
 
@@ -140,7 +140,7 @@ jobs:
             bash -s <<'EOF'
           set -euo pipefail
           mkdir -p "${HOME}/.config/openshell"
-          printf 'OPENSHELL_DRIVERS=podman\nOPENSHELL_TELEMETRY_ENABLED=%s\n' \
+          printf 'OPENSHELL_COMPUTE_DRIVER=podman\nOPENSHELL_TELEMETRY_ENABLED=%s\n' \
             "$OPENSHELL_TELEMETRY_ENABLED" > "${HOME}/.config/openshell/gateway.env"
           podman info
           curl -LsSf "${INSTALL_SH_URL}" | sh
@@ -276,7 +276,7 @@ jobs:
         run: |
           set -euo pipefail
           mkdir -p "${HOME}/.config/openshell"
-          printf 'OPENSHELL_DRIVERS=docker\n' > "${HOME}/.config/openshell/gateway.env"
+          printf 'OPENSHELL_COMPUTE_DRIVER=docker\n' > "${HOME}/.config/openshell/gateway.env"
           curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/${{ github.event.workflow_run.head_sha || github.sha }}/install.sh | sh
 
       - name: Register kind gateway and check status

architecture/compute-runtimes.md

@@ -127,10 +127,11 @@ defines the available implementation set, while the runtime consumes a generic
 registry. Adding or removing a compiled driver therefore changes registration
 rather than the server's selection flow. Alternate gateway binaries can install
 their own `ComputeDriverFactory` registrations and hand the completed registry
-to `run_cli_with_compute_drivers`; factories receive merged driver config and
-return either an in-process driver or a gateway-managed remote endpoint. The
-server constructs the common runtime adapter and snapshots `GetCapabilities`
-for either result. A configured UDS endpoint still takes precedence over a
+to `run_cli_with_compute_drivers`; factories receive only the selected
+`[openshell.drivers.<name>]` table and return either an in-process driver or a
+gateway-managed remote endpoint. The server constructs the common runtime
+adapter and snapshots `GetCapabilities` for either result. A configured UDS
+endpoint still takes precedence over a
 compiled registration with the same name.
 
 The `openshell-gateway` composition crate groups first-party registrations
@@ -251,7 +252,7 @@ delete, reconciliation removes the row; otherwise it can remain `Deleting`.
 | Podman | Rootless or single-machine deployments. | Container plus nested sandbox namespace. | Uses the Podman REST API and CDI GPU devices when available. Delivers the supervisor via OCI image volume by default; falls back to extracting the binary to a host-side cache and bind-mounting it when `userns` is configured (overlay does not support idmapped mounts). Advertises the combined-supervisor policy-DNS and transparent-TCP substrate. |
 | Kubernetes | Cluster deployment through Helm. | Pod plus nested sandbox namespace. | Uses Kubernetes API objects, service accounts, secrets, PVC-backed workspace storage, and GPU resources. |
 | VM | Experimental microVM isolation. | Per-sandbox libkrun VM. | Managed endpoint-backed driver. The gateway spawns `openshell-driver-vm`, waits for its Unix socket, and then consumes it through the same remote `compute_driver.proto` path used by unmanaged endpoint drivers. The VM driver boots a cached bootstrap `rootfs.ext4`, prepares requested OCI images inside a bootstrap VM with `umoci`, attaches the prepared image disk read-only, and gives each sandbox a writable `overlay.ext4` for merged-root changes and runtime material. The driver persists each accepted launch request beside the overlay and restarts those VMs on driver startup without recreating the overlay. |
-| Extension | Out-of-tree drivers operated alongside the gateway. | Whatever boundary the driver implements. | Selected by a custom `compute_drivers = ["<name>"]` entry with `[openshell.drivers.<name>].socket_path`, or at launch time by pairing `--drivers <name>` with `--compute-driver-socket=<path>`. A launch-time endpoint may use a canonical built-in name to preserve its driver-config key while replacing in-process construction. The gateway connects to an operator-provisioned UDS, snapshots `GetCapabilities`, and dispatches all sandbox lifecycle calls through `compute_driver.proto`. The driver process and socket lifecycle are operator-owned; the gateway does not spawn, supervise, or remove unmanaged extension drivers. The trust boundary is the socket's filesystem permissions: the operator must ensure only the gateway uid can read/write it. |
+| Extension | Out-of-tree drivers operated alongside the gateway. | Whatever boundary the driver implements. | Selected by a custom `compute_driver = "<name>"` entry with `[openshell.drivers.<name>].socket_path`, or at launch time by pairing `--compute-driver <name>` with `--compute-driver-socket=<path>`. A launch-time endpoint may use a canonical built-in name to preserve its driver-config key while replacing in-process construction. The gateway connects to an operator-provisioned UDS, snapshots `GetCapabilities`, and dispatches all sandbox lifecycle calls through `compute_driver.proto`. The driver process and socket lifecycle are operator-owned; the gateway does not spawn, supervise, or remove unmanaged extension drivers. The trust boundary is the socket's filesystem permissions: the operator must ensure only the gateway uid can read/write it. |
 
 Per-sandbox CPU and memory values currently enter the driver layer through
 template resource limits. Docker and Podman apply them as runtime limits.
@@ -288,10 +289,23 @@ pinned dialing, relay behavior, and OCSF decisions. Docker and Podman advertise
 they implement and validate the same complete contract. The capability marker
 is driver-owned supervisor input and is removed from workload environments.
 
-Kubernetes deployments may set an AppArmor profile on sandbox agent containers
-through the driver configuration. The Helm chart defaults sandbox agents to
-`Unconfined` so runtime/default AppArmor profiles do not block supervisor
-network namespace setup on AppArmor-enabled nodes.
+Kubernetes, Docker, and Podman share one AppArmor configuration model:
+`RuntimeDefault`, `Unconfined`, or `Localhost/<profile>`. Each driver translates
+that model to its native API and rejects an explicitly requested confined
+profile when its backend reports AppArmor unavailable. Docker keeps its
+historical explicit `Unconfined` default. Podman sends no override when the
+field is omitted, preserving the runtime-selected profile; development paths
+that require the supervisor's namespace mount setup opt into `Unconfined`
+explicitly. The Helm chart independently uses `Unconfined` for Kubernetes.
+
+Corporate proxy settings are driver-owned supervisor inputs. Docker, Podman,
+and VM propagate `https_proxy`, `no_proxy`, an optional root-only auth file,
+and the explicit cleartext-Basic-auth acknowledgement without allowing
+workload environment to override them. Local containers project provider SPIFFE
+through a dedicated host UNIX-socket parent mount. A VM cannot safely expose
+that host socket: it accepts only a separately operated, concrete TCP listener
+when `provider_spiffe_allow_guest_tcp = true` explicitly acknowledges guest
+access. Host-only sockets are never implicitly forwarded to VM guests.
 
 The Kubernetes deployment packaging has two ownership boundaries. The gateway
 chart owns the gateway workload, configuration, Services, PKI, and
@@ -309,10 +323,14 @@ can request a specific number of GPUs or the driver-specific default behaviour.
 For all in-tree drivers, this is equivalent to selecting a single GPU.
 
 VM runtime state paths are derived only from driver-validated sandbox IDs
-matching `[A-Za-z0-9._-]{1,128}`. The gateway-owned VM driver socket uses a
-private `run/` directory plus Unix peer UID/PID checks. Standalone
-unauthenticated TCP mode is disabled unless explicitly enabled for local
-development.
+matching `[A-Za-z0-9._-]{1,128}`. Each writable overlay records its effective
+sandbox UID/GID so later rootfs cache changes cannot rewrite persisted file
+ownership. Unmarked pre-migration overlays recover identity from concrete
+overlay or prepared-rootfs state, an explicit operator override, or the current
+image account. The driver never assumes `10001:10001`; it preserves that legacy
+identity only when persisted state reports it. The gateway-owned VM driver
+socket uses a private `run/` directory plus Unix peer UID/PID checks. Standalone unauthenticated TCP
+mode is disabled unless explicitly enabled for local development.
 
 Runtime-specific implementation notes belong in the driver crate README: