@@ -130,6 +130,19 @@ systemctl --user enable --now snap.openshell.user-gateway.service
 
 The user gateway is disabled globally by default. The install script enables it only for the user who ran the script. After a direct snap installation, choose one user account to run the gateway and enable it with the command above. Do not enable the gateway for multiple users who may be logged in at the same time: every user gateway binds to `127.0.0.1:17670`, so only one can run on the system at a time.
 
+Older OpenShell snap revisions could enable the user gateway globally, causing it to start for every user. Remove that global enablement once, then enable the gateway from the account that will run it:
+
+```shell
+sudo systemctl disable --global snap.openshell.user-gateway.service
+systemctl --user enable --now snap.openshell.user-gateway.service
+```
+
+The global command prevents automatic activation for other users but does not stop gateways already running in their user sessions. Run the following command from each other affected user's session:
+
+```shell
+systemctl --user disable --now snap.openshell.user-gateway.service
+```
+
 The snap installs the standalone policy prover as `openshell.prover`. The
 `openshell-prover` alias requires Snap Store approval and may not be available.
 The prover reads local policy files through the `home` interface and does not
 
@@ -1494,6 +1494,9 @@ Install Docker Engine from a system package or Docker's package repository, then
     warn "restarting the OpenShell gateway to use the refreshed snap; active sandbox sessions will be interrupted"
     as_root snap restart openshell.system-gateway
   else
+    # In case refreshing from an old snap which had a globally-enabled user
+    # gateway service, globally disable it, then just enable for the target user
+    as_root systemctl --global disable snap.openshell.user-gateway.service
     as_target_user systemctl --user daemon-reload
     as_target_user systemctl --user enable --now snap.openshell.user-gateway.service
     if [ "$_existing_snap" = true ]; then
 
@@ -72,7 +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 CLI mTLS bundle does not match the gateway CA, a supervisor is missing the gateway CA, or TLS termination does not match the gateway listener. Workloads and supervisors should not contain a user TLS client certificate or private key.
-- Fresh snap installations select `gateway-mode=user`, but the user gateway is globally disabled by default. `install.sh` enables `snap.openshell.user-gateway.service` only for its target user; direct snap installations must select one user and run `systemctl --user enable --now snap.openshell.user-gateway.service` from that user's session. Do not enable it for multiple concurrently logged-in users: every instance binds to `127.0.0.1:17670`, so later instances fail with an address-in-use error. Setting `gateway-mode=user` disables the system gateway without changing any user's service. To change the selected user, disable and stop the current user's unit before enabling the new user's unit. Upgraded installations retain their system-owned state through `openshell.system-gateway`. Existing HTTPS registrations continue to work after the service rename. Follow the published snap installation steps to enroll a new user, replace an old HTTP registration, or change modes safely through the `disable` maintenance state. If `gateway-mode=disable`, no local snap gateway is expected to run.
+- Fresh snap installations select `gateway-mode=user`, but the user gateway is globally disabled by default. `install.sh` enables `snap.openshell.user-gateway.service` only for its target user; direct snap installations must select one user and run `systemctl --user enable --now snap.openshell.user-gateway.service` from that user's session. Do not enable it for multiple concurrently logged-in users: every instance binds to `127.0.0.1:17670`, so later instances fail with an address-in-use error. Older snap revisions could leave the unit globally enabled; remove that state with `sudo systemctl disable --global snap.openshell.user-gateway.service`, then disable and stop the service from every other affected user's session. The global command does not stop running user services. Setting `gateway-mode=user` disables the system gateway without changing any user's service. To change the selected user, disable and stop the current user's unit before enabling the new user's unit. Upgraded installations retain their system-owned state through `openshell.system-gateway`. Existing HTTPS registrations continue to work after the service rename. Follow the published snap installation steps to enroll a new user, replace an old HTTP registration, or change modes safely through the `disable` maintenance state. If `gateway-mode=disable`, no local snap gateway is expected to run.
 - `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.
 - Operator credential retrieval requires direct gateway mTLS, `[openshell.gateway.mtls_auth] operator_enabled = true`, and a verified certificate with exact `OU=operator`. OIDC admin roles and forwarded certificate headers do not grant access. Do not combine the operator certificate with an `Authorization` header. Enabling this role grants gateway-wide administration; never repair a denial by issuing operator certificates to ordinary users. See the published gateway authentication and provider references.
 - 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.
 
@@ -33,6 +33,15 @@ description: |
        same time. Every user gateway binds to 127.0.0.1:17670, so only one can
        run on the system at a time.
 
+       Older OpenShell snap revisions could enable the user gateway globally.
+       When upgrading such an installation, remove that global enablement so
+       the gateway does not start automatically for other users:
+
+         sudo systemctl disable --global snap.openshell.user-gateway.service
+
+       This does not stop gateways already running in other user sessions.
+       Those users must disable and stop the service from their own sessions.
+
        If the OpenShell snap was installed before Docker was running, its user
        service may have hit the systemd start limit. Resolve this from the
        affected user's session after Docker is available:
 
@@ -366,6 +366,7 @@ assert_snap_user_refresh_flow() {
   calls="$(cat "$out")"
   expected="wait:user-docker
 root:snap refresh openshell --channel=latest/stable
+root:systemctl --global disable snap.openshell.user-gateway.service
 target:systemctl --user daemon-reload
 target:systemctl --user enable --now snap.openshell.user-gateway.service
 target:systemctl --user restart snap.openshell.user-gateway.service
@@ -384,6 +385,7 @@ assert_snap_install_flow \
   1 0 "" \
   "wait:user-docker
 root:snap install openshell --channel=latest/stable
+root:systemctl --global disable snap.openshell.user-gateway.service
 target:systemctl --user daemon-reload
 target:systemctl --user enable --now snap.openshell.user-gateway.service
 wait:user-gateway-listener
 
@@ -233,9 +233,12 @@ assert_contains "$snap_install_docs" "systemctl --user reset-failed snap.openshe
 assert_contains "$snap_install_docs" "systemctl --user enable --now snap.openshell.user-gateway.service"
 assert_contains "$snapcraft" "systemctl --user enable --now snap.openshell.user-gateway.service"
 assert_contains "$ROOT/install.sh" "systemctl --user enable --now snap.openshell.user-gateway.service"
+assert_contains "$ROOT/install.sh" "systemctl --global disable snap.openshell.user-gateway.service"
 assert_contains "$snap_install_docs" 'every user gateway binds to `127.0.0.1:17670`'
 assert_contains "$snap_install_docs" "systemctl --user disable --now snap.openshell.user-gateway.service"
 assert_contains "$snapcraft" "Every user gateway binds to 127.0.0.1:17670"
+assert_contains "$snap_install_docs" "sudo systemctl disable --global snap.openshell.user-gateway.service"
+assert_contains "$snapcraft" "sudo systemctl disable --global snap.openshell.user-gateway.service"
 for snap_file in "$ROOT/install.sh" "$snapcraft" "$snap_install_docs"; do
   assert_not_contains "$snap_file" "snap start --user openshell.user-gateway"
   assert_not_contains "$snap_file" "snap restart openshell.user-gateway"