fix(linux): lower host glibc floor to 2.28 to support RHEL/Rocky 8

.github/workflows/driver-vm-linux.yml

@@ -81,13 +81,13 @@ jobs:
           - arch: arm64
             runner: linux-arm64-cpu8
             target: aarch64-unknown-linux-gnu
-            zig_target: aarch64-unknown-linux-gnu.2.31
+            zig_target: aarch64-unknown-linux-gnu.2.28
             platform: linux-aarch64
             guest_arch: aarch64
           - arch: amd64
             runner: linux-amd64-cpu8
             target: x86_64-unknown-linux-gnu
-            zig_target: x86_64-unknown-linux-gnu.2.31
+            zig_target: x86_64-unknown-linux-gnu.2.28
             platform: linux-x86_64
             guest_arch: x86_64
     runs-on: ${{ matrix.runner }}
@@ -165,7 +165,7 @@ jobs:
           set -euo pipefail
           sed -i -E '/^\[workspace\.package\]/,/^\[/{s/^version[[:space:]]*=[[:space:]]*".*"/version = "'"${{ inputs['cargo-version'] }}"'"/}' Cargo.toml
 
-      - name: Build openshell-driver-vm with glibc 2.31 floor
+      - name: Build openshell-driver-vm with glibc 2.28 floor
         run: |
           set -euo pipefail
           mise x -- rustup target add ${{ matrix.target }}
@@ -182,7 +182,7 @@ jobs:
           grep -q '^openshell-driver-vm ' <<<"$OUTPUT"
 
       - name: Verify glibc symbol floor
-        run: tasks/scripts/verify-glibc-symbols.sh 2.31 artifacts/bin/openshell-driver-vm
+        run: tasks/scripts/verify-glibc-symbols.sh 2.28 artifacts/bin/openshell-driver-vm
 
       - name: sccache stats
         if: always()

.github/workflows/release-dev.yml

@@ -376,7 +376,7 @@ jobs:
           retention-days: 5
 
   # ---------------------------------------------------------------------------
-  # Build standalone gateway binaries (Linux GNU — glibc 2.31 floor)
+  # Build standalone gateway binaries (Linux GNU — glibc 2.28 floor)
   # ---------------------------------------------------------------------------
   build-gateway-binary-linux:
     name: Build Gateway Binary (Linux ${{ matrix.arch }})
@@ -387,11 +387,11 @@ jobs:
           - arch: amd64
             runner: linux-amd64-cpu8
             target: x86_64-unknown-linux-gnu
-            zig_target: x86_64-unknown-linux-gnu.2.31
+            zig_target: x86_64-unknown-linux-gnu.2.28
           - arch: arm64
             runner: linux-arm64-cpu8
             target: aarch64-unknown-linux-gnu
-            zig_target: aarch64-unknown-linux-gnu.2.31
+            zig_target: aarch64-unknown-linux-gnu.2.28
     runs-on: ${{ matrix.runner }}
     timeout-minutes: 60
     container:
@@ -419,7 +419,7 @@ jobs:
       - name: Cache Rust target and registry
         uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2
         with:
-          shared-key: gateway-binary-gnu-${{ matrix.arch }}
+          shared-key: gateway-binary-gnu-${{ matrix.arch }}-zig-wrapper-${{ hashFiles('tasks/scripts/setup-zig-cc-wrapper.sh') }}
           cache-directories: .cache/sccache
           cache-targets: "true"
 
@@ -429,6 +429,9 @@ jobs:
           set -euo pipefail
           sed -i -E '/^\[workspace\.package\]/,/^\[/{s/^version[[:space:]]*=[[:space:]]*".*"/version = "'"${{ needs.compute-versions.outputs.cargo_version }}"'"/}' Cargo.toml
 
+      - name: Set up Zig C/C++ wrappers
+        run: tasks/scripts/setup-zig-cc-wrapper.sh ${{ matrix.zig_target }} ${{ matrix.zig_target }} /tmp/zig-gnu
+
       - name: Build ${{ matrix.zig_target }}
         env:
           OPENSHELL_IMAGE_TAG: ${{ github.sha }}
