Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
olivercalder wants to merge 7 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
576cf94
feat(install): add snap install support with automatic Docker snap pr…
zyga Jun 9, 2026
5886877
docs(installation): document snap install path
zyga Jun 5, 2026
4bd8a05
docs(installation): update installation docs to for snap installation
olivercalder Jul 13, 2026
22525a2
feat(install): add `OPENSHELL_INSTALL_METHOD` options
olivercalder Jul 13, 2026
dc778b4
ci(release): update ubuntu release canary variants
olivercalder Jul 17, 2026
8db6072
fix(snap): fix outdated description in snapcraft.yaml
olivercalder Jul 17, 2026
c91aea9
fix(install): remove OPENSHELL_INSTALL_METHOD variable
olivercalder Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions .agents/skills/test-release-canary/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,9 @@ The Release Canary (`.github/workflows/release-canary.yml`) smoke-tests the arti
| Job | Runner | Verifies |
|---|---|---|
| `macos` | `macos-latest-xlarge` | `install.sh` resolves the Homebrew formula, brew installs the cask, and `openshell status` reaches the brew-services–backed local gateway with the VM driver. |
| `ubuntu` | `ubuntu-latest` | `install.sh` installs the Debian package, the post-install systemd user service starts, and `openshell status` reaches the local gateway with the Docker driver. |
| `ubuntu-deb-native-docker` | `ubuntu-latest` | `install.sh` auto-detects the Debian package when both snapd and native Docker are present, installs the deb, the post-install systemd user service starts, and `openshell status` reaches the local gateway with the Docker driver. Once snapd 2.77 is released to `latest/stable`, `install.sh` should install the `openshell` snap here instead, even with native Docker present. This job should then be renamed to `ubuntu-snap-native-docker`, and its purpose will be to verify that the openshell snap installs and works when a native (non-snap) Docker is already present on the system. |
| `ubuntu-deb` | `ubuntu-latest` | `install.sh` installs the Debian package after snapd is fully removed (forcing the deb path), starts the systemd user service, and `openshell status` reaches the local gateway with the Docker driver. |
| `ubuntu-snap-without-docker` | `ubuntu-latest` | `install.sh` auto-detects and installs both the `openshell` and `docker` snaps from the Snap Store when snapd is present and there is no Docker daemon on the system, the gateway daemon starts with auto-connected interfaces, and `openshell status` reaches the local gateway. |
| `fedora` | `fedora:latest` container | `install.sh` installs the RPM packages, the local gateway starts under Podman, and `openshell status` succeeds. |
| `kubernetes` | `ubuntu-latest` + kind | `helm install oci://ghcr.io/nvidia/openshell/helm-chart --version 0.0.0-dev` succeeds in a kind cluster, the gateway pod becomes Ready, port-forward exposes 8080, and the released CLI registers the in-cluster gateway and runs `openshell status` against it. |

Expand Down Expand Up @@ -107,8 +109,9 @@ Loopback registration auto-derives the gateway name to `openshell` if `--name` i

| Symptom | Likely cause | Where to look |
|---|---|---|
| `macos`/`ubuntu`/`fedora` job fails on `install.sh` | Latest tagged release missing an asset, checksum mismatch, or `install.sh` regression on this branch. | Job log around the `curl … install.sh \| sh` step. |
| `macos`/`ubuntu`/`fedora` job fails on `openshell status` | Local gateway service did not start (systemd/brew/podman). Often a driver issue. | Service logs in the job log; `OPENSHELL_DRIVERS` env in the "Ensure …" step. |
| `macos`/`ubuntu-deb-native-docker`/`ubuntu-deb`/`fedora` job fails on `install.sh` | Latest tagged release missing an asset, checksum mismatch, or `install.sh` regression on this branch. | Job log around the `curl … install.sh \| sh` step. |
| `macos`/`ubuntu-deb-native-docker`/`ubuntu-deb`/`fedora` job fails on `openshell status` | Local gateway service did not start (systemd/brew/podman). Often a driver issue. | Service logs in the job log; `OPENSHELL_DRIVERS` env in the "Ensure …" step. |
| `ubuntu-snap-without-docker` job fails on `openshell status` | Snap gateway daemon did not start. | `snap services openshell` and `snap logs openshell.gateway` in the job log. |
| `kubernetes` job fails on `helm install --wait` | Chart did not deploy in 5 min — usually image pull failure or readiness probe failing. | "Diagnostics on failure" step dumps `helm status`, manifest, pod describe, pod logs. |
| `kubernetes` job fails on `kubectl wait` | Gateway pod stuck `CrashLoopBackOff` or `ImagePullBackOff`. | Diagnostics dump; check `:dev` image existence at `ghcr.io/nvidia/openshell/gateway`. |
| `kubernetes` job fails on `openshell gateway add` or `status` | Port-forward not reachable, or CLI/gateway proto mismatch. | `port-forward.log` and `openshell gateway list` in the diagnostics dump. |
Expand Down
136 changes: 84 additions & 52 deletions .github/workflows/release-canary.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,17 @@ jobs:
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/${{ github.event.workflow_run.head_sha || github.sha }}/install.sh | sh
openshell status

