From cb42f5d9e85bd53c9889e067eac04f94fd398ade Mon Sep 17 00:00:00 2001 From: Oliver Calder Date: Thu, 22 Oct 2026 17:12:02 +0000 Subject: [PATCH] fix(snap): use openshell-prover instead of openshell.prover (#4835) The alias `openshell-prover` has been granted for OpenShell: https://forum.snapcraft.io/t/alias-request-for-openshell/53658 Thus, we can remove guidance differentiating `openshell.prover` for the snap from `openshell-prover` for other packaging formats. It is still worth noting that installing a locally-built snap directly, rather than from the store, means there is no alias. Signed-off-by: Oliver Calder --- .agents/skills/test-release-canary/SKILL.md | 2 +- .github/workflows/release-canary.yml | 4 ++-- docs/about/installation.mdx | 5 +---- docs/about/support-matrix.mdx | 5 +---- docs/how-it-works/policies/prover.mdx | 11 +++-------- snapcraft.yaml | 6 +++--- tasks/scripts/test-packaging-assets.sh | 2 +- 7 files changed, 12 insertions(+), 23 deletions(-) diff --git a/.agents/skills/test-release-canary/SKILL.md b/.agents/skills/test-release-canary/SKILL.md index 5081c85e5..b707920b7 100644 --- a/.agents/skills/test-release-canary/SKILL.md +++ b/.agents/skills/test-release-canary/SKILL.md @@ -144,7 +144,7 @@ Loopback registration auto-derives the gateway name to `openshell` if `--name` i | Sandbox create or exec fails | Published sandbox and supervisor artifacts are missing, incompatible, or cannot establish the protected runtime channel. | Gateway logs plus Docker, Podman, VM, snap, or Kubernetes runtime diagnostics for the job. | | `macos`/`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_COMPUTE_DRIVER` env in the "Ensure …" step. | | `ubuntu-snap-system-docker` fails during `install.sh` | System Docker was unavailable to the runner user, the edge revision or automatic interfaces were unavailable, or the user gateway did not become reachable. | Failure diagnostics dump system Docker, snap service/connection/change state, user and legacy gateway journals, snap logs, and port 17670 listeners. | -| `ubuntu-snap-system-docker` fails during the prover checks | The prover artifact is missing or packaged for the wrong architecture, `openshell.prover` is not exposed or confined to read the test policies, or its solver linkage is not runnable. | The `Install and check status` and `Check a policy boundary with the snap prover` steps, plus `snap info openshell` and `snap connections openshell`. | +| `ubuntu-snap-system-docker` fails during the prover checks | The prover artifact is missing or packaged for the wrong architecture, `openshell.prover` is not exposed, missing the alias to `openshell-prover`, or not permitted to read the test policies, or its solver linkage is not runnable. | The `Install and check status` and `Check a policy boundary with the snap prover` steps, plus `snap info openshell` and `snap connections openshell`. | | `ubuntu-snap-docker-preflight` unexpectedly succeeds | The installer no longer fails before installing the OpenShell snap when Docker is absent or supplied by the Docker snap. | Inspect `install.log`, `docker-snap.log`, `snap list`, and snapd changes. | | `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`. | diff --git a/.github/workflows/release-canary.yml b/.github/workflows/release-canary.yml index 514a7bc8a..a8479db19 100644 --- a/.github/workflows/release-canary.yml +++ b/.github/workflows/release-canary.yml @@ -239,7 +239,7 @@ jobs: docker info sudo snap connections openshell | grep -E '^docker +openshell:docker +:docker +' openshell --version - openshell.prover --version + openshell-prover --version snap services openshell systemctl --user is-enabled --quiet snap.openshell.user-gateway.service systemctl --user is-active snap.openshell.user-gateway.service @@ -283,7 +283,7 @@ jobs: read_only: - /usr EOF - result=$(openshell.prover check "$prover_dir/candidate.yaml" \ + result=$(openshell-prover check "$prover_dir/candidate.yaml" \ --boundary "$prover_dir/boundary.yaml") grep -q '^result: within_boundary$' <<<"$result" diff --git a/docs/about/installation.mdx b/docs/about/installation.mdx index ff5af03da..2afc236ed 100644 --- a/docs/about/installation.mdx +++ b/docs/about/installation.mdx @@ -143,10 +143,7 @@ The global command prevents automatic activation for other users but does not st 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 -connect to the gateway. +The snap installs the standalone policy prover as `openshell.prover` with an alias to `openshell-prover`. Installs of locally-built snaps will not have the alias. The prover reads local policy files through the `home` interface and does not connect to the gateway. The gateway runs at `https://127.0.0.1:17670`. It reads `~/snap/openshell/common/.config/openshell/gateway.toml` when that file exists. Its database defaults to `~/snap/openshell/common/.local/state/openshell/gateway/openshell.db`, and its TLS material lives under `~/snap/openshell/common/.local/state/openshell/tls`. Register it from the same user account: diff --git a/docs/about/support-matrix.mdx b/docs/about/support-matrix.mdx index 155cf355a..d9852d35c 100644 --- a/docs/about/support-matrix.mdx +++ b/docs/about/support-matrix.mdx @@ -113,10 +113,7 @@ OpenShell publishes standalone `openshell-prover` release assets for manual down These artifacts are attached to GitHub releases. The Linux binaries are static and do not require glibc. All prover archives include the required solver linkage. -The Debian, RPM, Homebrew, and snap packages also include the prover. Debian, -RPM, and Homebrew installations expose it as `openshell-prover`; use -`openshell.prover` with the snap. The `openshell-prover` snap alias requires -Store approval and may not be available. +The Debian, RPM, Homebrew, and snap packages also include the prover. ## Runtimes diff --git a/docs/how-it-works/policies/prover.mdx b/docs/how-it-works/policies/prover.mdx index 87bacbc94..c2fa29782 100644 --- a/docs/how-it-works/policies/prover.mdx +++ b/docs/how-it-works/policies/prover.mdx @@ -36,10 +36,6 @@ contain access that the proposal risk check would flag. This page covers the boundary check. To learn about the proposal risk check, refer to [Policy Advisor](/how-it-works/policies/advisor). -For snap installations, replace `openshell-prover` in these examples with -`openshell.prover`. The `openshell-prover` snap alias requires Store approval -and may not be available. - The prover remains independent of the gateway at runtime. If you only need the standalone binary, use the artifacts listed in the [Support Matrix](/about/support-matrix#standalone-policy-prover). These @@ -60,10 +56,9 @@ or MCP rules, the prover reports that it cannot check the policy instead of ignoring those rules. [What the Boundary Check Covers](#what-the-boundary-check-covers) describes each part and its limits. -The Homebrew, Debian, RPM, and snap packages install the prover. Homebrew, -Debian, and RPM expose it as `openshell-prover`; use `openshell.prover` with the -snap. The CLI reads policy files on your machine, does not need a gateway, and -does not apply or approve policies. +The Homebrew, Debian, RPM, and snap packages install the prover. The CLI reads +policy files on your machine, does not need a gateway, and does not apply or +approve policies. Create `boundary.yaml`, a boundary that allows reading `/usr` and `/etc`: diff --git a/snapcraft.yaml b/snapcraft.yaml index 5278343d4..f5050a6a3 100644 --- a/snapcraft.yaml +++ b/snapcraft.yaml @@ -11,9 +11,9 @@ description: | policy-enforced egress routing, credential proxying, and privacy-aware profile-backed model-provider access. - The OpenShell snap ships a CLI (`openshell`), a terminal UI - (`openshell.term`), a standalone policy prover (`openshell.prover`), and a - managed gateway daemon (`openshell.user-gateway`). The user gateway is + The OpenShell snap ships a CLI (`openshell`), a terminal UI (`openshell.term`), + a standalone policy prover (`openshell.prover` with alias `openshell-prover`), + and a managed gateway daemon (`openshell.user-gateway`). The user gateway is disabled by default so that one selected user can run it. **Setup instructions** diff --git a/tasks/scripts/test-packaging-assets.sh b/tasks/scripts/test-packaging-assets.sh index e056d3121..5600370b6 100755 --- a/tasks/scripts/test-packaging-assets.sh +++ b/tasks/scripts/test-packaging-assets.sh @@ -260,7 +260,7 @@ assert_not_contains "$snap_install_docs" "snap services --user" assert_contains "$snap_canary" "install.sh | sh" assert_contains "$snap_canary" "ubuntu-snap-system-docker:" assert_contains "$snap_canary" "ubuntu-snap-docker-preflight:" -assert_contains "$snap_canary" "openshell.prover check" +assert_contains "$snap_canary" "openshell-prover check" assert_not_contains "$snap_canary" "--dangerous" assert_not_contains "$snap_canary" "snap connect openshell:docker" if ! awk '/config preflight/ { seen = 1 } /generate-certs/ { exit !seen }' "$service"; then