feat(snap): add snap install method to install.sh when snap is available

.image-garden.mk

@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# TODO: image-garden maps systems to cloud-init templates by (system, arch) but
+# cannot select different templates for the same system name. Until that is
+# resolved, we use different cloud-image versions to give each docker
+# configuration a distinct cloud-init profile. 22.04, 24.04, 26.04, 12 (bookworm),
+# 13 (trixie), and 44 (Fedora). Once spread supports more flexible per-system
+# overrides, consolidate back to a single ubuntu-cloud-26.04 definition.
+
+# snapd-only: snapd is pre-installed, no docker at all.
+# install.sh will choose the "snap" install path.
+define UBUNTU_22.04_CLOUD_INIT_USER_DATA_TEMPLATE
+$(CLOUD_INIT_USER_DATA_TEMPLATE)
+- snap wait system seed.loaded
+- snap install snapd
+packages:
+- snapd
+endef
+
+# docker-snap: snapd + docker snap pre-installed.
+# install.sh will choose the "snap" install path.
+define UBUNTU_24.04_CLOUD_INIT_USER_DATA_TEMPLATE
+$(CLOUD_INIT_USER_DATA_TEMPLATE)
+- snap wait system seed.loaded
+- snap install docker
+packages:
+- snapd
+endef
+
+# native-docker: snapd + docker installed via apt (deb package).
+# install.sh will choose the "classic" install path because native
+# docker is detected and snapd is present.
+define UBUNTU_26.04_CLOUD_INIT_USER_DATA_TEMPLATE
+$(CLOUD_INIT_USER_DATA_TEMPLATE)
+packages:
+- docker.io
+endef
+
+# snapd + docker snap pre-installed. install.sh detects snapd and finds docker
+# snap, choosing the snap install path. Debian users who install snapd to run
+# docker as a snap get this configuration.
+define DEBIAN_12_CLOUD_INIT_USER_DATA_TEMPLATE
+$(CLOUD_INIT_USER_DATA_TEMPLATE)
+- snap wait system seed.loaded
+- snap install snapd
+- snap install docker
+packages:
+- snapd
+endef
+
+# native docker, no snapd — classic install path.
+define DEBIAN_13_CLOUD_INIT_USER_DATA_TEMPLATE
+$(CLOUD_INIT_USER_DATA_TEMPLATE)
+packages:
+- docker.io
+endef
+
+# Clean Fedora image: no snapd, no docker.
+# install.sh chooses the classic (rpm) install path.
+define FEDORA_44_CLOUD_INIT_USER_DATA_TEMPLATE
+$(CLOUD_INIT_USER_DATA_TEMPLATE)
+endef

.image-garden/.gitignore

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+*.img
+*.iso
+*.lock
+*.log
+*.meta-data
+*.qcow2
+*.run
+*.user-data

docs/about/installation.mdx

@@ -16,7 +16,10 @@ Install OpenShell with a single command:
 curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
 ```
 
-The script detects your operating system and installs the OpenShell CLI and gateway with your native package manager. It then starts the local gateway server so you can begin creating sandboxes.
+The script detects your operating system and installs the OpenShell CLI and
+gateway. On Linux, the Snap path is preferred when `snapd` is available;
+otherwise the script uses the native DEB or RPM package. The gateway then
+starts automatically so you can begin creating sandboxes.
 
 You can also download release artifacts directly from the [OpenShell GitHub Releases](https://github.com/NVIDIA/OpenShell/releases) page.
 
@@ -51,6 +54,13 @@ brew services restart openshell
 
 ## Linux
 
+On distributions that ship with `snapd`, the install script uses the Snap path
+described below, provided no non-snap Docker is detected. If a native Docker
+package is present, the installer exits with an error and recommends installing
+via DEB or RPM instead. On hosts without `snapd` (or with
+`OPENSHELL_INSTALL_METHOD=classic` set), the script falls back to the classic
+package manager.
+
 On Fedora and RHEL, the install script uses RPM packages. The RPM installs the `openshell` CLI, the `openshell-gateway` daemon, and a systemd user service.
 
 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.
@@ -75,6 +85,81 @@ To keep the user service running after logout, enable linger:
 sudo loginctl enable-linger $USER
 ```
 
+## Snap
+
+On Linux distributions that ship with `snapd`, the install script installs
+OpenShell from the Snap Store. The OpenShell snap bundles the CLI, the terminal
+UI, and a managed gateway daemon. snapd handles upgrades and rollback; the
+gateway runs as a system service inside the snap.
+
+You can also install the snap directly:
+
+```shell
+sudo snap install openshell
+```
+
+The snap requires the Docker snap. `default-provider: docker` on the OpenShell
+snap installs the Docker snap automatically on first use, but you can install
+it up front with:
+
+```shell
+sudo snap install docker
+```
+
+### Connect the required interfaces
+
+Strict confinement requires explicit `snap connect` for several interfaces. The
+installer runs these for you on Snap installs; run them by hand if you install
+the snap manually:
+
+```shell
+sudo snap connect openshell:docker docker:docker-daemon
+sudo snap connect openshell:log-observe
+sudo snap connect openshell:ssh-keys
+sudo snap connect openshell:system-observe
+```
+
+The Docker slot is the Docker snap's `docker-daemon` slot; OpenShell does not
+work with a host-installed Docker Engine. The installer is best-effort: if a
+connect fails (for example because the Docker snap is not yet running), the
+snap still installs and the installer prints a warning.
+
+### Verify the gateway
+
+The snap-managed gateway service is `openshell.gateway`. Inspect it with:
+
+```shell
+snap services openshell
+snap logs -n 100 openshell.gateway
+```
+
+Register the gateway with the CLI:
+
+```shell
+openshell gateway add https://127.0.0.1:17670 --local --name openshell
+openshell status
+```
+
+The gateway listens on `https://127.0.0.1:17670` and stores its state under
+`/var/snap/openshell/common/`. Override gateway settings by creating
+`/var/snap/openshell/common/gateway.toml`.
+
+### When to choose Snap
+
+Use Snap when `snapd` is available and no native Docker Engine is installed,
+and you want atomic upgrades and rollback, a single self-contained install that
+bundles the Docker provider, or a desktop launcher that surfaces the OpenShell
+terminal UI in the application menu.
+
+Use DEB or RPM when `snapd` is unavailable or presents temporary limitations
+awaiting snapd 2.76 release: `systemd --user` integration for the gateway, or
+when you already run Docker Engine from a non-snap source. The installer will
+refuse Snap installs on hosts with native Docker — use the DEB or RPM package
+instead.
+
+Set `OPENSHELL_INSTALL_METHOD=classic` to force the classic package on hosts
+that also have `snapd` available.
+
 ## Kubernetes
 
 Kubernetes deployments use the OpenShell Helm chart. For step-by-step installation, refer to [Kubernetes Setup](/kubernetes/setup). For chart values and packaging details, refer to the [Helm chart README](https://github.com/NVIDIA/OpenShell/blob/main/deploy/helm/openshell/README.md).