Skip to content

feat: match the supervisor image to the gateway, allow pinning prerequisites - #33

Merged
vyncint merged 1 commit into
mainfrom
feat/version-pinning-and-supervisor-match
Aug 5, 2026
Merged

feat: match the supervisor image to the gateway, allow pinning prerequisites#33
vyncint merged 1 commit into
mainfrom
feat/version-pinning-and-supervisor-match

Conversation

@vyncint

@vyncint vyncint commented Aug 5, 2026

Copy link
Copy Markdown
Owner

Started as "should we allow selecting OpenShell / apple-container versions?" — and turned up a live version mismatch on the reference machine, which this PR fixes alongside the requested feature.

1. Bug: the supervisor image tag didn't track the gateway

--supervisor-image defaulted to a hardcoded …/supervisor:0.0.96, but OpenShell's installer resolves its own latest release. On the reference machine that meant:

version
installed gateway 0.0.97
supervisor the driver used 0.0.96 (hardcoded)
supervisor:0.0.97 on the registry exists (HTTP 200) — just unused

The supervisor runs inside every sandbox and speaks the gateway's protocol, so this is a silent protocol mismatch, and nothing detected or reported it. It happened to work (0.0.96 ↔ 0.0.97 are compatible) — luck, not design. update --all runs brew upgrade openshell, which can move the gateway independently at any time.

Fix: the driver reads openshell-gateway --version and uses the matching supervisor:<version>. The compute-driver contract carries no gateway version, and the driver shares the host with the gateway, so the binary is the only source. Guardrails:

  • An explicit --supervisor-image / OSHL_AC_SUPERVISOR_IMAGE always wins (detected via flag.Visit + env lookup).
  • If the matching tag is unpublished, the single extraction call site falls back to the pinned image and warns — a create cannot regress into failing outright.
  • Shelling out is unsuitable for config.Parse, so resolution is an explicit call after parsing; forgetting it degrades to the pinned tag, never to an empty image.

2. Feature: pin the prerequisites

Only the driver's own release was selectable; OpenShell and apple/container always resolved to latest — installs weren't reproducible and a bad upstream release couldn't be rolled back. Both upstreams already support pinning, so this is pass-through:

curl -LsSf …/install.sh | sh -s -- --version v0.2.6 --openshell-version 0.0.97 --container-version 1.2.0
openshell-driver-applecontainer update --all --openshell-version 0.0.97 --container-version 1.2.0
  • OpenShell: its installer honors OPENSHELL_VERSION. brew can't install an arbitrary tap version, so a pin routes through the official installer — downloaded to a file and run as sh <file>, not piped into a shell, so a truncated fetch can't execute as a partial script.
  • apple/container: update-container.sh -v <ver>; the .pkg URL is already tag-based.
  • Env mirrors: OSHL_AC_OPENSHELL_VERSION, OSHL_AC_CONTAINER_VERSION. Defaults stay "latest" so users keep getting fixes; pinning is opt-in.
  • --openshell-version/--container-version without --all is rejected rather than silently ignored.

3. Visibility

setup now logs the resolved driver / gateway / apple-container versions and the supervisor image, and warns when the tag ≠ gateway. The README compatibility table said "pinned to v0.0.96", which no longer matched reality — corrected, and the pinning recipes documented.

Verification

  • Live: setup logged matched the supervisor image to the installed gateway gateway_version=0.0.97, then a sandbox reached Ready on the derived image — cache shows supervisor-0.0.97-523e0565f895 alongside the old 0.0.96 — with exec returning kernel 6.18.15. Version summary printed driver / gateway 0.0.97 / apple_container 1.2.0 and no mismatch warning.
  • Tests: supervisor resolution (matches gateway / respects explicit pin / falls back when unknown / Parse records explicitness) and version probing (gateway + container + v-prefix + junk + missing binary) with mismatch-warning assertions.
  • go test -race ./..., golangci-lint (0 issues), shellcheck, make sec all clean. install.sh -h now prints the header robustly (it was about to leak set -eu as the header grew).

Also fixed while here: cleanup -d removes the supervisor image the driver actually uses, not just the pinned default.

…uisites

The supervisor image tag was hardcoded to 0.0.96 while OpenShell's own
installer resolves its latest release, so a host running gateway 0.0.97
booted every sandbox with a 0.0.96 supervisor. That is a silent version
mismatch, not a cosmetic one: the supervisor runs inside the sandbox and
speaks the gateway's protocol. Nothing detected or reported it.

The driver now reads `openshell-gateway --version` (the compute contract
carries no gateway version, and the driver shares the host with the
gateway) and uses the matching supervisor tag. An explicit
--supervisor-image / OSHL_AC_SUPERVISOR_IMAGE still wins, and if the
matching tag is unpublished the single extraction call site falls back to
the pinned image so a create cannot regress into failing outright.

Only the driver's own release was selectable before; the prerequisites
always resolved to latest, which made installs irreproducible and left no
way to roll back a bad upstream release. Both upstreams support pinning,
so pass it through: install.sh gains --openshell-version and
--container-version (env OSHL_AC_OPENSHELL_VERSION,
OSHL_AC_CONTAINER_VERSION), and `update --all` gains the same two flags.
OpenShell pinning runs its official installer with OPENSHELL_VERSION set
(downloaded to a file first, so a truncated fetch cannot execute as a
partial script); apple/container uses `update-container.sh -v`.

setup now prints the resolved driver / gateway / apple-container versions
plus the supervisor image, and warns when the tag does not match the
gateway, so this class of drift is visible instead of silent.

Verified live: setup switched 0.0.96 -> 0.0.97 against the installed
gateway, and a sandbox reached Ready on the derived supervisor (cache
shows supervisor-0.0.97) with exec working.

Signed-off-by: Vyncint Ng <vyncint@users.noreply.github.com>
@vyncint
vyncint merged commit 0d35387 into main Aug 5, 2026
22 checks passed
@vyncint
vyncint deleted the feat/version-pinning-and-supervisor-match branch August 5, 2026 15:40
vyncint added a commit that referenced this pull request Aug 5, 2026
Supervisor image now tracks the installed gateway version; prerequisites
are pinnable; setup reports the component versions (#33).

Signed-off-by: Vyncint Ng <vyncint@users.noreply.github.com>
Co-authored-by: Vyncint Ng <vyncint@users.noreply.github.com>
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