@@ -452,7 +455,7 @@ jobs:
           fi
 
       - name: Verify glibc symbol floor
-        run: tasks/scripts/verify-glibc-symbols.sh 2.31 artifacts/bin/openshell-gateway
+        run: tasks/scripts/verify-glibc-symbols.sh 2.28 artifacts/bin/openshell-gateway
 
       - name: sccache stats
         if: always()
@@ -676,7 +679,7 @@ jobs:
 
   smoke-linux-dev-artifacts:
     name: Smoke Linux Dev Artifacts (${{ matrix.name }})
-    needs: [build-gateway-binary-linux, build-driver-vm-linux, build-deb]
+    needs: [build-gateway-binary-linux, build-driver-vm-linux, build-deb, build-rpm]
     timeout-minutes: 20
     strategy:
       fail-fast: false
@@ -685,29 +688,61 @@ jobs:
           - name: ubuntu-22.04-deb-amd64
             runner: linux-amd64-cpu8
             image: ubuntu:22.04
+            kind: deb
             artifact_arch: amd64
+            rpm_arch: x86_64
           - name: ubuntu-22.04-deb-arm64
             runner: linux-arm64-cpu8
             image: ubuntu:22.04
+            kind: deb
             artifact_arch: arm64
+            rpm_arch: aarch64
+          - name: fedora-rpm-amd64
+            runner: linux-amd64-cpu8
+            image: fedora:latest
+            kind: rpm
+            artifact_arch: amd64
+            rpm_arch: x86_64
+          - name: fedora-rpm-arm64
+            runner: linux-arm64-cpu8
+            image: fedora:latest
+            kind: rpm
+            artifact_arch: arm64
+            rpm_arch: aarch64
     runs-on: ${{ matrix.runner }}
     container:
       image: ${{ matrix.image }}
     steps:
       - name: Download Debian package artifact
+        if: matrix.kind == 'deb'
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: deb-linux-${{ matrix.artifact_arch }}
           path: package-input/
 
       - name: Smoke Debian package on Ubuntu 22.04
