feat(install): install the snap package by default when supported

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

@@ -16,8 +16,8 @@ The Release Canary (`.github/workflows/release-canary.yml`) smoke-tests the arti
 | `macos` | `macos-latest-xlarge` | Installs the dev Homebrew artifacts, reaches the VM gateway, and creates, executes in, and deletes a sandbox. |
 | `ubuntu-deb` | `ubuntu-latest` | Installs the dev Debian package, reaches the Docker gateway, and creates, executes in, and deletes a sandbox. |
 | `fedora` | `fedora:latest` container | Installs the dev RPM packages, reaches the Podman gateway, and creates, executes in, and deletes a sandbox. |
-| `ubuntu-snap-system-docker` | `ubuntu-latest` | Uses `install.sh` to install the snap from `latest/edge`, reuses system Docker, verifies the packaged prover version and a local policy boundary check, reaches the Docker gateway, creates, executes in, and deletes a sandbox, and verifies that the Docker snap is not installed. |
-| `ubuntu-snap-docker-preflight` | `ubuntu-latest` | Verifies that `install.sh` rejects the OpenShell snap path when Docker is absent or supplied by the Docker snap, without installing OpenShell. |
+| `ubuntu-snap-system-docker` | `ubuntu-latest` | Verifies that `install.sh` selects the snap automatically when the `snap` command is available, installs it from `latest/edge`, reuses system Docker, verifies the packaged prover version and a local policy boundary check, reaches the Docker gateway, creates, executes in, and deletes a sandbox, and verifies that the Docker snap is not installed. |
+| `ubuntu-snap-docker-preflight` | `ubuntu-latest` | Verifies that automatic snap selection rejects installation when Docker is absent or supplied by the Docker snap, without installing OpenShell. |
 | `kubernetes` | `ubuntu-latest` + kind | Installs the dev Helm chart, reaches the in-cluster gateway, and creates, executes in, and deletes a sandbox using the published runtime images. |
 
 All canary jobs disable anonymous OpenShell telemetry. Host package jobs inject
@@ -26,11 +26,13 @@ Kubernetes job installs with `server.telemetryEnabled=false`, so smoke traffic
 does not contribute to product usage metrics.
 
 The workflow sets `OPENSHELL_VERSION=dev` for every `install.sh` job. Positive
-jobs consume the rolling dev release produced by the triggering workflow. The
-system-Docker snap lane tracks `latest/edge`; the missing-Docker lane exits
-before installing a snap. The Debian and Kubernetes CLI lanes remove snapd so
-they continue to exercise the dev Debian package. Kubernetes pins the matching
-`0.0.0-dev` chart and `:dev` images.
+jobs consume the rolling dev release produced by the triggering workflow. Both
+snap lanes rely on the installed `snap` command to exercise automatic snap
+selection without setting `OPENSHELL_INSTALL_METHOD`. The system-Docker lane
+tracks `latest/edge`; the missing-Docker lane exits before installing a snap.
+The Debian and Kubernetes CLI lanes remove snapd so they continue to exercise
+the dev Debian package. Kubernetes pins the matching `0.0.0-dev` chart and
+`:dev` images.
 
 RPM package installation also has tmachine conformance coverage in
 `Branch E2E Checks` (with `test:e2e`), `Release Dev`, and `Release Tag`. Those

.github/workflows/release-canary.yml

@@ -195,8 +195,6 @@ jobs:
     name: Ubuntu snap with system Docker
     if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
     runs-on: ubuntu-latest
-    env:
-      OPENSHELL_INSTALL_METHOD: snap
     timeout-minutes: 20
     steps:
       - name: Install snapd
@@ -297,8 +295,6 @@ jobs:
     name: Ubuntu snap Docker preflight
     if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
     runs-on: ubuntu-latest
-    env:
-      OPENSHELL_INSTALL_METHOD: snap
     timeout-minutes: 20
     steps:
       - name: Install snapd

CI.md