ubuntu:
name: Ubuntu Docker
ubuntu-deb-native-docker:
name: Ubuntu (native Docker)
if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
runs-on: ubuntu-latest
timeout-minutes: 20
# TODO: Once snapd 2.77 is released to latest/stable, the openshell snap
# will be able to connect to system Docker via the docker interface,
# removing the requirement for the docker snap. At that point,
# install.sh should select snap here even with native Docker present.
# Rename this job to `ubuntu-snap-native-docker`, replace the dpkg
# assertion below with `snap list openshell`.
steps:
- name: Ensure Docker
run: |
Expand All @@ -50,6 +56,82 @@ jobs:
- name: Install and check status
run: |
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/${{ github.event.workflow_run.head_sha || github.sha }}/install.sh | sh
# Expected to fail once snapd 2.77 is in latest/stable, at which
# point install.sh should select snap instead of deb here.
dpkg -l openshell | grep '^ii'
openshell --version
systemctl --user is-active openshell-gateway
openshell status

ubuntu-deb:
name: Ubuntu Debian package
if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- name: Remove snapd
run: |
set -euo pipefail
# Remove all snaps in a single transaction. Core bases and content
# providers cannot be removed before snaps that consume them, so
# removing one at a time fails; snap handles ordering within a
# single `snap remove` invocation.
snaps=$(snap list 2>/dev/null | awk 'NR>1 {print $1}')
if [ -n "$snaps" ]; then
sudo snap remove $snaps
fi
sudo apt-get -y --purge remove snapd
! command -v snap >/dev/null 2>&1

- name: Ensure Docker
run: |
if ! command -v docker >/dev/null 2>&1; then
sudo apt-get update
sudo apt-get install -y docker.io
fi
sudo systemctl start docker || sudo service docker start
mkdir -p "${HOME}/.config/openshell"
printf 'OPENSHELL_DRIVERS=docker\n' > "${HOME}/.config/openshell/gateway.env"

@krishicks krishicks Jul 17, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this line required? I would have expected gateway auto-detection of Docker to work.

docker info

- name: Install and check status
run: |
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/${{ github.event.workflow_run.head_sha || github.sha }}/install.sh | sh
dpkg -l openshell | grep '^ii'
openshell --version
systemctl --user is-active openshell-gateway
openshell status

ubuntu-snap-without-docker:
name: Ubuntu without Docker preinstalled
if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- name: Ensure snapd
run: |
set -euo pipefail
sudo apt-get update
sudo apt-get install -y snapd
sudo systemctl enable --now snapd.socket
sudo systemctl start snapd
sudo snap wait system seed.loaded

- name: Remove native Docker
run: |
set -euo pipefail
sudo systemctl stop docker.service docker.socket 2>/dev/null || true
sudo apt-get -y --purge remove docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin docker.io 2>/dev/null || true
! command -v docker >/dev/null 2>&1

- name: Install and check status
run: |
set -euo pipefail
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/${{ github.event.workflow_run.head_sha || github.sha }}/install.sh | sh
snap list openshell
openshell --version
sudo snap services openshell
openshell status

fedora:
Expand Down Expand Up @@ -145,56 +227,6 @@ jobs:
run: |
docker rm -f "${FEDORA_CANARY_CONTAINER}" >/dev/null 2>&1 || true

ubuntu-snap:
name: Ubuntu Snap
if: ${{ github.event.workflow_run.conclusion == 'success' }}
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- name: Install snapd
run: |
set -euo pipefail
sudo apt-get update
sudo apt-get install -y snapd
sudo systemctl enable --now snapd.socket
sudo systemctl start snapd
sudo snap wait system seed.loaded

- name: Install Docker snap
run: |
set -euo pipefail
sudo snap install docker

- name: Download snap from release-dev artifacts
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
with:
github-token: ${{ github.token }}
run-id: ${{ github.event.workflow_run.id }}
pattern: snap-linux-amd64
path: release/
merge-multiple: true

- name: Install snap (dangerous — from release, not store)
run: |
set -euo pipefail
sudo snap install ./release/*.snap --dangerous

- name: Connect interfaces
run: |
set -euo pipefail
sudo snap connect openshell:docker docker:docker-daemon
sudo snap connect openshell:log-observe
sudo snap connect openshell:system-observe

- name: Register snap gateway and check status
run: |
set -euo pipefail
openshell --version
sudo snap services openshell
openshell gateway add http://127.0.0.1:17670 --local --name snap-docker
openshell gateway select snap-docker
openshell status

kubernetes:
name: Kubernetes Helm (kind)
if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
Expand Down
74 changes: 62 additions & 12 deletions docs/about/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -51,9 +54,15 @@ brew services restart openshell

## Linux

On distributions that ship with `snapd`, the install script uses the Snap path
described below, unless one of the following is true:

- `snapd` is not present
- a native (non-snap) Docker package is present (the `openshell` snap requires the `docker` snap, until snapd 2.77 is released to the `latest/stable` channel)

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.
On Debian and Ubuntu (where the snap is not applicable), 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.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.

Expand All @@ -77,7 +86,12 @@ sudo loginctl enable-linger $USER

## Snap

Install the OpenShell snap from the Snap Store:
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
Expand All @@ -94,19 +108,24 @@ typically `~/snap/openshell/common`. Gateway registrations live under
`$SNAP_USER_COMMON/.config/openshell/gateways/` instead of
`~/.config/openshell/gateways/`.

### Snap store installs

When installing from the Snap Store, snapd automatically connects the `home`,
`network`, and `network-bind` plugs. The `docker` plug still
requires manual connection:
The OpenShell snap requires the Docker snap, which you can install with:

@krishicks krishicks Jul 17, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the OpenShell snap requires the Docker snap, does that also mean it cannot be used with Podman? I'm wondering what this means for auto-detection, which prefers Podman over Docker. It seems like we need to document this limitation of the snap more clearly, if that's the case. I'd expect to see the docs say very clearly that the snap only works with Docker and you should configure Docker as the openshell driver explicitly to avoid issues if you also have Podman running.


```shell
sudo snap connect openshell:docker docker:docker-daemon
sudo snap install docker
```

The snap declares `default-provider: docker` on the Docker plug so snapd will
offer to install the Docker snap, but the connection itself must be made
manually.
### Snap store installs

When installing from the Snap Store, snapd automatically connects the `docker`,
`home`, `log-observe`, `network`, `network-bind`, and `system-observe plugs.

The `docker` interface is used to connect the `openshell` snap's `docker` plug
to the `docker` snap's `docker-daemon` slot; the `openshell` snap does not yet
work with a host-installed Docker Engine. The installer runs this and the other
interface connections for you after installing the `openshell` snap; run them
by hand if you install the snap manually. 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.

### Locally built snap packages

Expand All @@ -127,6 +146,26 @@ to read logs and inspect system processes. The `docker` plug requires the
`docker:docker-daemon` slot from the Docker snap and does not work with
system-installed Docker.

### 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 http://127.0.0.1:17670 --local --name openshell
openshell status
```

The gateway listens on `http://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`.

### Gateway service

The gateway runs as a snap daemon with `refresh-mode: endure`, meaning snapd
Expand All @@ -138,6 +177,17 @@ a snap refresh when you need the updated binary:
sudo systemctl restart snap.openshell.gateway
```

### When to choose Snap

Use the `openshell` snap when `snapd` is available and no native Docker Engine
is installed, and you want atomic upgrades and rollback, a single self-contained
and sandboxed install, or a desktop launcher that surfaces the OpenShell
terminal UI in the application menu.

Use the `openshell` `.deb` or `.rpm` file when `snapd` is unavailable or when
you already run Docker from a non-snap source. The installer falls back to
these methods on hosts with native Docker.

## 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).
Expand Down
Loading
Loading