Skip to content

fix: normalise the OpenShell version pin to a release tag - #48

Merged
vyncint merged 1 commit into
mainfrom
fix/openshell-version-tag
Aug 22, 2026
Merged

fix: normalise the OpenShell version pin to a release tag#48
vyncint merged 1 commit into
mainfrom
fix/openshell-version-tag

Conversation

@vyncint

@vyncint vyncint commented Aug 22, 2026

Copy link
Copy Markdown
Owner

Two things, both found by actually running against newer upstreams as asked.

--openshell-version has never worked

OpenShell tags every release vX.Y.Z, and its installer uses OPENSHELL_VERSION verbatim as the tag in the asset URL. So the value our own README documented asked for a release that does not exist:

URL
…/releases/download/0.0.97/openshell.rb 404
…/releases/download/v0.0.97/openshell.rb 200
…/releases/download/0.0.111/openshell.rb 404
…/releases/download/v0.0.111/openshell.rb 200

Reproduced exactly: OPENSHELL_VERSION=0.0.111 died with failed to download …/0.0.111/openshell.rb; the selected release may not include a Homebrew formula, and v0.0.111 installed cleanly. Broken since the flag shipped in v0.2.7 — the documented example never worked.

Both the Go path (update --all --openshell-version) and install.sh --openshell-version now normalise a bare X.Y.Z to vX.Y.Z. An explicit vX.Y.Z passes through, as does OpenShell's documented dev literal.

apple/container needs no such handling — its tags carry no v (1.2.2), and -v 1.2.2 worked as-is.

Compatibility now verified against 0.0.111 / 1.2.2

Live on the reference machine, upgraded from 0.0.97 / 1.2.0:

  • setup clean; derived supervisor:0.0.111 and pulled it
  • create → ReadyexecLinux 6.18.15 aarch64, workload as uid 998
  • network policy still enforced in-guest (egress 000/blocked)
  • restart adoption: agent kickstart → reconciled sandbox record … reason=BackendReady, exec still works
  • delete clean

Newer gateways are compatible by design, not luck. The contract gained four RPCs after v0.0.96 — GetGatewayListenerRequirements, StartSandbox, EnsureWorkspace, DeleteWorkspace — and this driver implements none. Three are optional by construction; from crates/openshell-server/src/compute/mod.rs:

Err(status) if status.code() == Code::Unimplemented => Ok(()),

StopSandbox/StartSandbox have no such branch, but are reached only by the new openshell sandbox stop/start commands, or by lifecycle sweeps guarded on gateway_manages_lifecycle — a capability this driver does not advertise, so those sweeps early-return. Confirmed what a user actually sees:

$ openshell sandbox stop full1
Error: × code: 'Operation is not implemented or not supported',
  message: "stop sandbox failed: StopSandbox is not implemented yet"

Clean failure of an unsupported command, nothing damaged. DriverSandboxSpec.command and .tty were also added and are silently ignored.

README, STATUS.md and docs/CONTRACT.md now state this rather than implying the v0.0.96 contract is current, and the release footer advertises the tested range.

Verification

go build, go test -race, golangci-lint (0 issues), shellcheck install.sh, goreleaser check, govulncheck/gosec/gitleaks — all clean. Unit test covers the normaliser including the dev and empty cases.

--openshell-version has never worked. OpenShell tags every release vX.Y.Z and
its installer uses OPENSHELL_VERSION verbatim as the tag in the asset URL, so
the value we documented -- `--openshell-version 0.0.97` -- asked for a release
that does not exist:

  https://github.com/NVIDIA/OpenShell/releases/download/0.0.97/openshell.rb  404
  https://github.com/NVIDIA/OpenShell/releases/download/v0.0.97/openshell.rb 200

and the install died with "the selected release may not include a Homebrew
formula". Broken since the flag shipped in v0.2.7; found while testing against
newer upstreams.

Normalise a bare X.Y.Z to vX.Y.Z in both the Go path and install.sh. An
explicit vX.Y.Z passes through, as does OpenShell's documented `dev` literal
for the rolling build.

Also record what the compatibility testing found. Verified live on OpenShell
0.0.111 and apple/container 1.2.2: create -> Ready -> exec -> delete, egress
still blocked by policy, restart adoption intact.

The contract gained four RPCs after v0.0.96 -- GetGatewayListenerRequirements,
StartSandbox, EnsureWorkspace, DeleteWorkspace -- none of which this driver
implements. Three are optional by construction: the gateway maps their
Unimplemented back to Ok. StopSandbox/StartSandbox are not, but are reached
only by the new `openshell sandbox stop`/`start` commands, or by lifecycle
sweeps gated on the gateway_manages_lifecycle capability this driver does not
advertise. README, STATUS.md and docs/CONTRACT.md now say so instead of
implying the v0.0.96 contract is still current.

Signed-off-by: Vyncint Ng <vyncint@users.noreply.github.com>
@vyncint
vyncint merged commit c436ff4 into main Aug 22, 2026
22 checks passed
@vyncint
vyncint deleted the fix/openshell-version-tag branch August 22, 2026 05:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant