NVIDIA · drew · Sep 26, 2026 · Sep 25, 2026 · Sep 25, 2026 · Sep 25, 2026
@@ -195,6 +195,8 @@ 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
@@ -232,6 +234,9 @@ jobs:
           sudo snap connections openshell | grep -E '^docker +openshell:docker +:docker +'
           openshell --version
           sudo snap services openshell
+          sudo journalctl -b -u snap.openshell.gateway.service --no-pager |
+            grep -F "mTLS user authentication enabled"
+          openshell gateway list | grep -F "https://127.0.0.1:17670"
           openshell status
 
       - name: Create and exercise a sandbox
@@ -262,6 +267,8 @@ 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

@@ -324,24 +324,30 @@ for direct executable installation on every environment. Release Dev and
 Release Tag run Ubuntu conformance through the Debian package, while Fedora
 continues using direct executable installation until RPM coverage is available.
 The release canary separately exercises the public installer on Ubuntu. The
-OpenShell Snap requires a compatible, preinstalled non-Snap Docker daemon. Its
-positive canary uses system Docker; negative preflight coverage verifies that
-the installer rejects both missing Docker and the Docker Snap before installing
-OpenShell. Its Debian lane removes snapd before running the installer so Snap
-precedence cannot change the package under test.
-Explicit release tags and the `pre` alias bypass Snap selection and use the
-native Debian or RPM package path even when `snap` is available. The `pre` alias
+installer selects the OpenShell Snap only with `OPENSHELL_INSTALL_METHOD=snap`
+or when the Snap is already installed; otherwise it uses the native Debian or
+RPM package. The Snap requires a compatible, preinstalled non-Snap Docker
+daemon. Its positive canary uses system Docker; negative preflight coverage
+verifies that the installer rejects both missing Docker and the Docker Snap
+before installing OpenShell.
+Explicit release tags and the `pre` alias always use the native Debian or RPM
+package path. The `pre` alias
 checks matching Git tags in version order, then looks up the exact platform
 artifact and verifies the release run instead of listing every repository
 artifact.
 
 Snapd runs the gateway as a root-owned system service. Its generated client
-certificates reside in root-owned snap state and are unavailable to ordinary CLI
-users, so the Snap uses plaintext loopback transport and enables unauthenticated
-local users by default. Debian and RPM packages instead run systemd user services
-and use user-owned mTLS material. Bootstrap creates the default configuration
-only when it is missing. Sandbox-to-gateway sessions remain authenticated with
-gateway-minted JWTs.
+certificates reside in root-owned snap state. The installer copies the client
+bundle into the target user's private Snap state and registers the TLS endpoint;
+direct Snap installs require the same enrollment. The install and post-refresh
+hooks replace configs that explicitly enable plaintext or unauthenticated access
+with the secure default. Snap refreshes
+restart the gateway so the migrated config takes effect immediately.
+
+Debian and RPM packages instead run systemd user services with user-owned mTLS
+material. Sandbox-to-gateway sessions remain authenticated with gateway-minted
+JWTs.
+
 The Debian qualification profile keeps candidate-image overrides outside the
 operator-owned gateway configuration: it writes a harness-owned file under
 `/var/lib/openshell-qualification` and selects it through the packaged systemd

@@ -38,7 +38,7 @@ curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh |
   OPENSHELL_VERSION=pre sh
 ```
 
-The installer checks prerelease tags from newest to oldest, selects an unexpired artifact from a successful release run for the current platform, and downloads only that artifact. Installed packages keep the candidate's exact version, such as `0.1.0-pre.3`. Prerelease tags do not create entries on the GitHub Releases page. On Linux, prereleases and explicit release tags use Debian or RPM packages even if `snap` is installed.
+The installer checks prerelease tags from newest to oldest, selects an unexpired artifact from a successful release run for the current platform, and downloads only that artifact. Installed packages keep the candidate's exact version, such as `0.1.0-pre.3`. Prerelease tags do not create entries on the GitHub Releases page. On Linux, prereleases and explicit release tags use Debian or RPM packages.
 
 The rolling [`dev` release](https://github.com/NVIDIA/OpenShell/releases/tag/dev) does not require GitHub authentication:
 
@@ -86,7 +86,7 @@ The gateway reads `~/.config/openshell/gateway.toml` if it exists, otherwise the
 
 ## Linux
 
-The script uses the [Snap](#snap) package when `snap` is available. Otherwise, or when you set `OPENSHELL_VERSION` to a release tag, it installs a Debian package on Debian and Ubuntu or an RPM package on Fedora and RHEL. Linux packages require glibc 2.28 or newer.
+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.
 
 The gateway runs as a systemd user service at `https://127.0.0.1:17670` and reads `~/.config/openshell/gateway.toml`.
 