@@ -571,7 +571,7 @@ These workflows run after merge to publish dev/tagged artifacts and verify them.
 | `.github/workflows/release-tag.yml` | Publishes stable releases and pre-releases on tag pushes or manual dispatch. Release Auto-Tag dispatches it explicitly because its `GITHUB_TOKEN` pushes do not trigger workflows. Both require the currently implemented qualification profile to pass before publication; the summary identifies the remaining RFC 0014 coverage. Failed candidates retain build artifacts and evidence in Actions storage. Source-SHA OCI images remain available as qualification inputs. |
 | `.github/workflows/snap-package.yml` | Builds snap and component artifacts for Release Dev and Release Tag without Store credentials or publication. |
 | `.github/workflows/snap-publish.yml` | Uploads existing snap and component artifacts to the Store without rebuilding. Release Dev calls it directly for `latest/edge` after snap builds and requires it to succeed before creating the dev release. Release Tag calls it for `latest/stable` only for stable releases, after qualification and release assembly succeed. |
-| `.github/workflows/release-canary.yml` | Smoke-tests published dev artifacts in the `macos`, `ubuntu-deb`, `ubuntu-snap-system-docker`, `fedora`, and `kubernetes` (kind + Helm) jobs. Each job reaches its gateway and creates, exercises, and deletes a sandbox. The `ubuntu-snap-system-docker` job verifies a compatible system Docker lifecycle, while `ubuntu-snap-docker-preflight` tests fail-fast behavior when Docker is absent or supplied by the Docker snap. The positive snap lane also runs a local policy containment check with the packaged prover. It runs automatically after `Release Dev` succeeds and supports manual dispatch (`gh workflow run release-canary.yml --ref <branch>`). See the `test-release-canary` skill for the playbook and local kind reproduction. |
+| `.github/workflows/release-canary.yml` | Smoke-tests published dev artifacts in the `macos`, `ubuntu-deb`, `ubuntu-snap-system-docker`, `fedora`, and `kubernetes` (kind + Helm) jobs. Each job reaches its gateway and creates, exercises, and deletes a sandbox. The snap jobs verify that `install.sh` selects the snap automatically when the `snap` command is available. The `ubuntu-snap-system-docker` job verifies a compatible system Docker lifecycle, while `ubuntu-snap-docker-preflight` tests fail-fast behavior when Docker is absent or supplied by the Docker snap. The positive snap lane also runs a local policy containment check with the packaged prover. It runs automatically after `Release Dev` succeeds and supports manual dispatch (`gh workflow run release-canary.yml --ref <branch>`). See the `test-release-canary` skill for the playbook and local kind reproduction. |
 
 ## Required status contexts
 

README.md

@@ -31,6 +31,8 @@ See [Architecture](https://docs.nvidia.com/openshell/latest/about/architecture)
 
 You need Linux, macOS on Apple Silicon, or Windows with WSL 2 (experimental), plus Docker, Podman, or host virtualization. See the [Support Matrix](https://docs.nvidia.com/openshell/latest/about/support-matrix) for details.
 
+On Linux with snapd, the default installation requires Docker Engine from a system package or Docker's repository; the Docker snap is unsupported. If you have snapd installed but want to use Podman or VMs instead of Docker, or you prefer a [native package](https://docs.nvidia.com/openshell/latest/about/installation#linux), you may do so with `OPENSHELL_INSTALL_METHOD=deb` or `rpm`.
+
 ```shell
 curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
 openshell sandbox create --name demo

crates/openshell-driver-vm/README.md

@@ -311,14 +311,17 @@ create TAP devices or install nftables/iptables rules.
   `release-vm-kernel.yml`
 
 On Debian-family Linux amd64 and arm64 systems, `install.sh` installs the
-Debian package from the selected `OPENSHELL_VERSION` release tag. That package
-includes `openshell-gateway` and `openshell-driver-vm`, but leaves
+Debian package when snapd is unavailable, `OPENSHELL_VERSION=pre` or an exact
+release tag is requested, or
+`OPENSHELL_INSTALL_METHOD=deb` is set. That package includes
+`openshell-gateway` and `openshell-driver-vm`, but leaves
 `OPENSHELL_COMPUTE_DRIVER` unset so the gateway uses its normal runtime
 auto-detection. Set `OPENSHELL_COMPUTE_DRIVER=vm` to force the VM driver.
 
-On RPM-family Linux x86_64 and aarch64 systems, `install.sh` installs the
-`openshell` and `openshell-gateway` RPM packages from the selected release tag.
-The RPM gateway package is configured for the Podman driver.
+On RPM-family Linux x86_64 and aarch64 systems, the equivalent native path
+installs the `openshell` and `openshell-gateway` RPM packages from the selected
+release tag. It is selected automatically under the same conditions or with
+`OPENSHELL_INSTALL_METHOD=rpm`. The RPM gateway package uses the Podman driver.
 
 On Apple Silicon macOS, `install.sh` stages the generated `openshell.rb`
 formula from the selected release in the `nvidia/openshell` Homebrew tap.

docs/about/installation.mdx

@@ -86,9 +86,11 @@ The gateway reads `~/.config/openshell/gateway.toml` if it exists, otherwise the
 
 ## Linux
 
-The script installs a Debian package on Debian and Ubuntu or an RPM package on Fedora and RHEL. Set `OPENSHELL_INSTALL_METHOD=snap` to install the [snap](#snap) package instead; hosts that already have the OpenShell snap keep refreshing it. Linux packages require glibc 2.28 or newer.
+When snapd is available, the script installs the [snap](#snap) package for the latest stable release or the rolling `dev` release. Otherwise, it installs a Debian package on Debian and Ubuntu or RPM packages on Fedora and RHEL. Prereleases and explicit release tags use native packages. Explicit `OPENSHELL_INSTALL_METHOD=snap` supports only an unset version or `OPENSHELL_VERSION=dev`.
 
-The gateway runs as a systemd user service at `https://127.0.0.1:17670` and reads `~/.config/openshell/gateway.toml`.
+Set `OPENSHELL_INSTALL_METHOD=deb` or `OPENSHELL_INSTALL_METHOD=rpm` to select a native package explicitly. Native Linux packages require glibc 2.28 or newer.
+
+For Debian and RPM installations, the gateway runs as a systemd user service at `https://127.0.0.1:17670` and reads `~/.config/openshell/gateway.toml`.
 
 Both Debian and RPM load `~/.config/openshell/gateway.env` for configuration
 preflight and gateway startup. Use it to select exact trusted runtime artifacts
@@ -119,9 +121,9 @@ sudo loginctl enable-linger $USER
 
 ## Snap
 
-The snap requires Docker Engine installed from your distribution or Docker's package repository. The Docker snap is not compatible.
+The snap requires Docker Engine installed from your distribution or Docker's package repository. The Docker snap is not compatible. To use Podman or the VM driver instead, select a native package with `OPENSHELL_INSTALL_METHOD=deb` or `OPENSHELL_INSTALL_METHOD=rpm`.
 
-The snap does not migrate existing Debian, RPM, or Homebrew installs. Remove any existing installation first, then either rerun the `install.sh` script with `OPENSHELL_INSTALL_METHOD=snap OPENSHELL_ACK_BREAKING_UPGRADE=1`, or install the snap directly:
+The snap does not migrate existing Debian, RPM, or Homebrew installs. If the script detects an existing native installation while selecting the snap, it stops before making changes. To keep the native installation, rerun it with `OPENSHELL_INSTALL_METHOD=deb` or `OPENSHELL_INSTALL_METHOD=rpm`. To migrate, back up any state you need, remove the native installation, and rerun the script. Set `OPENSHELL_ACK_BREAKING_UPGRADE=1` only if a detected native `openshell` binary remains after cleanup. You can also install the snap directly:
 
 ```shell
 sudo snap install openshell

install.sh

@@ -4,7 +4,8 @@
 #
 # Install OpenShell from a GitHub release.
 #
-# Linux installs either the Debian or RPM packages from the selected release.
+# Linux automatically installs the snap when snapd is available and
+# the version is unset or dev; exact releases and prereleases use native packages.
 # Apple Silicon macOS installs the generated Homebrew formula, so Homebrew owns
 # the binary layout and launchd service lifecycle.
 #
@@ -63,19 +64,19 @@ ENVIRONMENT VARIABLES:
                         pre-v0.0.37 or non-snap installation.
     OPENSHELL_INSTALL_METHOD
                         Linux package to install: snap, deb, or rpm. Unset
-                        selects deb or rpm from the host package manager.
+                        selects snap when snapd is available, otherwise deb or rpm.
 
 NOTES:
     When OPENSHELL_VERSION is unset, this resolves the latest tagged release
     from ${GITHUB_URL}/releases/latest.
 
-    Linux installs the Debian package on amd64/arm64 or the RPM packages on
-    x86_64/aarch64, depending on the host package manager. Set
-    OPENSHELL_INSTALL_METHOD=snap to install the OpenShell snap instead; hosts
-    that already have the OpenShell snap keep refreshing it. snap installs use
-    latest/stable by default and latest/edge for dev, and do not support
-    explicit release tags or prereleases. The OpenShell snap requires a running
-    Docker Engine installed from a system package or Docker's package
+    Linux installs the OpenShell snap when snapd is available and
+    OPENSHELL_VERSION is unset or dev. Snap installs use latest/stable by
+    default and latest/edge for dev. Explicit release tags and prereleases use
+    the Debian package on amd64/arm64 or the RPM packages on x86_64/aarch64,
+    depending on the host package manager. Set OPENSHELL_INSTALL_METHOD=deb or
+    rpm to select a native package explicitly. The OpenShell snap requires a
+    running Docker Engine installed from a system package or Docker's package
     repository. The Docker snap is not currently compatible with OpenShell.
     macOS installs the release Homebrew formula on Apple Silicon and starts a
     brew services-backed local gateway.
@@ -86,6 +87,11 @@ has_cmd() {
   command -v "$1" >/dev/null 2>&1
 }
 
+snapd_available() {
+  has_cmd snap || return 1
+  snap version 2>/dev/null | grep -Eq '^snapd[[:space:]]+[0-9]'
+}
+
 require_cmd() {
   if ! has_cmd "$1"; then
     error "'$1' is required"
@@ -668,11 +674,9 @@ linux_package_method() {
     *) error "unsupported OPENSHELL_INSTALL_METHOD=${OPENSHELL_INSTALL_METHOD}; use snap, deb, or rpm" ;;
   esac
 
-  # Keep refreshing an existing snap install instead of adding a second
-  # gateway on the same port.
   case "${OPENSHELL_VERSION:-}" in
     '' | dev)
-      if has_cmd snap && snap list openshell >/dev/null 2>&1; then
+      if snapd_available; then
         echo "snap"
         return 0
       fi
@@ -1451,6 +1455,9 @@ wait_for_user_snap_gateway_listener() {
 
 install_linux_snap() {
   require_cmd snap
+  snapd_available || error "snapd is not available; ensure snapd is running, then rerun this installer"
+  info "waiting for snapd initialization to complete..."
+  as_root snap wait system seed.loaded || error "snapd initialization did not complete"
   set_linux_target_runtime_dir
 
   if snap list openshell >/dev/null 2>&1; then
@@ -1467,11 +1474,11 @@ install_linux_snap() {
 
   if snap list docker >/dev/null 2>&1; then
     error "the Docker snap is not currently compatible with OpenShell because its AppArmor confinement prevents OpenShell's hardened containers from starting.
-Remove the Docker snap and install Docker Engine from a system package or Docker's package repository, then rerun this installer."
+Remove the Docker snap and install Docker Engine from a system package or Docker's package repository, then rerun this installer. To use a native OpenShell package instead, set OPENSHELL_INSTALL_METHOD=deb or OPENSHELL_INSTALL_METHOD=rpm."
   fi
   if ! has_cmd docker; then
     error "Docker is required before installing the OpenShell snap.
-Install Docker Engine from a system package or Docker's package repository, then rerun this installer. The Docker snap is not currently compatible with OpenShell."
+Install Docker Engine from a system package or Docker's package repository, then rerun this installer. The Docker snap is not currently compatible with OpenShell. To use a native OpenShell package instead, set OPENSHELL_INSTALL_METHOD=deb or OPENSHELL_INSTALL_METHOD=rpm."
   fi
   info "using existing Docker installation"
   if [ "$_existing_mode" = user ]; then

nix/test-guest/README.md

@@ -78,10 +78,10 @@ The root [`flake.nix`](../../flake.nix) exposes this directory as the `test-gues
 | Fedora 44 | No | Yes | Yes | Yes | `.rpm` |
 | Rocky Linux 9 | Yes | Yes | No | Yes | `.rpm` |
 
-The `snapd` configuration is available for Ubuntu and prepares snapd for snap
-Store installation experiments. Combine it with `docker` to reproduce the
-system-Docker canary, or use it alone to verify that `install.sh` fails safely
-when Docker is absent.
+The `snapd` configuration is available for Ubuntu and prepares snapd to
+reproduce `install.sh` automatic snap selection. Combine it with `docker` to
+reproduce the system-Docker canary, or use it alone to verify that `install.sh`
+fails safely when Docker is absent.
 
 `podman-rootless` configures the explicit rootless Podman guest setup used by
 OpenShell tests. It supports Fedora and Ubuntu 26.04 or later. Ubuntu adds the