+        if: matrix.kind == 'deb'
         run: |
           set -euo pipefail
           apt-get update
           apt-get install -y --no-install-recommends ./package-input/*.deb
-          openshell-gateway --version
+          LD_BIND_NOW=1 openshell-gateway --version
           /usr/libexec/openshell/openshell-driver-vm --version
 
+      - name: Download RPM package artifacts
+        if: matrix.kind == 'rpm'
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: rpm-linux-${{ matrix.rpm_arch }}
+          path: package-input/
+
+      - name: Smoke RPM packages on Fedora
+        if: matrix.kind == 'rpm'
+        run: |
+          set -euo pipefail
+          dnf install -y ./package-input/openshell-[0-9]*.rpm ./package-input/openshell-gateway-*.rpm
+          LD_BIND_NOW=1 openshell-gateway --version
+
   # ---------------------------------------------------------------------------
   # Create / update the dev GitHub Release with CLI, gateway, driver, and wheels
   # ---------------------------------------------------------------------------

.github/workflows/release-tag.yml

@@ -409,7 +409,7 @@ jobs:
           retention-days: 5
 
   # ---------------------------------------------------------------------------
-  # Build standalone gateway binaries (Linux GNU — glibc 2.31 floor)
+  # Build standalone gateway binaries (Linux GNU — glibc 2.28 floor)
   # ---------------------------------------------------------------------------
   build-gateway-binary-linux:
     name: Build Gateway Binary (Linux ${{ matrix.arch }})
@@ -420,11 +420,11 @@ jobs:
           - arch: amd64
             runner: linux-amd64-cpu8
             target: x86_64-unknown-linux-gnu
-            zig_target: x86_64-unknown-linux-gnu.2.31
+            zig_target: x86_64-unknown-linux-gnu.2.28
           - arch: arm64
             runner: linux-arm64-cpu8
             target: aarch64-unknown-linux-gnu
-            zig_target: aarch64-unknown-linux-gnu.2.31
+            zig_target: aarch64-unknown-linux-gnu.2.28
     runs-on: ${{ matrix.runner }}
     timeout-minutes: 60
     container:
@@ -453,7 +453,7 @@ jobs:
       - name: Cache Rust target and registry
         uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2
         with:
-          shared-key: gateway-binary-gnu-${{ matrix.arch }}
+          shared-key: gateway-binary-gnu-${{ matrix.arch }}-zig-wrapper-${{ hashFiles('tasks/scripts/setup-zig-cc-wrapper.sh') }}
           cache-directories: .cache/sccache
           cache-targets: "true"
 
@@ -463,6 +463,9 @@ jobs:
           set -euo pipefail
           sed -i -E '/^\[workspace\.package\]/,/^\[/{s/^version[[:space:]]*=[[:space:]]*".*"/version = "'"${{ needs.compute-versions.outputs.cargo_version }}"'"/}' Cargo.toml
 
+      - name: Set up Zig C/C++ wrappers
+        run: tasks/scripts/setup-zig-cc-wrapper.sh ${{ matrix.zig_target }} ${{ matrix.zig_target }} /tmp/zig-gnu
+
       - name: Build ${{ matrix.zig_target }}
         env:
           OPENSHELL_IMAGE_TAG: ${{ needs.compute-versions.outputs.source_sha }}
@@ -481,12 +484,12 @@ jobs:
           grep -q '^openshell-gateway ' <<<"$OUTPUT"
           ldd artifacts/bin/openshell-gateway || true
           if ldd artifacts/bin/openshell-gateway | grep -q 'libz3'; then
-            echo "gateway binary must not depend on shared libz3; build with bundled-z3" >&2
+            echo "gateway binary must not require shared libz3; keep z3 bundled for portable release artifacts" >&2
             exit 1
           fi
 
       - name: Verify glibc symbol floor
-        run: tasks/scripts/verify-glibc-symbols.sh 2.31 artifacts/bin/openshell-gateway
+        run: tasks/scripts/verify-glibc-symbols.sh 2.28 artifacts/bin/openshell-gateway
 
       - name: sccache stats
         if: always()
@@ -782,10 +785,11 @@ jobs:
         if: matrix.kind == 'binary'
         run: |
           set -euo pipefail
+          apt-get update
           mkdir -p smoke-bin
           tar -xzf smoke-input/openshell-gateway-${{ matrix.target }}.tar.gz -C smoke-bin
           tar -xzf smoke-input/openshell-driver-vm-${{ matrix.target }}.tar.gz -C smoke-bin
-          smoke-bin/openshell-gateway --version
+          LD_BIND_NOW=1 smoke-bin/openshell-gateway --version
           smoke-bin/openshell-driver-vm --version
 
       - name: Download Debian package artifact
@@ -801,7 +805,7 @@ jobs:
           set -euo pipefail
           apt-get update
           apt-get install -y --no-install-recommends ./package-input/*.deb
-          openshell-gateway --version
+          LD_BIND_NOW=1 openshell-gateway --version
           /usr/libexec/openshell/openshell-driver-vm --version
 
       - name: Download RPM package artifacts
@@ -816,7 +820,7 @@ jobs:
         run: |
           set -euo pipefail
           dnf install -y ./package-input/openshell-[0-9]*.rpm ./package-input/openshell-gateway-*.rpm
-          openshell-gateway --version
+          LD_BIND_NOW=1 openshell-gateway --version
 
   # ---------------------------------------------------------------------------
   # Create a tagged GitHub Release with CLI, gateway, driver, and wheels

.github/workflows/rust-native-build.yml

@@ -7,7 +7,7 @@ name: Rust Image Binary Build (openshell-gateway / openshell-sandbox / openshell
 # consumes them as prebuilt artifacts. Gateway images use GNU-linked binaries
 # for the NVIDIA distroless C/C++ runtime; supervisor and cli images use musl/static
 # binaries so the final image can remain scratch. Gateway GNU binaries are
-# built with an explicit glibc 2.31 floor so image, package, and tarball
+# built with an explicit glibc 2.28 floor so image, package, and tarball
 # artifacts share the same host portability contract.
 
 on:
@@ -139,7 +139,7 @@ jobs:
                 zig_target=x86_64-linux-musl
               else
                 target=x86_64-unknown-linux-gnu
-                zig_target=x86_64-unknown-linux-gnu.2.31
+                zig_target=x86_64-unknown-linux-gnu.2.28
               fi
               ;;
             arm64)
@@ -148,7 +148,7 @@ jobs:
                 zig_target=aarch64-linux-musl
               else
                 target=aarch64-unknown-linux-gnu
-                zig_target=aarch64-unknown-linux-gnu.2.31
+                zig_target=aarch64-unknown-linux-gnu.2.28
               fi
               ;;
             *)
@@ -167,7 +167,7 @@ jobs:
       - name: Cache Rust target and registry
         uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2
         with:
-          shared-key: rust-native-${{ inputs.component }}-${{ inputs.arch }}
+          shared-key: rust-native-${{ inputs.component }}-${{ inputs.arch }}-zig-wrapper-${{ hashFiles('tasks/scripts/setup-zig-cc-wrapper.sh') }}
           cache-directories: .cache/sccache
           cache-targets: "true"
 
@@ -211,6 +211,10 @@ jobs:
           echo "CARGO_TARGET_${TARGET_ENV_UPPER}_LINKER=/tmp/zig-musl/cc" >> "$GITHUB_ENV"
           echo "CARGO_TARGET_${TARGET_ENV_UPPER}_RUSTFLAGS=-Clink-self-contained=no" >> "$GITHUB_ENV"
 
+      - name: Set up zig glibc wrappers
+        if: inputs.component == 'gateway'
+        run: tasks/scripts/setup-zig-cc-wrapper.sh "${{ steps.target.outputs.zig_target }}" "${{ steps.target.outputs.zig_target }}" /tmp/zig-gnu
+
       - name: Build ${{ steps.target.outputs.binary }} (${{ steps.target.outputs.zig_target || steps.target.outputs.target }})
         env:
           # Preserve the release-codegen setting used by the old Dockerfile
@@ -226,13 +230,17 @@ jobs:
           fi
 
           mise x -- rustup target add "${{ steps.target.outputs.target }}"
+
           cargo_cmd=(cargo build)
           build_target="${{ steps.target.outputs.target }}"
+          args=()
+
           if [[ "${{ inputs.component }}" == "gateway" ]]; then
             cargo_cmd=(cargo zigbuild)
             build_target="${{ steps.target.outputs.zig_target }}"
+            args+=(--features bundled-z3)
           fi
-          args=(
+          args+=(
             --release
             --target "$build_target"
             -p "${{ steps.target.outputs.crate }}"
@@ -266,7 +274,7 @@ jobs:
         run: |
           set -euo pipefail
           BIN="target/${{ steps.target.outputs.target }}/release/${{ steps.target.outputs.binary }}"
-          tasks/scripts/verify-glibc-symbols.sh 2.31 "$BIN"
+          tasks/scripts/verify-glibc-symbols.sh 2.28 "$BIN"
 
       - name: Stage binary for prebuilt layout
         run: |

architecture/build.md

@@ -44,9 +44,11 @@ disable telemetry in a default (telemetry-enabled) build.
 OpenShell uses different Linux libc environments for different host artifacts.
 The standalone `openshell` CLI is built as a static musl binary so it can run on
 a wide range of Linux distributions without depending on the host's glibc. Host
-runtime binaries that use the GNU/Linux runtime environment, including
-`openshell-gateway` and `openshell-driver-vm`, are GNU-linked and built with a
-glibc 2.31 floor.
+runtime binaries that use the GNU/Linux runtime environment are GNU-linked.
+`openshell-gateway` and `openshell-driver-vm` are built with a glibc 2.28 floor.
+The gateway bundles z3 into the release binary so Linux packages, standalone
+tarballs, and gateway images do not depend on distro-specific z3 shared-library
+SONAMEs.
 
 ## Container Builds
 
@@ -58,24 +60,34 @@ Dockerfile compiles Rust — both copy a staged binary out of
 `deploy/docker/.build/prebuilt-binaries/<arch>/` into the final image.
 
 Binary staging is driven by `tasks/scripts/stage-prebuilt-binaries.sh`. Gateway
-binaries use `cargo zigbuild` with GNU targets pinned to glibc 2.31, including
+binaries use `cargo zigbuild` with GNU targets pinned to glibc 2.28, including
 native-architecture builds, so the gateway image, standalone tarballs, and Linux
-packages share the same host portability floor. Supervisor binaries remain
-static musl and use `cargo zigbuild` when available, including native CPU
-architectures, so C dependencies are compiled for the musl target instead of the
-host GNU libc target. Local Docker image tasks infer the target architecture from
-`DOCKER_PLATFORM` when set, otherwise from the container engine host metadata
-with the kernel architecture as the fallback. CI invokes the same staging step
-via the `rust-native-build.yml` workflow (per-architecture, per-component) and
-uploads the result as an artifact that the image build job downloads back into
-the staging directory before running Buildx.
+packages share the same host portability floor. The gateway build enables
+`bundled-z3`. Linux VM driver release artifacts use the same glibc floor so
+package-managed VM support does not raise the package runtime requirement.
+Release workflows verify the maximum referenced `GLIBC_*` symbol version before
+publishing artifacts.
+Supervisor binaries remain static musl and use `cargo zigbuild` when available,
+including native CPU architectures, so C dependencies are compiled for the musl
+target instead of the host GNU libc target. Local Docker image tasks infer the
+target architecture from `DOCKER_PLATFORM` when set, otherwise from the
+container engine host metadata with the kernel architecture as the fallback. CI
+invokes the same staging step via the `rust-native-build.yml` workflow
+(per-architecture, per-component) and uploads the result as an artifact that the
+image build job downloads back into the staging directory before running Buildx.
 
 Runtime layout:
 
 - **Gateway**: `gcr.io/distroless/cc-debian13:nonroot` base, GNU-linked binary at
   `/usr/local/bin/openshell-gateway`, runs as UID/GID `1000:1000`. Linux GNU
-  gateway and VM driver binaries must not reference `GLIBC_*` symbols newer than
-  `GLIBC_2.31`; release workflows verify this before publishing artifacts.
+  gateway binaries must not reference `GLIBC_*` symbols newer than
+  `GLIBC_2.28`; release workflows verify this before publishing artifacts. The
+  gateway bundles z3, so the image does not need a distro-provided z3 runtime.
+- **VM driver**: host GNU-linked binary installed at
+  `/usr/libexec/openshell/openshell-driver-vm` in Linux packages and published
+  as a release artifact. Linux GNU VM driver binaries must not reference
+  `GLIBC_*` symbols newer than `GLIBC_2.28`; release workflows verify this
+  before publishing artifacts.
 - **Supervisor**: `scratch` base, static musl binary at `/openshell-sandbox`.
   Static linkage is required because the image is mounted/extracted into
   sandbox environments (Docker extraction, Podman image volumes, Kubernetes

docs/about/installation.mdx

@@ -55,7 +55,7 @@ On Fedora and RHEL, the install script uses RPM packages. The RPM installs the `
 
 On Debian and Ubuntu, the install script uses a Debian package. The Debian package installs the `openshell` CLI, the `openshell-gateway` daemon, VM sandbox support, and a systemd user service.
 
-Linux packages require glibc 2.31 or newer. The installer checks libc before downloading packages and exits with an error on older glibc versions, Alpine, musl-based distributions, or unknown libc environments.
+Linux packages require glibc 2.28 or newer. The installer checks libc before downloading packages and exits with an error on older glibc versions, Alpine, musl-based distributions, or unknown libc environments.
 
 The Linux user service listens on `https://127.0.0.1:17670`, starts from built-in defaults, and generates a local mTLS bundle before the gateway starts. Create `~/.config/openshell/gateway.toml` only when you need to override those defaults.
 

docs/reference/support-matrix.mdx

@@ -33,7 +33,7 @@ OpenShell publishes standalone `openshell-gateway` release assets for manual dow
 
 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.31 or newer. Compatible systems include, for example, Ubuntu 20.04+, RHEL 9+, Amazon Linux 2023+, and Fedora 32+.
+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+.
 
 ## Compute Drivers