@@ -110,20 +110,22 @@ The snap requires Docker Engine installed from your distribution or Docker's pac
 sudo snap install openshell
 ```
 
-The snap does not migrate existing Debian, RPM, or Homebrew installs. Remove any existing installation first, then rerun the script with `OPENSHELL_ACK_BREAKING_UPGRADE=1`.
+The snap does not migrate existing Debian, RPM, or Homebrew installs. Remove any existing installation first, then rerun the script with `OPENSHELL_INSTALL_METHOD=snap OPENSHELL_ACK_BREAKING_UPGRADE=1`.
 
-The gateway runs as a system service at `http://127.0.0.1:17670` and reads `/var/snap/openshell/common/gateway.toml`.
-
-<Warning>
-The snap gateway allows unauthenticated access from the local host. Any local user or process can operate it. Do not expose it beyond the local host.
-</Warning>
-
-Snap refreshes do not restart the gateway, so active sandboxes keep running. Restart it to pick up a new version:
+The gateway runs as a system service at `https://127.0.0.1:17670` and reads `/var/snap/openshell/common/gateway.toml`. It requires a client certificate. The install script copies that certificate to the installing user's Snap state and registers the gateway automatically. If you installed with `sudo snap install openshell`, give each trusted user the certificate and register the gateway from that user's account:
 
 ```shell
-sudo systemctl restart snap.openshell.gateway
+d=~/snap/openshell/common/.local/state/openshell/tls
+mkdir -p -m 700 "$d" "$d/client"
+sudo install -o "$USER" -m 600 /var/snap/openshell/common/tls/ca.crt "$d/"
+sudo install -o "$USER" -m 600 -t "$d/client" \
+  /var/snap/openshell/common/tls/client/tls.crt /var/snap/openshell/common/tls/client/tls.key
+openshell gateway add https://127.0.0.1:17670 --local --name openshell
+openshell status
 ```
 
