Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

docs(relay): clarify stable plugin bundle installation and validation (#746)

Bryan Bednarski3ddea9d30174
diff --git a/crates/switchyard-nemo-relay-plugin/README.md b/crates/switchyard-nemo-relay-plugin/README.md
index fa1aaedd9..ff4d43b8c 100644
--- a/crates/switchyard-nemo-relay-plugin/README.md
+++ b/crates/switchyard-nemo-relay-plugin/README.md
@@ -14,18 +14,35 @@ The plugin requires NeMo Relay `>=0.8.0, <1.0.0`.
### Install a released bundle
-Released bundles are published in the
+Official plugin bundles are distributed through the
[NeMo Relay Plugins repository](https://github.com/NVIDIA/NeMo-Relay-Plugins/releases).
-Find the `switchyard-plugin` release that corresponds to the Switchyard version
-or source commit you need. The release's `.json` sidecar records the exact
-Switchyard source commit and Relay version used to validate each platform
-artifact.
-
-Download the archive and matching `.sha256` file for your platform, verify the
-checksum, extract the archive into a directory you plan to keep, then register
-the extracted `relay-plugin.toml` with Relay using step 3 below. The release
-version is independent of the Switchyard workspace version, so use the release
-metadata rather than assuming that version numbers match.
+Each bundle includes the native library, a completed `relay-plugin.toml`, the
+configuration schema, and license notices. Installing a bundle requires no
+Rust build or separate `switchyard-nemo-relay-plugin` crate installation.
+
+The repository currently requires NVIDIA GitHub repository access. Sign in
+with an account that has access and complete organization SSO/SAML authorization
+where required, including for credentials used by `gh`. An HTTP 404 can mean
+that your account or credentials lack access; it does not prove that a bundle
+is missing.
+
+1. Select a published `switchyard-plugin-<version>` release for Switchyard
+ `0.3.0`. Plugin versions are managed separately and can match the Switchyard
+ version. Confirm the source commit in the release notes and `.json` metadata
+ rather than relying on the version number alone. A Switchyard release does
+ not itself publish a plugin bundle. If no matching published bundle is
+ available, use [Build from source](#build-from-source).
+2. Download the archive for your platform and its matching `.sha256` and `.json`
+ sidecars. For Linux x86_64, the archive is named
+ `switchyard-plugin-<version>-linux-x86_64.tar.gz`. Check the metadata's
+ `source_commit`, `platform`, and `relay` fields for the source and tested host.
+3. Verify the downloaded archive against its `.sha256` file before extracting
+ it. On Linux, run `sha256sum -c <archive>.sha256` from the download directory,
+ replacing `<archive>` with the archive's filename.
+4. Extract the archive into a directory you plan to keep, then follow
+ [Register and enable the plugin](#register-and-enable-the-plugin). Use the
+ actual path to the extracted `relay-plugin.toml`; the examples below use
+ `./plugins/switchyard/relay-plugin.toml`.
### Build from source
@@ -68,7 +85,11 @@ python crates/switchyard-nemo-relay-plugin/scripts/package_bundle.py \
Pass `--archive switchyard-plugin.tar.gz` (or `.zip`) to also produce an
archive for distribution.
-**3. Register the plugin.**
+### Register and enable the plugin
+
+These steps apply to both a downloaded bundle and a bundle built from source.
+
+**1. Register the plugin.**
```bash
nemo-relay plugins validate ./plugins/switchyard/relay-plugin.toml
@@ -80,10 +101,10 @@ nemo-relay plugins add --user ./plugins/switchyard/relay-plugin.toml
The plugin is not enabled yet; enabling before the deployment is configured
fails validation because the plugin requires a Switchyard configuration.
-**4. Configure the deployment and trust policy** in that `plugins.toml`, as
+**2. Configure the deployment and trust policy** in that `plugins.toml`, as
described in [Configure Relay](#configure-relay).
-**5. Enable and validate the plugin**, then restart Relay. The manifest ships
+**3. Enable and validate the plugin**, then restart Relay. The manifest ships
with `enabled = false`; Relay validates a disabled plugin but never loads it.
```bash
diff --git a/docs/integrations/nemo_relay.md b/docs/integrations/nemo_relay.md
index be96a9da5..aec8465c7 100644
--- a/docs/integrations/nemo_relay.md
+++ b/docs/integrations/nemo_relay.md
@@ -125,11 +125,27 @@ and
## Set Up the Plugin
-Follow the [plugin README](../../crates/switchyard-nemo-relay-plugin/README.md)
-to install a released bundle from the
-[NeMo Relay Plugins repository](https://github.com/NVIDIA/NeMo-Relay-Plugins/releases)
-or build and package the native library from source, then register and enable
-it in Relay and configure its deployment. Relay documents how to
+For Switchyard `0.3.0`, select a matching published `switchyard-plugin` bundle
+from the
+[NeMo Relay Plugins releases](https://github.com/NVIDIA/NeMo-Relay-Plugins/releases).
+Confirm its Switchyard source commit in the release metadata. Plugin versions
+are managed separately and can match the Switchyard version. The bundle
+includes the native library, completed manifest, schema, and license notices;
+no separate plugin crate installation is needed.
+
+The repository currently requires NVIDIA GitHub repository access and
+organization SSO/SAML authorization where required. An HTTP 404 can indicate
+missing access. A Switchyard release does not guarantee that a matching plugin
+bundle has been published.
+
+Follow the
+[bundle installation steps](../../crates/switchyard-nemo-relay-plugin/README.md#install-a-released-bundle)
+to download the archive and sidecars, verify the checksum, and extract the
+bundle. If a matching published bundle is unavailable or you need a custom
+build, follow
+[Build from source](../../crates/switchyard-nemo-relay-plugin/README.md#build-from-source).
+Then register the manifest, configure the deployment and trust policy, enable
+the plugin, and restart Relay. Relay documents how to
[add and enable a discoverable plugin](https://docs.nvidia.com/nemo/relay/configure-plugins/discoverable-plugins#add-and-enable-a-plugin)
and how it
[validates the package before loading code](https://docs.nvidia.com/nemo/relay/configure-plugins/discoverable-plugins#validate-before-loading-code).
diff --git a/docs/internal/release_workflow.md b/docs/internal/release_workflow.md
index 10285724b..0d0ae38ed 100644
--- a/docs/internal/release_workflow.md
+++ b/docs/internal/release_workflow.md
@@ -102,6 +102,42 @@ can publish all seven crates and create new crates. The job waits for each versi
crates.io index before publishing its dependents. If publication stops partway through, use
GitHub's **Re-run failed jobs** action so successful crate jobs are not repeated.
+## Relay Plugin Bundles
+
+Official Relay plugin bundles are built and distributed by
+[NeMo Relay Plugins](https://github.com/NVIDIA/NeMo-Relay-Plugins/releases).
+They contain the native library, completed manifest, schema, and license
+notices. This delivery path does not require publishing
+`switchyard-nemo-relay-plugin` to crates.io or adding it to the crate list above.
+
+For Switchyard `0.3.0`, coordinate a plugin release pinned to the intended
+Switchyard release commit. The plugin's `release.toml` records its own version
+and `source.sha`. Versions can match, but the source pin establishes which
+Switchyard code is bundled. Follow the plugin repository's
+[release process](https://github.com/NVIDIA/NeMo-Relay-Plugins/blob/main/RELEASE.md)
+to review and publish its draft. A Switchyard tag alone does not publish it.
+
+Keep source-build validation and published-bundle validation as separate QA
+results. Before publication, build and package the exact source revision under
+test. Passing that path does not validate the eventual downloaded archive,
+sidecars, or repository access. Keep published-bundle validation pending until
+the official release is available.
+
+After publication, validate the delivery path from
+[the user installation guide](../../crates/switchyard-nemo-relay-plugin/README.md#install-a-released-bundle):
+
+1. Confirm the intended users can access the published release. Verify the
+ documented repository access and SSO/SAML requirements.
+2. Download each supported platform's archive and matching `.sha256` and
+ `.json` sidecars from that release. Verify the archive checksum and check
+ the metadata's source commit, platform, and tested Relay version.
+3. Extract the downloaded archive into a fresh installation directory. Follow
+ the documented registration, deployment configuration, trust policy, and
+ enablement steps using a supported official Relay runtime.
+4. Restart Relay and run a routed-request smoke test with the installed bundle.
+ Record the release tag, source commit, archive checksum, platform, Relay
+ version, and result. A local rebuild is not a substitute for this check.
+
## Local Metadata Helper
To preview the metadata stamp locally: