From 916f43709b2e0be0f21c11ae409852f9a73ddfcb Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 09:03:07 -0700 Subject: [PATCH 01/21] docs: define beta support matrix Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 182 ++++++++++++++++-------------- 1 file changed, 97 insertions(+), 85 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index bb390b06e8..20562981ff 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -2,97 +2,109 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Support Matrix" -description: "" +description: "Review OpenShell compatibility across host platforms, Kubernetes environments, and SDKs." position: 5 --- -This page lists the host platform, compute driver, software, runtime, and kernel requirements for running OpenShell. +## Platforms -## Supported Platforms +| Platform | Installation methods | Versions | +| --- | --- | --- | +| macOS (Apple Silicon) | Homebrew, container images | macOS minimum version: TBD | +| Linux (x86_64, arm64) | APT/DEB, RPM, Snap, container images | glibc 2.28 or later | +| Windows (x86_64, arm64) | MSI, WinGet, container images | Windows minimum version: TBD; MSVC toolchain | -OpenShell publishes multi-architecture gateway images for `linux/amd64` and `linux/arm64`. The CLI, package-managed gateway, and standalone gateway binary are supported on the following host platforms: +## Client -| Platform | Architecture | Status | -| -------------------------------- | --------------------- | --------- | -| Linux (Debian/Ubuntu) | x86_64 (amd64) | Supported | -| Linux (Debian/Ubuntu) | aarch64 (arm64) | Supported | -| macOS (Docker Desktop) | Apple Silicon (arm64) | Supported | -| Windows (WSL 2 + Docker Desktop) | x86_64 | Experimental | - -On Linux, the `openshell` CLI is a static musl binary and does not require glibc at runtime. - -## Standalone Gateway Binary - -OpenShell publishes standalone `openshell-gateway` release assets for manual download on these platforms: - -| Platform | Artifact pattern | -| --------------------- | ---------------------------------------------- | -| Linux x86_64 (amd64) | `openshell-gateway-x86_64-unknown-linux-gnu` | -| Linux aarch64 (arm64) | `openshell-gateway-aarch64-unknown-linux-gnu` | -| macOS Apple Silicon | `openshell-gateway-aarch64-apple-darwin` | - -These artifacts are attached to GitHub releases. Kubernetes deployments should use the Helm chart and the published gateway image. - -On Linux, `openshell-gateway` requires glibc 2.28 or newer. Compatible systems include, for example, Ubuntu 20.04+, RHEL 8+, Rocky Linux 8+, Amazon Linux 2023+, and Fedora 32+. +The OpenShell client includes the CLI and TUI. Client binaries are built with +musl and are supported on macOS, Linux, and Windows. ## Compute Drivers -The gateway can manage sandboxes through several compute drivers. - -| Compute Driver | Status | Notes | -|---|---|---| -| Docker | Supported for local development and single-machine gateways. | Requires Docker Desktop or Docker Engine on the gateway host. | -| Podman | Supported for rootless local and workstation workflows. | Requires a Podman-compatible socket and rootless networking setup. | -| Kubernetes | Supported through the [OpenShell Helm chart](https://github.com/NVIDIA/OpenShell/blob/main/deploy/helm/openshell/README.md). | Requires a Kubernetes cluster supplied by the operator. | -| MicroVM | Supported for VM-backed sandboxes. | Uses the VM compute driver and libkrun-based runtime. | - -## Software Prerequisites - -Install the software for the compute driver you use: - -| Component | Minimum Version | Notes | -|---|---|---| -| Docker Desktop or Docker Engine | 28.04 | Required for Docker-backed gateways, local image builds, and Docker development workflows. | -| Podman | 5.x | Required for Podman-backed gateways. | -| Kubernetes | 1.29 | Required for Helm deployments and Kubernetes sandbox scheduling. | -| Helm | 3.x | Required to install `deploy/helm/openshell`. | -| kubectl | Compatible with your cluster | Required for Kubernetes operational inspection and secret creation. | -| Host virtualization | Host dependent | Required for MicroVM-backed gateways. MicroVM uses Hypervisor.framework on macOS and KVM on Linux. | - -## Sandbox Runtime Versions - -Sandbox container images are maintained in the [openshell-community](https://github.com/nvidia/openshell-community) repository. Refer to that repository for the current list of installed components and their versions. - -## Container Images - -OpenShell publishes the gateway image for `linux/amd64` and `linux/arm64`. - -| Image | Reference | Pulled When | -|---|---|---| -| Gateway | `ghcr.io/nvidia/openshell/gateway:latest` | Helm chart install or upgrade, or standalone container deployment | - -The Helm chart in `deploy/helm/openshell` deploys the gateway workload, service account, service, optional persistent storage, and network policy for Kubernetes. It defaults to a StatefulSet for SQLite-backed installs and can render a Deployment for external database-backed installs. - -Sandbox images are maintained separately in the [openshell-community](https://github.com/nvidia/openshell-community) repository. - -To override the default image references, use Helm values: - -| Helm value | Purpose | -|---|---| -| `image.repository` / `image.tag` | Override the gateway image reference. | -| `server.sandboxImage` | Override the default sandbox image. | - -## Kernel Requirements - -OpenShell enforces sandbox isolation through two Linux kernel security modules: - -| Module | Requirement | Details | -| -------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [Landlock LSM](https://docs.kernel.org/security/landlock.html) | Recommended | Enforces filesystem access restrictions at the kernel level. The `best_effort` compatibility mode uses the highest Landlock ABI the host kernel supports. The `hard_requirement` mode fails sandbox creation if the required ABI is unavailable. | -| seccomp | Required | Filters dangerous system calls. Available on all modern Linux kernels (3.17+). | - -On macOS, these kernel modules run inside the Docker Desktop Linux VM, not on the host kernel. - -## Agent Compatibility - -For the full list of supported agents and their default policy coverage, refer to the [Supported Agents](/about/supported-agents) page. +| Driver | Supported hosts | Minimum version | Requirements | +| --- | --- | --- | --- | +| Docker | macOS, Linux, Windows | TBD | Docker Engine or Docker Desktop. | +| Podman | macOS, Linux, Windows | 5.x | Podman socket, rootless networking, and cgroups v2. | +| MicroVM | macOS, Linux | TBD | `Hypervisor.framework` on macOS; KVM on Linux. | +| Kubernetes | Kubernetes clusters | 1.29 or later | See [Kubernetes](#kubernetes) for Helm, Agent Sandbox, and distribution requirements. | + +## Supervisor Kernel Requirements + +These requirements apply to the Linux environment running the supervisor. On +macOS and Windows, they apply to the container or virtual machine kernel, not +the host kernel. + +| Kernel capability | Requirement | Minimum | Behavior when unavailable | +| --- | --- | --- | --- | +| seccomp BPF | Required | Linux 3.17 or later | Supervisor security initialization fails. | +| Network namespaces, veth, and nftables | Required | TBD | Network policy enforcement cannot start. | +| Landlock LSM | Recommended | Linux 5.13 or later | `best_effort` runs degraded with a security finding; `hard_requirement` fails. | +| cgroups v2 PID controller | Recommended | TBD | The compute driver or container runtime must provide PID limits. | +| User namespaces | Optional | Linux 5.12 or later | Stronger Kubernetes host isolation is unavailable. | + +## Kubernetes + +| Component | Supported version | Notes | +| --- | --- | --- | +| Kubernetes | 1.29 or later | Required for Helm deployments and sandbox scheduling. | +| Helm | 3.x | Required to install and upgrade the OpenShell chart. | +| Agent Sandbox controller and CRDs | Compatible release; version TBD | Required before installing the OpenShell chart. | + +Install the Agent Sandbox controller and its `Sandbox` CRDs before deploying +the OpenShell Helm chart. Refer to [Kubernetes setup](/kubernetes/setup) for +installation instructions. + +### Distributions + +- GKE Standard and Autopilot clusters are supported. +- OpenShift 4.x is supported with the OpenShift-specific SCC binding and chart + configuration. Refer to [OpenShift installation](/kubernetes/openshift) for + the required overrides. + +## SDKs + +| SDK | Minimum version | +| --- | --- | +| Python | 3.12 | +| TypeScript | TBD | +| Rust | 1.90 | +| Go | TBD | + +## API Compatibility + +The compatibility policy covers published gRPC services, Protobuf messages, +generated SDK interfaces, documented error behavior, and the Compute Driver +API used by out-of-tree drivers. It does not cover internal storage schemas or +implementation details. + +### Compatibility Promise + +| Release phase | Compatibility policy | +| --- | --- | +| Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release must include migration guidance and coordinated SDK updates. | +| Stable | Minor and patch releases are backward compatible within an API major version. Breaking changes require a new versioned Protobuf package and API major version. The previous stable API remains supported for at least 12 months or two minor releases after its replacement, whichever is longer. | + +During the beta milestone, the beta policy applies even when a Protobuf package +uses a `v1` suffix. Within a supported API major version, existing clients must +continue to work with newer servers. New clients may require capabilities that +are not available from older servers. + +### Change Policy + +| Change | Policy | +| --- | --- | +| Additive | New optional fields, messages, methods, and enum values may be added when existing requests and responses retain their meaning and defaults. | +| Deprecating | Keep the existing element functional, mark it deprecated in the schema and documentation, and identify its replacement and planned removal release. | +| Breaking | Removing or renaming an API element, reusing or renumbering a field, changing a field type or cardinality, making an existing input required, or changing documented semantics requires the beta process or a new stable API major version. | + +Removed Protobuf field and enum numbers and names must be reserved and never +reused. API changes must pass automated source, wire, and JSON compatibility +checks against the default branch. Release validation must exercise an older +supported SDK against the new server and the current SDK against every server +version still in the support window. + +This policy draws from the +[Kubernetes API deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/), +[Google AIP-180](https://google.aip.dev/180), +[Protobuf best practices](https://protobuf.dev/best-practices/dos-donts/), and +[Buf breaking-change detection](https://buf.build/docs/breaking/). From 0c0e1733b829065a45b232e76d28fec48d1368a4 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 09:22:26 -0700 Subject: [PATCH 02/21] docs: clarify API compatibility wording Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 20562981ff..1e388b342f 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -85,7 +85,7 @@ implementation details. | Stable | Minor and patch releases are backward compatible within an API major version. Breaking changes require a new versioned Protobuf package and API major version. The previous stable API remains supported for at least 12 months or two minor releases after its replacement, whichever is longer. | During the beta milestone, the beta policy applies even when a Protobuf package -uses a `v1` suffix. Within a supported API major version, existing clients must +uses a `v1` suffix. Within a supported API major version, existing clients continue to work with newer servers. New clients may require capabilities that are not available from older servers. @@ -94,14 +94,14 @@ are not available from older servers. | Change | Policy | | --- | --- | | Additive | New optional fields, messages, methods, and enum values may be added when existing requests and responses retain their meaning and defaults. | -| Deprecating | Keep the existing element functional, mark it deprecated in the schema and documentation, and identify its replacement and planned removal release. | -| Breaking | Removing or renaming an API element, reusing or renumbering a field, changing a field type or cardinality, making an existing input required, or changing documented semantics requires the beta process or a new stable API major version. | - -Removed Protobuf field and enum numbers and names must be reserved and never -reused. API changes must pass automated source, wire, and JSON compatibility -checks against the default branch. Release validation must exercise an older -supported SDK against the new server and the current SDK against every server -version still in the support window. +| Deprecating | The existing element remains functional while the schema and documentation identify it as deprecated, name its replacement, and state its planned removal release. | +| Breaking | Removing or renaming an API element, reusing or renumbering a field, changing a field type or cardinality, making an existing input required, or changing documented semantics follows the beta process or ships in a new stable API major version. | + +Removed Protobuf field and enum numbers and names remain reserved and are never +reused. CI compares API changes with the default branch for source, wire, and +JSON compatibility. Release validation exercises older supported SDKs against +the new server and the current SDKs against every server version still in the +support window. This policy draws from the [Kubernetes API deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/), From 7ccf57256b053f1a2178a864f3806a092b9cedfd Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 09:23:17 -0700 Subject: [PATCH 03/21] docs: define client server validation Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 1e388b342f..8221a42556 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -99,9 +99,11 @@ are not available from older servers. Removed Protobuf field and enum numbers and names remain reserved and are never reused. CI compares API changes with the default branch for source, wire, and -JSON compatibility. Release validation exercises older supported SDKs against -the new server and the current SDKs against every server version still in the -support window. +JSON compatibility. Release validation exercises the oldest supported release +of the CLI, TUI, and each SDK against the candidate server. The current client +release runs the shared-feature compatibility suite against every server +version still in the support window. Features newer than the server use +capability detection and return an actionable unsupported-version error. This policy draws from the [Kubernetes API deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/), From aeaa33017f3c56bf8a7e2c2c58247e23bcc58ffc Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 09:24:02 -0700 Subject: [PATCH 04/21] docs: describe API capability discovery Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 8221a42556..54cc0adbb1 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -89,6 +89,22 @@ uses a `v1` suffix. Within a supported API major version, existing clients continue to work with newer servers. New clients may require capabilities that are not available from older servers. +### Capability Discovery + +The gateway publishes structured compatibility information for clients: + +| Compatibility field | Purpose | +| --- | --- | +| Supported API versions | Identifies the API versions served by the gateway. | +| Capabilities | Uses stable identifiers to report available operations and behaviors. | +| Minimum client version | Identifies clients that cannot safely communicate with the gateway. | +| Deprecations | Identifies deprecated capabilities, their replacements, and their planned removal versions. | + +The CLI, TUI, and SDKs select behavior from the advertised capabilities rather +than inferring feature support from the server version. When an older server +does not advertise a capability, the client hides or disables the feature when +possible and otherwise returns an actionable unsupported-version error. + ### Change Policy | Change | Policy | @@ -99,11 +115,12 @@ are not available from older servers. Removed Protobuf field and enum numbers and names remain reserved and are never reused. CI compares API changes with the default branch for source, wire, and -JSON compatibility. Release validation exercises the oldest supported release -of the CLI, TUI, and each SDK against the candidate server. The current client -release runs the shared-feature compatibility suite against every server -version still in the support window. Features newer than the server use -capability detection and return an actionable unsupported-version error. +JSON compatibility. Client-server validation covers behavioral compatibility +by exercising the oldest supported release of the CLI, TUI, and each SDK +against the candidate server. The current client release runs the +shared-feature compatibility suite against every server version still in the +support window. Features newer than the server use capability detection and +return an actionable unsupported-version error. This policy draws from the [Kubernetes API deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/), From c8952c806b9c0d6e8ec6f4a332d47f9af307d7d4 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 09:28:37 -0700 Subject: [PATCH 05/21] docs: reframe client server compatibility Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 135 ++++++++++++++---------------- 1 file changed, 63 insertions(+), 72 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 54cc0adbb1..a7d88c96ab 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -5,14 +5,13 @@ title: "Support Matrix" description: "Review OpenShell compatibility across host platforms, Kubernetes environments, and SDKs." position: 5 --- - ## Platforms -| Platform | Installation methods | Versions | -| --- | --- | --- | -| macOS (Apple Silicon) | Homebrew, container images | macOS minimum version: TBD | -| Linux (x86_64, arm64) | APT/DEB, RPM, Snap, container images | glibc 2.28 or later | -| Windows (x86_64, arm64) | MSI, WinGet, container images | Windows minimum version: TBD; MSVC toolchain | +| Platform | Installation methods | Versions | +| ----------------------- | ------------------------------------ | -------------------------------------------- | +| macOS (Apple Silicon) | Homebrew, container images | macOS minimum version: TBD | +| Linux (x86_64, arm64) | APT/DEB, RPM, Snap, container images | glibc 2.28 or later | +| Windows (x86_64, arm64) | MSI, WinGet, container images | Windows minimum version: TBD; MSVC toolchain | ## Client @@ -21,12 +20,12 @@ musl and are supported on macOS, Linux, and Windows. ## Compute Drivers -| Driver | Supported hosts | Minimum version | Requirements | -| --- | --- | --- | --- | -| Docker | macOS, Linux, Windows | TBD | Docker Engine or Docker Desktop. | -| Podman | macOS, Linux, Windows | 5.x | Podman socket, rootless networking, and cgroups v2. | -| MicroVM | macOS, Linux | TBD | `Hypervisor.framework` on macOS; KVM on Linux. | -| Kubernetes | Kubernetes clusters | 1.29 or later | See [Kubernetes](#kubernetes) for Helm, Agent Sandbox, and distribution requirements. | +| Driver | Supported hosts | Minimum version | Requirements | +| ---------- | --------------------- | --------------- | ------------------------------------------------------------------------------------- | +| Docker | macOS, Linux, Windows | TBD | Docker Engine or Docker Desktop. | +| Podman | macOS, Linux, Windows | 5.x | Podman socket, rootless networking, and cgroups v2. | +| MicroVM | macOS, Linux | TBD | `Hypervisor.framework` on macOS; KVM on Linux. | +| Kubernetes | Kubernetes clusters | 1.29 or later | See [Kubernetes](#kubernetes) for Helm, Agent Sandbox, and distribution requirements. | ## Supervisor Kernel Requirements @@ -34,21 +33,21 @@ These requirements apply to the Linux environment running the supervisor. On macOS and Windows, they apply to the container or virtual machine kernel, not the host kernel. -| Kernel capability | Requirement | Minimum | Behavior when unavailable | -| --- | --- | --- | --- | -| seccomp BPF | Required | Linux 3.17 or later | Supervisor security initialization fails. | -| Network namespaces, veth, and nftables | Required | TBD | Network policy enforcement cannot start. | -| Landlock LSM | Recommended | Linux 5.13 or later | `best_effort` runs degraded with a security finding; `hard_requirement` fails. | -| cgroups v2 PID controller | Recommended | TBD | The compute driver or container runtime must provide PID limits. | -| User namespaces | Optional | Linux 5.12 or later | Stronger Kubernetes host isolation is unavailable. | +| Kernel capability | Requirement | Minimum | Behavior when unavailable | +| -------------------------------------- | ----------- | ------------------- | ------------------------------------------------------------------------------ | +| seccomp BPF | Required | Linux 3.17 or later | Supervisor security initialization fails. | +| Network namespaces, veth, and nftables | Required | TBD | Network policy enforcement cannot start. | +| Landlock LSM | Recommended | Linux 5.13 or later | `best_effort` runs degraded with a security finding; `hard_requirement` fails. | +| cgroups v2 PID controller | Recommended | TBD | The compute driver or container runtime must provide PID limits. | +| User namespaces | Optional | Linux 5.12 or later | Stronger Kubernetes host isolation is unavailable. | ## Kubernetes -| Component | Supported version | Notes | -| --- | --- | --- | -| Kubernetes | 1.29 or later | Required for Helm deployments and sandbox scheduling. | -| Helm | 3.x | Required to install and upgrade the OpenShell chart. | -| Agent Sandbox controller and CRDs | Compatible release; version TBD | Required before installing the OpenShell chart. | +| Component | Supported version | Notes | +| --------------------------------- | ------------------------------- | ----------------------------------------------------- | +| Kubernetes | 1.29 or later | Required for Helm deployments and sandbox scheduling. | +| Helm | 3.x | Required to install and upgrade the OpenShell chart. | +| Agent Sandbox controller and CRDs | Compatible release; version TBD | Required before installing the OpenShell chart. | Install the Agent Sandbox controller and its `Sandbox` CRDs before deploying the OpenShell Helm chart. Refer to [Kubernetes setup](/kubernetes/setup) for @@ -58,72 +57,64 @@ installation instructions. - GKE Standard and Autopilot clusters are supported. - OpenShift 4.x is supported with the OpenShift-specific SCC binding and chart - configuration. Refer to [OpenShift installation](/kubernetes/openshift) for - the required overrides. +configuration. Refer to [OpenShift installation](/kubernetes/openshift) for +the required overrides. ## SDKs -| SDK | Minimum version | -| --- | --- | -| Python | 3.12 | -| TypeScript | TBD | -| Rust | 1.90 | -| Go | TBD | +| SDK | Minimum version | +| ---------- | --------------- | +| Python | 3.12 | +| TypeScript | TBD | +| Rust | 1.90 | +| Go | TBD | ## API Compatibility -The compatibility policy covers published gRPC services, Protobuf messages, -generated SDK interfaces, documented error behavior, and the Compute Driver -API used by out-of-tree drivers. It does not cover internal storage schemas or -implementation details. +The compatibility policy covers published gRPC services, Protobuf messages, generated SDK interfaces, documented error behavior Driver, Interceptor, and Middleware APIs. ### Compatibility Promise -| Release phase | Compatibility policy | -| --- | --- | -| Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release must include migration guidance and coordinated SDK updates. | -| Stable | Minor and patch releases are backward compatible within an API major version. Breaking changes require a new versioned Protobuf package and API major version. The previous stable API remains supported for at least 12 months or two minor releases after its replacement, whichever is longer. | +| Release phase | Compatibility policy | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release must include migration guidance and coordinated SDK updates. | +| Stable | Minor and patch releases are backward compatible within an API major version. Breaking changes require a new versioned Protobuf package and API major version. The previous stable API remains supported for at least 12 months or two minor releases after its replacement, whichever is longer. | During the beta milestone, the beta policy applies even when a Protobuf package -uses a `v1` suffix. Within a supported API major version, existing clients -continue to work with newer servers. New clients may require capabilities that -are not available from older servers. +uses a `v1` suffix. + +### Change Policy + +| Change | Policy | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Additive | New optional fields, messages, methods, and enum values may be added when existing requests and responses retain their meaning and defaults. | +| Deprecating | Keep the existing element functional, mark it deprecated in the schema and documentation, and identify its replacement and planned removal release. | +| Breaking | Removing or renaming an API element, reusing or renumbering a field, changing a field type or cardinality, making an existing input required, or changing documented semantics requires the beta process or a new stable API major version. | -### Capability Discovery +### Client and Server Compatibility -The gateway publishes structured compatibility information for clients: +OpenShell evaluates compatibility in both client/server directions. Clients +include the CLI, TUI, and supported SDKs. -| Compatibility field | Purpose | +| Combination | Expected behavior | | --- | --- | -| Supported API versions | Identifies the API versions served by the gateway. | -| Capabilities | Uses stable identifiers to report available operations and behaviors. | -| Minimum client version | Identifies clients that cannot safely communicate with the gateway. | -| Deprecations | Identifies deprecated capabilities, their replacements, and their planned removal versions. | +| Older client with newer server | Operations available to the client retain their request, response, error, and behavioral semantics throughout the support window. | +| Newer client with older server | Features shared by both releases continue to work. Features unavailable from the server are hidden or return an actionable unsupported-version error. | +| Different patch versions | Existing features remain compatible in both directions. | +| Different API major versions | Compatibility depends on the server continuing to expose the older API version during its deprecation window. | -The CLI, TUI, and SDKs select behavior from the advertised capabilities rather -than inferring feature support from the server version. When an older server -does not advertise a capability, the client hides or disables the feature when -possible and otherwise returns an actionable unsupported-version error. +Clients use the capabilities advertised by the server to select supported +behavior instead of inferring feature availability from the server version +alone. -### Change Policy +Release validation exercises the oldest supported release of the CLI, TUI, and +each SDK against the candidate server. Current clients run the shared-feature +suite against each server release in the support window. Capability-specific +tests verify the behavior of features that are newer than the server. -| Change | Policy | -| --- | --- | -| Additive | New optional fields, messages, methods, and enum values may be added when existing requests and responses retain their meaning and defaults. | -| Deprecating | The existing element remains functional while the schema and documentation identify it as deprecated, name its replacement, and state its planned removal release. | -| Breaking | Removing or renaming an API element, reusing or renumbering a field, changing a field type or cardinality, making an existing input required, or changing documented semantics follows the beta process or ships in a new stable API major version. | +### Schema Compatibility Removed Protobuf field and enum numbers and names remain reserved and are never reused. CI compares API changes with the default branch for source, wire, and -JSON compatibility. Client-server validation covers behavioral compatibility -by exercising the oldest supported release of the CLI, TUI, and each SDK -against the candidate server. The current client release runs the -shared-feature compatibility suite against every server version still in the -support window. Features newer than the server use capability detection and -return an actionable unsupported-version error. - -This policy draws from the -[Kubernetes API deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/), -[Google AIP-180](https://google.aip.dev/180), -[Protobuf best practices](https://protobuf.dev/best-practices/dos-donts/), and -[Buf breaking-change detection](https://buf.build/docs/breaking/). +JSON compatibility. Client/server validation covers request semantics, response +semantics, documented errors, and feature negotiation. From 7362cf3958586b1b75d33b3d51ffbf88e8df29d6 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 09:30:46 -0700 Subject: [PATCH 06/21] docs: split API compatibility policy Signed-off-by: Drew Newberry --- docs/reference/api-compatibility.mdx | 60 ++++++++++++++++++++++++++++ docs/reference/support-matrix.mdx | 50 ++--------------------- 2 files changed, 63 insertions(+), 47 deletions(-) create mode 100644 docs/reference/api-compatibility.mdx diff --git a/docs/reference/api-compatibility.mdx b/docs/reference/api-compatibility.mdx new file mode 100644 index 0000000000..6716a6f1d0 --- /dev/null +++ b/docs/reference/api-compatibility.mdx @@ -0,0 +1,60 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "API Compatibility" +description: "Review OpenShell API versioning, deprecation, schema evolution, and client/server compatibility guarantees." +position: 6 +--- + +The compatibility policy covers published gRPC services, Protobuf messages, +generated SDK interfaces, documented error behavior, and public Driver, +Interceptor, and Middleware APIs. + +## Compatibility Promise + +| Release phase | Compatibility policy | +| --- | --- | +| Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release includes migration guidance and coordinated SDK updates. | +| Stable | Minor and patch releases are backward compatible within an API major version. Breaking changes use a new versioned Protobuf package and API major version. The previous stable API remains supported for at least 12 months or two minor releases after its replacement, whichever is longer. | + +During the beta milestone, the beta policy applies even when a Protobuf package +uses a `v1` suffix. + +## Change Policy + +| Change | Policy | +| --- | --- | +| Additive | New optional fields, messages, methods, and enum values may be added when existing requests and responses retain their meaning and defaults. | +| Deprecating | The existing element remains functional while the schema and documentation identify it as deprecated, name its replacement, and state its planned removal release. | +| Breaking | Removing or renaming an API element, reusing or renumbering a field, changing a field type or cardinality, making an existing input required, or changing documented semantics follows the beta process or ships in a new stable API major version. | + +## Client and Server Compatibility + +OpenShell evaluates compatibility in both client/server directions. Clients +include the CLI, TUI, and supported SDKs. + +| Combination | Expected behavior | +| --- | --- | +| Older client with newer server | Operations available to the client retain their request, response, error, and behavioral semantics throughout the support window. | +| Newer client with older server | Features shared by both releases continue to work. Features unavailable from the server are hidden or return an actionable unsupported-version error. | +| Different patch versions | Existing features remain compatible in both directions. | +| Different API major versions | Compatibility depends on the server continuing to expose the older API version during its deprecation window. | + +Clients use the capabilities advertised by the server to select supported +behavior instead of inferring feature availability from the server version +alone. + +Release validation exercises the oldest supported release of the CLI, TUI, and +each SDK against the candidate server. Current clients run the shared-feature +suite against each server release in the support window. Capability-specific +tests verify the behavior of features that are newer than the server. + +## Schema Compatibility + +Removed Protobuf field and enum numbers and names remain reserved and are never +reused. CI compares API changes with the default branch for source, wire, and +JSON compatibility. Client/server validation covers request semantics, response +semantics, documented errors, and feature negotiation. + +For supported platforms, clients, compute drivers, Kubernetes distributions, +and SDK versions, refer to the [Support Matrix](/reference/support-matrix). diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index a7d88c96ab..5d01e843d9 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -71,50 +71,6 @@ the required overrides. ## API Compatibility -The compatibility policy covers published gRPC services, Protobuf messages, generated SDK interfaces, documented error behavior Driver, Interceptor, and Middleware APIs. - -### Compatibility Promise - -| Release phase | Compatibility policy | -| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release must include migration guidance and coordinated SDK updates. | -| Stable | Minor and patch releases are backward compatible within an API major version. Breaking changes require a new versioned Protobuf package and API major version. The previous stable API remains supported for at least 12 months or two minor releases after its replacement, whichever is longer. | - -During the beta milestone, the beta policy applies even when a Protobuf package -uses a `v1` suffix. - -### Change Policy - -| Change | Policy | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Additive | New optional fields, messages, methods, and enum values may be added when existing requests and responses retain their meaning and defaults. | -| Deprecating | Keep the existing element functional, mark it deprecated in the schema and documentation, and identify its replacement and planned removal release. | -| Breaking | Removing or renaming an API element, reusing or renumbering a field, changing a field type or cardinality, making an existing input required, or changing documented semantics requires the beta process or a new stable API major version. | - -### Client and Server Compatibility - -OpenShell evaluates compatibility in both client/server directions. Clients -include the CLI, TUI, and supported SDKs. - -| Combination | Expected behavior | -| --- | --- | -| Older client with newer server | Operations available to the client retain their request, response, error, and behavioral semantics throughout the support window. | -| Newer client with older server | Features shared by both releases continue to work. Features unavailable from the server are hidden or return an actionable unsupported-version error. | -| Different patch versions | Existing features remain compatible in both directions. | -| Different API major versions | Compatibility depends on the server continuing to expose the older API version during its deprecation window. | - -Clients use the capabilities advertised by the server to select supported -behavior instead of inferring feature availability from the server version -alone. - -Release validation exercises the oldest supported release of the CLI, TUI, and -each SDK against the candidate server. Current clients run the shared-feature -suite against each server release in the support window. Capability-specific -tests verify the behavior of features that are newer than the server. - -### Schema Compatibility - -Removed Protobuf field and enum numbers and names remain reserved and are never -reused. CI compares API changes with the default branch for source, wire, and -JSON compatibility. Client/server validation covers request semantics, response -semantics, documented errors, and feature negotiation. +OpenShell maintains compatibility across its gRPC APIs, clients, SDKs, and +compute drivers. Refer to [API Compatibility](/reference/api-compatibility) for +the versioning, deprecation, and client/server compatibility policy. From 2aa662764283c3491a01b2b5601363a50a5047cd Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 09:38:13 -0700 Subject: [PATCH 07/21] wip --- docs/reference/api-compatibility.mdx | 38 +++++++++++++++------------- 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/docs/reference/api-compatibility.mdx b/docs/reference/api-compatibility.mdx index 6716a6f1d0..d4be4f6789 100644 --- a/docs/reference/api-compatibility.mdx +++ b/docs/reference/api-compatibility.mdx @@ -5,40 +5,42 @@ title: "API Compatibility" description: "Review OpenShell API versioning, deprecation, schema evolution, and client/server compatibility guarantees." position: 6 --- - The compatibility policy covers published gRPC services, Protobuf messages, generated SDK interfaces, documented error behavior, and public Driver, Interceptor, and Middleware APIs. ## Compatibility Promise -| Release phase | Compatibility policy | -| --- | --- | -| Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release includes migration guidance and coordinated SDK updates. | -| Stable | Minor and patch releases are backward compatible within an API major version. Breaking changes use a new versioned Protobuf package and API major version. The previous stable API remains supported for at least 12 months or two minor releases after its replacement, whichever is longer. | -During the beta milestone, the beta policy applies even when a Protobuf package -uses a `v1` suffix. +| Release phase | Compatibility policy | +| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release includes migration guidance and coordinated SDK updates. | +| Stable | Minor and patch releases are backward compatible within an API major version. Breaking changes use a new versioned Protobuf package and API major version. The previous stable API remains supported for at least 12 months or two minor releases after its replacement, whichever is longer. | + ## Change Policy -| Change | Policy | -| --- | --- | -| Additive | New optional fields, messages, methods, and enum values may be added when existing requests and responses retain their meaning and defaults. | -| Deprecating | The existing element remains functional while the schema and documentation identify it as deprecated, name its replacement, and state its planned removal release. | -| Breaking | Removing or renaming an API element, reusing or renumbering a field, changing a field type or cardinality, making an existing input required, or changing documented semantics follows the beta process or ships in a new stable API major version. | + +| Change | Policy | +| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Additive | New optional fields, messages, methods, and enum values may be added when existing requests and responses retain their meaning and defaults. | +| Deprecating | The existing element remains functional while the schema and documentation identify it as deprecated, name its replacement, and state its planned removal release. | +| Breaking | Removing or renaming an API element, reusing or renumbering a field, changing a field type or cardinality, making an existing input required, or changing documented semantics follows the beta process or ships in a new stable API major version. | + ## Client and Server Compatibility OpenShell evaluates compatibility in both client/server directions. Clients include the CLI, TUI, and supported SDKs. -| Combination | Expected behavior | -| --- | --- | -| Older client with newer server | Operations available to the client retain their request, response, error, and behavioral semantics throughout the support window. | + +| Combination | Expected behavior | +| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| Older client with newer server | Operations available to the client retain their request, response, error, and behavioral semantics throughout the support window. | | Newer client with older server | Features shared by both releases continue to work. Features unavailable from the server are hidden or return an actionable unsupported-version error. | -| Different patch versions | Existing features remain compatible in both directions. | -| Different API major versions | Compatibility depends on the server continuing to expose the older API version during its deprecation window. | +| Different patch versions | Existing features remain compatible in both directions. | +| Different API major versions | Compatibility depends on the server continuing to expose the older API version during its deprecation window. | + Clients use the capabilities advertised by the server to select supported behavior instead of inferring feature availability from the server version @@ -57,4 +59,4 @@ JSON compatibility. Client/server validation covers request semantics, response semantics, documented errors, and feature negotiation. For supported platforms, clients, compute drivers, Kubernetes distributions, -and SDK versions, refer to the [Support Matrix](/reference/support-matrix). +and SDK versions, refer to the [Support Matrix](/reference/support-matrix). \ No newline at end of file From 19a9862284814050f8bd471996529ff56d0edcf0 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 09:47:58 -0700 Subject: [PATCH 08/21] docs: refine compatibility version floors Signed-off-by: Drew Newberry --- docs/reference/api-compatibility.mdx | 8 +------- docs/reference/support-matrix.mdx | 18 +++++++++--------- 2 files changed, 10 insertions(+), 16 deletions(-) diff --git a/docs/reference/api-compatibility.mdx b/docs/reference/api-compatibility.mdx index d4be4f6789..e3799bfb1d 100644 --- a/docs/reference/api-compatibility.mdx +++ b/docs/reference/api-compatibility.mdx @@ -11,29 +11,24 @@ Interceptor, and Middleware APIs. ## Compatibility Promise - | Release phase | Compatibility policy | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release includes migration guidance and coordinated SDK updates. | | Stable | Minor and patch releases are backward compatible within an API major version. Breaking changes use a new versioned Protobuf package and API major version. The previous stable API remains supported for at least 12 months or two minor releases after its replacement, whichever is longer. | - ## Change Policy - | Change | Policy | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Additive | New optional fields, messages, methods, and enum values may be added when existing requests and responses retain their meaning and defaults. | | Deprecating | The existing element remains functional while the schema and documentation identify it as deprecated, name its replacement, and state its planned removal release. | | Breaking | Removing or renaming an API element, reusing or renumbering a field, changing a field type or cardinality, making an existing input required, or changing documented semantics follows the beta process or ships in a new stable API major version. | - ## Client and Server Compatibility OpenShell evaluates compatibility in both client/server directions. Clients include the CLI, TUI, and supported SDKs. - | Combination | Expected behavior | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Older client with newer server | Operations available to the client retain their request, response, error, and behavioral semantics throughout the support window. | @@ -41,7 +36,6 @@ include the CLI, TUI, and supported SDKs. | Different patch versions | Existing features remain compatible in both directions. | | Different API major versions | Compatibility depends on the server continuing to expose the older API version during its deprecation window. | - Clients use the capabilities advertised by the server to select supported behavior instead of inferring feature availability from the server version alone. @@ -59,4 +53,4 @@ JSON compatibility. Client/server validation covers request semantics, response semantics, documented errors, and feature negotiation. For supported platforms, clients, compute drivers, Kubernetes distributions, -and SDK versions, refer to the [Support Matrix](/reference/support-matrix). \ No newline at end of file +and SDK versions, refer to the [Support Matrix](/reference/support-matrix). diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 5d01e843d9..14500f7d51 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -7,11 +7,11 @@ position: 5 --- ## Platforms -| Platform | Installation methods | Versions | -| ----------------------- | ------------------------------------ | -------------------------------------------- | -| macOS (Apple Silicon) | Homebrew, container images | macOS minimum version: TBD | -| Linux (x86_64, arm64) | APT/DEB, RPM, Snap, container images | glibc 2.28 or later | -| Windows (x86_64, arm64) | MSI, WinGet, container images | Windows minimum version: TBD; MSVC toolchain | +| Platform | Installation methods | Versions | +| ----------------------- | -------------------- | -------------------------------------------- | +| macOS (Apple Silicon) | Homebrew | macOS 13.3 or later | +| Linux (x86_64, arm64) | APT/DEB, RPM, Snap | Linux kernel 5.13 or later | +| Windows (x86_64, arm64) | MSI, WinGet | Windows minimum version: TBD; MSVC toolchain | ## Client @@ -22,9 +22,9 @@ musl and are supported on macOS, Linux, and Windows. | Driver | Supported hosts | Minimum version | Requirements | | ---------- | --------------------- | --------------- | ------------------------------------------------------------------------------------- | -| Docker | macOS, Linux, Windows | TBD | Docker Engine or Docker Desktop. | +| Docker | macOS, Linux, Windows | 28.0.4 or later | Docker Engine or Docker Desktop. | | Podman | macOS, Linux, Windows | 5.x | Podman socket, rootless networking, and cgroups v2. | -| MicroVM | macOS, Linux | TBD | `Hypervisor.framework` on macOS; KVM on Linux. | +| MicroVM | macOS, Linux | macOS 13.3 or later; Linux kernel 5.13 or later | Host virtualization enabled; `Hypervisor.framework` on macOS; KVM on Linux. | | Kubernetes | Kubernetes clusters | 1.29 or later | See [Kubernetes](#kubernetes) for Helm, Agent Sandbox, and distribution requirements. | ## Supervisor Kernel Requirements @@ -65,9 +65,9 @@ the required overrides. | SDK | Minimum version | | ---------- | --------------- | | Python | 3.12 | -| TypeScript | TBD | +| TypeScript | 5.7 | | Rust | 1.90 | -| Go | TBD | +| Go | 1.24 | ## API Compatibility From 258c9a25aa9b8934aa4905302711eaade9fbfb0e Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 09:57:24 -0700 Subject: [PATCH 09/21] docs: introduce support matrix sections Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 14500f7d51..48897c4962 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -7,6 +7,9 @@ position: 5 --- ## Platforms +Install and run OpenShell on macOS, Linux, or Windows using a standard package +installer. Refer to [Installation](/about/installation) for setup instructions. + | Platform | Installation methods | Versions | | ----------------------- | -------------------- | -------------------------------------------- | | macOS (Apple Silicon) | Homebrew | macOS 13.3 or later | @@ -16,7 +19,8 @@ position: 5 ## Client The OpenShell client includes the CLI and TUI. Client binaries are built with -musl and are supported on macOS, Linux, and Windows. +musl and are supported on macOS, Linux, and Windows. You can download and run +the client without running a local gateway. ## Compute Drivers @@ -43,6 +47,8 @@ the host kernel. ## Kubernetes +Run OpenShell on Kubernetes as a distributed, multi-tenant application. + | Component | Supported version | Notes | | --------------------------------- | ------------------------------- | ----------------------------------------------------- | | Kubernetes | 1.29 or later | Required for Helm deployments and sandbox scheduling. | @@ -62,6 +68,8 @@ the required overrides. ## SDKs +Use the supported SDKs to connect to local or remote OpenShell deployments. + | SDK | Minimum version | | ---------- | --------------- | | Python | 3.12 | From 1f88b3a289397205408ed7460225cbe5058f7621 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 10:08:04 -0700 Subject: [PATCH 10/21] docs: make support matrix descriptive Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 38 +++++++++++++++++-------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 48897c4962..8dca7808c2 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -5,10 +5,16 @@ title: "Support Matrix" description: "Review OpenShell compatibility across host platforms, Kubernetes environments, and SDKs." position: 5 --- +OpenShell can run sandboxes on a local macOS, Linux, or Windows machine or as +a distributed deployment on Kubernetes. The OpenShell CLI, TUI, and SDKs can +manage a local gateway or connect to a remote gateway. This matrix lists the +supported platforms, runtimes, and client toolchains. + ## Platforms -Install and run OpenShell on macOS, Linux, or Windows using a standard package -installer. Refer to [Installation](/about/installation) for setup instructions. +OpenShell can be installed and run on macOS, Linux, or Windows using standard +package installers. The [Installation guide](/about/installation) provides +setup instructions. | Platform | Installation methods | Versions | | ----------------------- | -------------------- | -------------------------------------------- | @@ -16,20 +22,18 @@ installer. Refer to [Installation](/about/installation) for setup instructions. | Linux (x86_64, arm64) | APT/DEB, RPM, Snap | Linux kernel 5.13 or later | | Windows (x86_64, arm64) | MSI, WinGet | Windows minimum version: TBD; MSVC toolchain | -## Client - The OpenShell client includes the CLI and TUI. Client binaries are built with -musl and are supported on macOS, Linux, and Windows. You can download and run -the client without running a local gateway. +musl and are supported on macOS, Linux, and Windows. The client can be +downloaded and run without a local gateway or package manager. ## Compute Drivers -| Driver | Supported hosts | Minimum version | Requirements | -| ---------- | --------------------- | --------------- | ------------------------------------------------------------------------------------- | -| Docker | macOS, Linux, Windows | 28.0.4 or later | Docker Engine or Docker Desktop. | -| Podman | macOS, Linux, Windows | 5.x | Podman socket, rootless networking, and cgroups v2. | -| MicroVM | macOS, Linux | macOS 13.3 or later; Linux kernel 5.13 or later | Host virtualization enabled; `Hypervisor.framework` on macOS; KVM on Linux. | -| Kubernetes | Kubernetes clusters | 1.29 or later | See [Kubernetes](#kubernetes) for Helm, Agent Sandbox, and distribution requirements. | +| Driver | Supported hosts | Minimum version | Requirements | +| ---------- | --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- | +| Docker | macOS, Linux, Windows | 28.0.4 or later | Docker Engine or Docker Desktop. | +| Podman | macOS, Linux, Windows | 5.x | Podman socket, rootless networking, and cgroups v2. | +| MicroVM | macOS, Linux | macOS 13.3 or later; Linux kernel 5.13 or later | Host virtualization enabled; `Hypervisor.framework` on macOS; KVM on Linux. | +| Kubernetes | Kubernetes clusters | 1.29 or later | See [Kubernetes](#kubernetes) for Helm, Agent Sandbox, and distribution requirements. | ## Supervisor Kernel Requirements @@ -47,7 +51,7 @@ the host kernel. ## Kubernetes -Run OpenShell on Kubernetes as a distributed, multi-tenant application. +OpenShell runs on Kubernetes as a distributed, multi-tenant application. | Component | Supported version | Notes | | --------------------------------- | ------------------------------- | ----------------------------------------------------- | @@ -55,9 +59,9 @@ Run OpenShell on Kubernetes as a distributed, multi-tenant application. | Helm | 3.x | Required to install and upgrade the OpenShell chart. | | Agent Sandbox controller and CRDs | Compatible release; version TBD | Required before installing the OpenShell chart. | -Install the Agent Sandbox controller and its `Sandbox` CRDs before deploying -the OpenShell Helm chart. Refer to [Kubernetes setup](/kubernetes/setup) for -installation instructions. +Kubernetes deployments require the Agent Sandbox controller and its `Sandbox` +CRDs before the OpenShell Helm chart is installed. The +[Kubernetes setup guide](/kubernetes/setup) provides installation instructions. ### Distributions @@ -68,7 +72,7 @@ the required overrides. ## SDKs -Use the supported SDKs to connect to local or remote OpenShell deployments. +The supported SDKs connect to local or remote OpenShell deployments. | SDK | Minimum version | | ---------- | --------------- | From d2462266b3d7c90d4652c9c8550cb0168bc05bfa Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 10:36:33 -0700 Subject: [PATCH 11/21] docs: separate Linux runtime and kernel requirements Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 8dca7808c2..a735699636 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -19,7 +19,7 @@ setup instructions. | Platform | Installation methods | Versions | | ----------------------- | -------------------- | -------------------------------------------- | | macOS (Apple Silicon) | Homebrew | macOS 13.3 or later | -| Linux (x86_64, arm64) | APT/DEB, RPM, Snap | Linux kernel 5.13 or later | +| Linux (x86_64, arm64) | APT/DEB, RPM, Snap | glibc 2.28 or later | | Windows (x86_64, arm64) | MSI, WinGet | Windows minimum version: TBD; MSVC toolchain | The OpenShell client includes the CLI and TUI. Client binaries are built with @@ -44,9 +44,9 @@ the host kernel. | Kernel capability | Requirement | Minimum | Behavior when unavailable | | -------------------------------------- | ----------- | ------------------- | ------------------------------------------------------------------------------ | | seccomp BPF | Required | Linux 3.17 or later | Supervisor security initialization fails. | -| Network namespaces, veth, and nftables | Required | TBD | Network policy enforcement cannot start. | +| Network namespaces, veth, and nftables | Required | Linux 3.13 or later | Network policy enforcement cannot start. | | Landlock LSM | Recommended | Linux 5.13 or later | `best_effort` runs degraded with a security finding; `hard_requirement` fails. | -| cgroups v2 PID controller | Recommended | TBD | The compute driver or container runtime must provide PID limits. | +| cgroups v2 PID controller | Recommended | Linux 4.5 or later | The compute driver or container runtime must provide PID limits. | | User namespaces | Optional | Linux 5.12 or later | Stronger Kubernetes host isolation is unavailable. | ## Kubernetes From 5bf2d0f712b7ca98eca686abb5d4ea9730567f84 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 10:41:03 -0700 Subject: [PATCH 12/21] docs: describe MicroVM Linux support by capability Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index a735699636..2a1c6bebcd 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -28,12 +28,12 @@ downloaded and run without a local gateway or package manager. ## Compute Drivers -| Driver | Supported hosts | Minimum version | Requirements | -| ---------- | --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- | -| Docker | macOS, Linux, Windows | 28.0.4 or later | Docker Engine or Docker Desktop. | -| Podman | macOS, Linux, Windows | 5.x | Podman socket, rootless networking, and cgroups v2. | -| MicroVM | macOS, Linux | macOS 13.3 or later; Linux kernel 5.13 or later | Host virtualization enabled; `Hypervisor.framework` on macOS; KVM on Linux. | -| Kubernetes | Kubernetes clusters | 1.29 or later | See [Kubernetes](#kubernetes) for Helm, Agent Sandbox, and distribution requirements. | +| Driver | Supported hosts | Minimum version | Requirements | +| ---------- | --------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- | +| Docker | macOS, Linux, Windows | 28.0.4 or later | Docker Engine or Docker Desktop. | +| Podman | macOS, Linux, Windows | 5.x | Podman socket, rootless networking, and cgroups v2. | +| MicroVM | macOS, Linux | macOS 13.3 or later; KVM support on Linux | Host virtualization enabled; `Hypervisor.framework` on macOS; KVM on Linux. | +| Kubernetes | Kubernetes clusters | 1.29 or later | See [Kubernetes](#kubernetes) for Helm, Agent Sandbox, and distribution requirements. | ## Supervisor Kernel Requirements From 274e0a6902e9abaf46ba5ceb0432976f1715a1d0 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 11:03:53 -0700 Subject: [PATCH 13/21] docs: simplify supervisor kernel versions Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 2a1c6bebcd..1bc073a463 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -41,13 +41,13 @@ These requirements apply to the Linux environment running the supervisor. On macOS and Windows, they apply to the container or virtual machine kernel, not the host kernel. -| Kernel capability | Requirement | Minimum | Behavior when unavailable | -| -------------------------------------- | ----------- | ------------------- | ------------------------------------------------------------------------------ | -| seccomp BPF | Required | Linux 3.17 or later | Supervisor security initialization fails. | -| Network namespaces, veth, and nftables | Required | Linux 3.13 or later | Network policy enforcement cannot start. | -| Landlock LSM | Recommended | Linux 5.13 or later | `best_effort` runs degraded with a security finding; `hard_requirement` fails. | -| cgroups v2 PID controller | Recommended | Linux 4.5 or later | The compute driver or container runtime must provide PID limits. | -| User namespaces | Optional | Linux 5.12 or later | Stronger Kubernetes host isolation is unavailable. | +| Kernel capability | Requirement | Minimum | Behavior when unavailable | +| -------------------------------------- | ----------- | ------- | ------------------------------------------------------------------------------ | +| seccomp BPF | Required | 3.17 | Supervisor security initialization fails. | +| Network namespaces, veth, and nftables | Required | 3.13 | Network policy enforcement cannot start. | +| Landlock LSM | Recommended | 5.13 | `best_effort` runs degraded with a security finding; `hard_requirement` fails. | +| cgroups v2 PID controller | Recommended | 4.5 | The compute driver or container runtime must provide PID limits. | +| User namespaces | Optional | 5.12 | Stronger Kubernetes host isolation is unavailable. | ## Kubernetes From 2b462b9f239655843d42c7b250dba19b2c722b78 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 12:16:29 -0700 Subject: [PATCH 14/21] docs: add GPU support matrix Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 1bc073a463..8d74e9f178 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -2,13 +2,13 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Support Matrix" -description: "Review OpenShell compatibility across host platforms, Kubernetes environments, and SDKs." +description: "Review OpenShell compatibility across host platforms, compute drivers, GPU environments, Kubernetes, and SDKs." position: 5 --- OpenShell can run sandboxes on a local macOS, Linux, or Windows machine or as a distributed deployment on Kubernetes. The OpenShell CLI, TUI, and SDKs can manage a local gateway or connect to a remote gateway. This matrix lists the -supported platforms, runtimes, and client toolchains. +supported platforms, runtimes, GPU environments, and client toolchains. ## Platforms @@ -35,6 +35,24 @@ downloaded and run without a local gateway or package manager. | MicroVM | macOS, Linux | macOS 13.3 or later; KVM support on Linux | Host virtualization enabled; `Hypervisor.framework` on macOS; KVM on Linux. | | Kubernetes | Kubernetes clusters | 1.29 or later | See [Kubernetes](#kubernetes) for Helm, Agent Sandbox, and distribution requirements. | +## GPU Support + +OpenShell supports NVIDIA GPU-backed sandboxes across compute drivers when the +host or cluster exposes compatible devices. Any LTS CUDA release is supported, +with release validation focused on Tesla Recommended Driver (TRD) branches. +GPU-capable sandbox images provide the CUDA user-space libraries required by +the workload. + +| Compute driver | Supported environment | Device interface | Requirements and limits | +| -------------- | --------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| Docker | Linux; Windows through WSL2 | NVIDIA CDI | Docker CDI is enabled and NVIDIA devices are visible. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. | +| Podman | Linux; Windows through WSL2 | NVIDIA CDI | NVIDIA CDI devices are visible to Podman. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. | +| MicroVM | Linux | QEMU/VFIO PCI passthrough | The host provides IOMMU and VFIO support, root privileges, and a compatible sandbox image. Each sandbox supports one GPU. | +| Kubernetes | Linux GPU nodes | `nvidia.com/gpu` | The NVIDIA device plugin or GPU Operator exposes allocatable GPU capacity, and the sandbox image includes the required user-space libraries. | + +GPU requests use `--gpu`. [GPU resource management](/sandboxes/manage-sandboxes#gpu-resources) +describes default, counted, and exact-device requests. + ## Supervisor Kernel Requirements These requirements apply to the Linux environment running the supervisor. On From 87b4d69ae2b49c167caa15d9dc674cf627315a8f Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 12:25:25 -0700 Subject: [PATCH 15/21] docs: address support matrix review feedback Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 36 ++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 8d74e9f178..3bdc7fb8c0 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -16,16 +16,12 @@ OpenShell can be installed and run on macOS, Linux, or Windows using standard package installers. The [Installation guide](/about/installation) provides setup instructions. -| Platform | Installation methods | Versions | +| Platform | Installation methods | Requirements | | ----------------------- | -------------------- | -------------------------------------------- | | macOS (Apple Silicon) | Homebrew | macOS 13.3 or later | | Linux (x86_64, arm64) | APT/DEB, RPM, Snap | glibc 2.28 or later | | Windows (x86_64, arm64) | MSI, WinGet | Windows minimum version: TBD; MSVC toolchain | -The OpenShell client includes the CLI and TUI. Client binaries are built with -musl and are supported on macOS, Linux, and Windows. The client can be -downloaded and run without a local gateway or package manager. - ## Compute Drivers | Driver | Supported hosts | Minimum version | Requirements | @@ -35,6 +31,10 @@ downloaded and run without a local gateway or package manager. | MicroVM | macOS, Linux | macOS 13.3 or later; KVM support on Linux | Host virtualization enabled; `Hypervisor.framework` on macOS; KVM on Linux. | | Kubernetes | Kubernetes clusters | 1.29 or later | See [Kubernetes](#kubernetes) for Helm, Agent Sandbox, and distribution requirements. | +Docker and Podman pass the configured `sandbox_pids_limit` to the container +runtime. Sandbox creation fails if the runtime rejects the limit. A value of +`0` leaves the runtime default unchanged. + ## GPU Support OpenShell supports NVIDIA GPU-backed sandboxes across compute drivers when the @@ -59,13 +59,12 @@ These requirements apply to the Linux environment running the supervisor. On macOS and Windows, they apply to the container or virtual machine kernel, not the host kernel. -| Kernel capability | Requirement | Minimum | Behavior when unavailable | -| -------------------------------------- | ----------- | ------- | ------------------------------------------------------------------------------ | -| seccomp BPF | Required | 3.17 | Supervisor security initialization fails. | -| Network namespaces, veth, and nftables | Required | 3.13 | Network policy enforcement cannot start. | -| Landlock LSM | Recommended | 5.13 | `best_effort` runs degraded with a security finding; `hard_requirement` fails. | -| cgroups v2 PID controller | Recommended | 4.5 | The compute driver or container runtime must provide PID limits. | -| User namespaces | Optional | 5.12 | Stronger Kubernetes host isolation is unavailable. | +| Kernel capability | Requirement | Minimum | Behavior when unavailable | +| --------------------------------- | ----------- | ------- | ------------------------------------------------------------------------------ | +| seccomp BPF | Required | 3.17 | Supervisor security initialization fails. | +| Network namespaces and veth | Required | 3.13 | Supervisor initialization fails, and the sandbox does not become ready. | +| nftables bypass-detection rules | Recommended | 3.13 | The sandbox starts with bypass detection degraded and emits an OCSF configuration event. | +| Landlock LSM | Recommended | 5.13 | `best_effort` runs degraded with a security finding; `hard_requirement` fails. | ## Kubernetes @@ -81,6 +80,12 @@ Kubernetes deployments require the Agent Sandbox controller and its `Sandbox` CRDs before the OpenShell Helm chart is installed. The [Kubernetes setup guide](/kubernetes/setup) provides installation instructions. +User namespaces are optional. Without user namespace support, OpenShell policy +enforcement remains available, but Kubernetes cannot set `hostUsers: false` to +map container UID 0 to an unprivileged host UID. The +[User Namespace Isolation guidance](/security/best-practices#user-namespace-isolation) +describes prerequisites and security effects. + ### Distributions - GKE Standard and Autopilot clusters are supported. @@ -88,6 +93,13 @@ CRDs before the OpenShell Helm chart is installed. The configuration. Refer to [OpenShift installation](/kubernetes/openshift) for the required overrides. +## CLI and TUI Clients + +Package installers install the OpenShell CLI, TUI, and gateway and start a local +gateway service. Standalone CLI and TUI binaries are also available from +[GitHub Releases](https://github.com/NVIDIA/OpenShell/releases) and can connect +to a remote gateway without running a local gateway. + ## SDKs The supported SDKs connect to local or remote OpenShell deployments. From 85dd7a52774cde03a8034d84b4e58ea3c898bbfb Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 12:38:09 -0700 Subject: [PATCH 16/21] docs: move user namespace support into table Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 3bdc7fb8c0..f577d1677c 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -75,17 +75,12 @@ OpenShell runs on Kubernetes as a distributed, multi-tenant application. | Kubernetes | 1.29 or later | Required for Helm deployments and sandbox scheduling. | | Helm | 3.x | Required to install and upgrade the OpenShell chart. | | Agent Sandbox controller and CRDs | Compatible release; version TBD | Required before installing the OpenShell chart. | +| User namespaces | 1.33 or later | Optional. Policy enforcement remains available without support, but Kubernetes cannot set `hostUsers: false` for UID remapping. See [User Namespace Isolation guidance](/security/best-practices#user-namespace-isolation). | Kubernetes deployments require the Agent Sandbox controller and its `Sandbox` CRDs before the OpenShell Helm chart is installed. The [Kubernetes setup guide](/kubernetes/setup) provides installation instructions. -User namespaces are optional. Without user namespace support, OpenShell policy -enforcement remains available, but Kubernetes cannot set `hostUsers: false` to -map container UID 0 to an unprivileged host UID. The -[User Namespace Isolation guidance](/security/best-practices#user-namespace-isolation) -describes prerequisites and security effects. - ### Distributions - GKE Standard and Autopilot clusters are supported. From 4d36a5ea0eca1bef7d0010a0e908613f417e1a9f Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 6 Jul 2026 12:47:17 -0700 Subject: [PATCH 17/21] docs: remove misplaced PID limit detail Signed-off-by: Drew Newberry --- docs/reference/support-matrix.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index f577d1677c..28566b6998 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -31,10 +31,6 @@ setup instructions. | MicroVM | macOS, Linux | macOS 13.3 or later; KVM support on Linux | Host virtualization enabled; `Hypervisor.framework` on macOS; KVM on Linux. | | Kubernetes | Kubernetes clusters | 1.29 or later | See [Kubernetes](#kubernetes) for Helm, Agent Sandbox, and distribution requirements. | -Docker and Podman pass the configured `sandbox_pids_limit` to the container -runtime. Sandbox creation fails if the runtime rejects the limit. A value of -`0` leaves the runtime default unchanged. - ## GPU Support OpenShell supports NVIDIA GPU-backed sandboxes across compute drivers when the From 6a1b6daec1d67e84c49f1f824efcd514d245fcb9 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Thu, 9 Jul 2026 00:15:33 -0700 Subject: [PATCH 18/21] Update docs/reference/support-matrix.mdx Co-authored-by: Evan Lezar --- docs/reference/support-matrix.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 28566b6998..58296115a0 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -44,7 +44,7 @@ the workload. | Docker | Linux; Windows through WSL2 | NVIDIA CDI | Docker CDI is enabled and NVIDIA devices are visible. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. | | Podman | Linux; Windows through WSL2 | NVIDIA CDI | NVIDIA CDI devices are visible to Podman. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. | | MicroVM | Linux | QEMU/VFIO PCI passthrough | The host provides IOMMU and VFIO support, root privileges, and a compatible sandbox image. Each sandbox supports one GPU. | -| Kubernetes | Linux GPU nodes | `nvidia.com/gpu` | The NVIDIA device plugin or GPU Operator exposes allocatable GPU capacity, and the sandbox image includes the required user-space libraries. | +| Kubernetes | Linux GPU nodes | `nvidia.com/gpu` extended resources | The NVIDIA GPU Device Plugin (e.g. installed by the GPU Operator) exposes allocatable GPU capacity, and the sandbox image includes the required user-space libraries. | GPU requests use `--gpu`. [GPU resource management](/sandboxes/manage-sandboxes#gpu-resources) describes default, counted, and exact-device requests. From da3decee288d5ae5a9e01d806466f560160fcf66 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Thu, 9 Jul 2026 00:15:42 -0700 Subject: [PATCH 19/21] Update docs/reference/support-matrix.mdx Co-authored-by: Evan Lezar --- docs/reference/support-matrix.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 58296115a0..b16a849db3 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -41,7 +41,7 @@ the workload. | Compute driver | Supported environment | Device interface | Requirements and limits | | -------------- | --------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| Docker | Linux; Windows through WSL2 | NVIDIA CDI | Docker CDI is enabled and NVIDIA devices are visible. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. | +| Docker | Linux; Windows through WSL2 | NVIDIA CDI | Docker is CDI-enabled and NVIDIA devices are visible. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. | | Podman | Linux; Windows through WSL2 | NVIDIA CDI | NVIDIA CDI devices are visible to Podman. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. | | MicroVM | Linux | QEMU/VFIO PCI passthrough | The host provides IOMMU and VFIO support, root privileges, and a compatible sandbox image. Each sandbox supports one GPU. | | Kubernetes | Linux GPU nodes | `nvidia.com/gpu` extended resources | The NVIDIA GPU Device Plugin (e.g. installed by the GPU Operator) exposes allocatable GPU capacity, and the sandbox image includes the required user-space libraries. | From 42859cc499084f6adc37dd2d73f72827dddb0351 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Thu, 9 Jul 2026 00:15:57 -0700 Subject: [PATCH 20/21] Update docs/reference/support-matrix.mdx Co-authored-by: Evan Lezar --- docs/reference/support-matrix.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index b16a849db3..f2daa5ded8 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -34,7 +34,7 @@ setup instructions. ## GPU Support OpenShell supports NVIDIA GPU-backed sandboxes across compute drivers when the -host or cluster exposes compatible devices. Any LTS CUDA release is supported, +host or cluster exposes compatible devices through a supported mechanism. Any current CUDA driver is supported, with release validation focused on Tesla Recommended Driver (TRD) branches. GPU-capable sandbox images provide the CUDA user-space libraries required by the workload. From d575cf85f8c520774cc3e307ec1bcdabf57cd682 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Thu, 9 Jul 2026 00:18:54 -0700 Subject: [PATCH 21/21] Update docs/reference/api-compatibility.mdx Co-authored-by: Evan Lezar --- docs/reference/api-compatibility.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/api-compatibility.mdx b/docs/reference/api-compatibility.mdx index e3799bfb1d..7482d8eac0 100644 --- a/docs/reference/api-compatibility.mdx +++ b/docs/reference/api-compatibility.mdx @@ -13,7 +13,7 @@ Interceptor, and Middleware APIs. | Release phase | Compatibility policy | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release includes migration guidance and coordinated SDK updates. | +| Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in a preceding minor release. The release includes migration guidance and coordinated SDK updates. | | Stable | Minor and patch releases are backward compatible within an API major version. Breaking changes use a new versioned Protobuf package and API major version. The previous stable API remains supported for at least 12 months or two minor releases after its replacement, whichever is longer. | ## Change Policy