+Keep the client key private.
+
 To install a locally built snap, connect its interfaces manually:
 
 ```shell

@@ -61,21 +61,22 @@ ENVIRONMENT VARIABLES:
     OPENSHELL_ACK_BREAKING_UPGRADE
                         Set to 1 only after backing up and cleaning up a
                         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.
 
 NOTES:
     When OPENSHELL_VERSION is unset, this resolves the latest tagged release
     from ${GITHUB_URL}/releases/latest.
 
-    On Linux, the installer uses the OpenShell snap when the snap command 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 Debian or RPM packages. The OpenShell snap requires a
-    running Docker Engine installed from a system package or Docker's package
+    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
     repository. The Docker snap is not currently compatible with OpenShell.
-
-    For explicit versions or without snap, Linux installs the Debian package
-    on amd64/arm64 or the RPM packages on x86_64/aarch64, depending on the
-    host package manager.
     macOS installs the release Homebrew formula on Apple Silicon and starts a
     brew services-backed local gateway.
 EOF
@@ -658,9 +659,20 @@ local_gateway_endpoint() {
 }
 
 linux_package_method() {
+  case "${OPENSHELL_INSTALL_METHOD:-}" in
+    snap | deb | rpm)
+      echo "$OPENSHELL_INSTALL_METHOD"
+      return 0
+      ;;
+    '') ;;
+    *) 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; then
+      if has_cmd snap && snap list openshell >/dev/null 2>&1; then
         echo "snap"
         return 0
       fi
@@ -1220,43 +1232,6 @@ openshell_snap_channel() {
   esac
 }
 
-ensure_snap_gateway_config() {
-  _config_file="${1:-/var/snap/openshell/common/gateway.toml}"
-
-  as_root sh -c '
-    set -eu
-    config_file=$1
-    if [ -e "$config_file" ] || [ -L "$config_file" ]; then
-      exit 0
-    fi
-
-    config_dir=${config_file%/*}
-    mkdir -p "$config_dir"
-    umask 077
-    temporary_file=$(mktemp "${config_file}.tmp.XXXXXX")
-    trap '\''rm -f "$temporary_file"'\'' 0 HUP INT TERM
-
-    cat >"$temporary_file" <<'\''EOF'\''
-[openshell]
-version = 2
-
-[openshell.gateway]
-
-[openshell.gateway.auth]
-allow_unauthenticated_users = true
-EOF
-
-    if ! ln "$temporary_file" "$config_file"; then
-      if [ -e "$config_file" ] || [ -L "$config_file" ]; then
-        exit 0
-      fi
-      exit 1
-    fi
-    rm -f "$temporary_file"
-    trap - 0 HUP INT TERM
-  ' sh "$_config_file"
-}
-
 wait_for_docker_daemon() {
   _timeout="${OPENSHELL_INSTALL_DOCKER_TIMEOUT:-30}"
   _elapsed=0
@@ -1280,9 +1255,39 @@ wait_for_docker_daemon() {
   error "Docker daemon did not become reachable within ${_timeout}s"
 }
 
+# Copy the snap gateway's client bundle into the target user's snap state
+# directory, where `openshell gateway add --local` imports it. Root only reads
+# the source files; the target user writes the copies into their own home.
+copy_snap_client_bundle() {
+  _src="${OPENSHELL_SNAP_TLS_DIR:-/var/snap/openshell/common/tls}"
+  _dst="${TARGET_HOME}/snap/openshell/common/.local/state/openshell/tls"
+
+  as_target_user mkdir -p "${_dst}/client"
+  as_target_user chmod 700 "$_dst" "${_dst}/client"
+  for _file in ca.crt client/tls.crt client/tls.key; do
+    as_root cat "${_src}/${_file}" |
+      as_target_user sh -c 'umask 077; cat >"$1"' sh "${_dst}/${_file}"
+    as_target_user chmod 600 "${_dst}/${_file}"
+  done
+}
+
+# Snap revisions that require mTLS ship the post-refresh hook that migrates
+# older plaintext configs.
+snap_gateway_uses_mtls() {
+  [ -e "${OPENSHELL_SNAP_DIR:-/snap/openshell/current}/meta/hooks/post-refresh" ]
+}
+
 register_snap_gateway() {
   _register_bin="${OPENSHELL_REGISTER_BIN:-/snap/bin/openshell}"
-  _endpoint="http://127.0.0.1:${LOCAL_GATEWAY_PORT}"
+
+  if snap_gateway_uses_mtls; then
+    _endpoint="https://127.0.0.1:${LOCAL_GATEWAY_PORT}"
+    info "copying the gateway client certificate for ${TARGET_USER}..."
+    copy_snap_client_bundle
+  else
+    _endpoint="http://127.0.0.1:${LOCAL_GATEWAY_PORT}"
+    warn "this OpenShell snap revision serves plaintext HTTP without client authentication; any local user can operate the gateway"
+  fi
 
   if _add_output="$(as_target_user "$_register_bin" gateway add "$_endpoint" --local --name openshell 2>&1)"; then
     [ -z "$_add_output" ] || print_gateway_add_output "$_add_output"
@@ -1304,15 +1309,28 @@ register_snap_gateway() {
   esac
 }
 
+# The mTLS gateway rejects TLS handshakes without a client certificate, so
+# probe it with the root-owned client bundle.
 wait_for_snap_gateway_listener() {
   _timeout="${OPENSHELL_INSTALL_GATEWAY_TIMEOUT:-30}"
   _elapsed=0
   _last_output=""
-  _probe_url="http://127.0.0.1:${LOCAL_GATEWAY_PORT}/"
+  _tls_dir="${OPENSHELL_SNAP_TLS_DIR:-/var/snap/openshell/common/tls}"
+
+  if snap_gateway_uses_mtls; then
+    _probe_url="https://127.0.0.1:${LOCAL_GATEWAY_PORT}/"
+    _probe_as=as_root
+    set -- --cacert "${_tls_dir}/ca.crt" \
+      --cert "${_tls_dir}/client/tls.crt" --key "${_tls_dir}/client/tls.key"
+  else
+    _probe_url="http://127.0.0.1:${LOCAL_GATEWAY_PORT}/"
+    _probe_as=""
+    set --
+  fi
 
   info "waiting for local gateway listener to become reachable..."
   while [ "$_elapsed" -lt "$_timeout" ]; do
-    if _last_output="$(curl -sS --max-time 2 -o /dev/null "$_probe_url" 2>&1)"; then
+    if _last_output="$($_probe_as curl -sS --max-time 2 "$@" -o /dev/null "$_probe_url" 2>&1)"; then
       info "local gateway listener is reachable"
       return 0
     fi
@@ -1350,13 +1368,12 @@ Install Docker Engine from a system package or Docker's package repository, then
     as_root snap install openshell --channel="$_channel"
   fi
 
-  ensure_snap_gateway_config
   as_root snap restart openshell.gateway
 
   info "installed OpenShell snap from ${_channel}"
+  wait_for_snap_gateway_listener
   info "registering local gateway as ${TARGET_USER}..."
   register_snap_gateway
-  wait_for_snap_gateway_listener
   OPENSHELL_REGISTER_BIN="/snap/bin/openshell"
   wait_for_local_gateway_status
 }

@@ -99,7 +99,7 @@ for attempt in $(seq 1 "${attempts}"); do
 	echo "==> install.sh Snap ${mode} reproduction attempt ${attempt}/${attempts}"
 	if [ "${mode}" != system-docker ]; then
 		output=$(mktemp)
-		if OPENSHELL_VERSION=dev sh "${install_script}" >"${output}" 2>&1; then
+		if OPENSHELL_INSTALL_METHOD=snap OPENSHELL_VERSION=dev sh "${install_script}" >"${output}" 2>&1; then
 			echo "install.sh unexpectedly succeeded in ${mode} mode" >&2
 			cat "${output}" >&2
 			rm -f "${output}"
@@ -127,7 +127,7 @@ for attempt in $(seq 1 "${attempts}"); do
 	fi
 
 	sandbox="snap-${attempt}-$$"
-	if ! OPENSHELL_VERSION=dev sh "${install_script}" ||
+	if ! OPENSHELL_INSTALL_METHOD=snap OPENSHELL_VERSION=dev sh "${install_script}" ||
 		! sudo snap list openshell >/dev/null ||
 		! snap info openshell | grep -Eq '^tracking: +latest/edge$' ||
 		! docker_is_ready ||

@@ -155,7 +155,11 @@ def test_snap_wrapper_uses_optional_gateway_config_without_generating_toml() ->
         'export OPENSHELL_DB_URL="${OPENSHELL_DB_URL:-sqlite:${SNAP_COMMON}/gateway.db?mode=rwc}"'
         in wrapper
     )
-    assert 'export OPENSHELL_DISABLE_TLS="${OPENSHELL_DISABLE_TLS:-true}"' in wrapper
+    assert "OPENSHELL_DISABLE_TLS" not in wrapper
+    assert (
+        'export OPENSHELL_LOCAL_TLS_DIR="${OPENSHELL_LOCAL_TLS_DIR:-${SNAP_COMMON}/tls}"'
+        in wrapper
+    )
     assert (
         'exec "${SNAP}/bin/openshell-gateway" --config "$CANONICAL_CONFIG_FILE" "$@"'
         in wrapper

@@ -72,6 +72,7 @@ Common findings:
 - `No active gateway`: register one with `openshell gateway add <endpoint>`.
 - Connection refused: gateway process is not running, service exposure is wrong, or a port-forward/proxy is not active.
 - TLS/certificate errors: the endpoint scheme or trust chain is wrong, a local mTLS bundle does not match the gateway CA, or TLS termination does not match the gateway listener.
+- A Snap refresh restarts the gateway with its migrated mTLS config. The secure Snap gateway uses `https://127.0.0.1:17670` and requires a client bundle in the user's Snap state. Refresh replaces insecure configs without keeping a copy; follow the published Snap installation steps to re-register an old HTTP client.
 - `Unauthenticated` from an edge or OIDC gateway: refresh stored credentials with `openshell gateway login [name]`, then retry. Use `gateway logout` only when intentionally clearing local credentials.
 - A direct development endpoint with a private or self-signed certificate can be isolated with `--gateway-endpoint <url> --gateway-insecure`; do not persist or recommend insecure verification for shared gateways.
 

@@ -2,35 +2,34 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
+# Create the mTLS default and replace insecure configs on refresh.
+
 set -eu
 
 config_file="${SNAP_COMMON}/gateway.toml"
-if [ -e "$config_file" ] || [ -L "$config_file" ]; then
+insecure='^[[:space:]]*(allow_unauthenticated_users|disable_tls)[[:space:]]*=[[:space:]]*true([[:space:]#]|$)'
+
+# Keep secure operator configs, symlinks, and directories. Replace a config
+# that explicitly allows plaintext or anonymous access, even if it has other
+# edits.
+if [ -L "$config_file" ]; then
+	exit 0
+elif [ -f "$config_file" ]; then
+	grep -Eq "$insecure" "$config_file" || exit 0
+	echo "openshell: replacing insecure gateway config with the mTLS default" >&2
+elif [ -e "$config_file" ]; then
 	exit 0
 fi
 
 mkdir -p "$SNAP_COMMON"
 umask 077
 temporary_file=$(mktemp "${config_file}.tmp.XXXXXX")
 trap 'rm -f "$temporary_file"' 0 HUP INT TERM
-
-cat >"$temporary_file" <<'EOF'
+cat >"$temporary_file" <<'CONFIG'
 [openshell]
 version = 2
 
 [openshell.gateway]
-
-[openshell.gateway.auth]
-allow_unauthenticated_users = true
-EOF
-
-# A hard link publishes the config atomically without replacing a path created
-# concurrently. SNAP_COMMON and the temporary file are on the same filesystem.
-if ! ln "$temporary_file" "$config_file"; then
-	if [ -e "$config_file" ] || [ -L "$config_file" ]; then
-		exit 0
-	fi
-	exit 1
-fi
-rm -f "$temporary_file"
+CONFIG
+mv -f "$temporary_file" "$config_file"
 trap - 0 HUP INT TERM