feat(openshell): switch to official release binaries with version override

Replace rolling dev builds with official GitHub releases (v0.0.37).
Add --openshell-version flag to override the version at init time.
Cache binaries per version at <storageDir>/bin/<version>/ to avoid
conflicts. Remove --no-bootstrap flag unsupported in official CLI.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Florent Benoit <fbenoit@redhat.com>

Author: benoitf

AGENTS.md

@@ -180,6 +180,16 @@ The runtime system provides a pluggable architecture for managing workspaces on
 
 **To add a new runtime, use:** `/add-runtime`
 
+### OpenShell Runtime — Version Management
+
+The OpenShell runtime downloads three binaries (`openshell`, `openshell-gateway`, `openshell-driver-vm`) from official GitHub releases at `https://github.com/NVIDIA/OpenShell/releases`.
+
+**Default version constant:** `pkg/runtime/openshell/version.go` defines `DefaultVersion` (currently `v0.0.37`). To bump the default, edit this single constant.
+
+**`--openshell-version` flag:** Users can override the version at `kdn init` time (e.g., `kdn init --openshell-version v0.1.0`). The flag value flows through `RuntimeOptions["openshell-version"]` and is read in `Create()` before binaries are downloaded.
+
+**Binary caching:** Binaries are cached per version at `<storageDir>/bin/<version>/`. Different versions coexist without conflict.
+
 ### Podman Runtime — Deny-mode Networking
 
 When a workspace has `network.mode = deny`, the Podman runtime enforces outbound traffic filtering on every `Start()` using two layers. Allowed hosts come from `network.hosts` and are automatically augmented by host patterns derived from configured secrets. With no allowed hosts at all, the approval-handler denies every request (fully-isolated workspace).

pkg/runtime/openshell/create.go

@@ -39,6 +39,10 @@ func (r *openshellRuntime) Create(ctx context.Context, params runtime.CreatePara
 		return runtime.RuntimeInfo{}, err
 	}
 
+	if v := params.RuntimeOptions["openshell-version"]; v != "" {
+		r.version = v
+	}
+
 	driver := params.RuntimeOptions["openshell-driver"]
 
 	// Update driver in memory so ensureGatewayRunning uses the requested driver.
@@ -190,7 +194,7 @@ func (r *openshellRuntime) createSandbox(ctx context.Context, name string, agent
 	for _, p := range providers {
 		args = append(args, "--provider", p)
 	}
-	args = append(args, "--no-tty", "--no-bootstrap", "--", "true")
+	args = append(args, "--no-tty", "--", "true")
 	err := r.executor.Run(ctx, l.Stdout(), l.Stderr(), args...)
 	if err == nil {
 		return nil

pkg/runtime/openshell/download.go

@@ -27,10 +27,7 @@ import (
 )
 
 const (
-	openshellGatewayRelease  = "dev"
-	openshellRelease         = "dev"
-	openshellDriverVMRelease = "vm-dev"
-	githubRepo               = "NVIDIA/OpenShell"
+	githubRepo = "NVIDIA/OpenShell"
 )
 
 // platformAsset returns the asset name for the current platform.

pkg/runtime/openshell/gateway.go

@@ -117,7 +117,7 @@ func (r *openshellRuntime) hasActiveSandboxes(ctx context.Context) bool {
 func (r *openshellRuntime) ensureGatewayRunning(ctx context.Context) error {
 	// Download binaries on first use (deferred from Initialize to avoid
 	// network calls during runtime registration).
-	if err := r.ensureBinaries(); err != nil {
+	if err := r.ensureBinaries(ctx); err != nil {
 		return err
 	}
 

pkg/runtime/openshell/info.go

@@ -30,7 +30,7 @@ func (r *openshellRuntime) Info(ctx context.Context, id string) (runtime.Runtime
 		return runtime.RuntimeInfo{}, fmt.Errorf("%w: sandbox ID is required", runtime.ErrInvalidParams)
 	}
 
-	if err := r.ensureBinaries(); err != nil {
+	if err := r.ensureBinaries(ctx); err != nil {
 		return runtime.RuntimeInfo{}, err
 	}
 

pkg/runtime/openshell/openshell.go

@@ -16,6 +16,7 @@
 package openshell
 
 import (
+	"context"
 	"fmt"
 	"path/filepath"
 	"sync"
@@ -24,6 +25,7 @@ import (
 	"github.com/openkaiden/kdn/pkg/runtime/openshell/exec"
 	"github.com/openkaiden/kdn/pkg/secret"
 	"github.com/openkaiden/kdn/pkg/secretservice"
+	"github.com/openkaiden/kdn/pkg/steplogger"
 )
 
 const (
@@ -44,6 +46,7 @@ type openshellRuntime struct {
 	binariesErr           error
 	secretStore           secret.Store
 	secretServiceRegistry secretservice.Registry
+	version               string
 }
 
 // Ensure openshellRuntime implements runtime.Runtime at compile time.
@@ -100,6 +103,10 @@ func (r *openshellRuntime) Flags() []runtime.FlagDef {
 			Usage:       "OpenShell driver to use (podman, vm)",
 			Completions: []string{"podman", "vm"},
 		},
+		{
+			Name:  "openshell-version",
+			Usage: fmt.Sprintf("OpenShell version tag to download (default: %s)", DefaultVersion),
+		},
 	}
 }
 
@@ -128,30 +135,41 @@ func (r *openshellRuntime) Initialize(storageDir string) error {
 // openshell-driver-vm binaries if they are not already present.
 // It is safe to call from multiple entry points — the download
 // runs at most once per runtime instance.
-func (r *openshellRuntime) ensureBinaries() error {
+func (r *openshellRuntime) ensureBinaries(ctx context.Context) error {
 	r.binariesOnce.Do(func() {
-		r.binariesErr = r.downloadBinaries()
+		r.binariesErr = r.downloadBinaries(ctx)
 	})
 	return r.binariesErr
 }
 
-func (r *openshellRuntime) downloadBinaries() error {
-	binDir := filepath.Join(r.storageDir, "bin")
+func (r *openshellRuntime) resolveVersion() string {
+	if r.version != "" {
+		return r.version
+	}
+	return DefaultVersion
+}
+
+func (r *openshellRuntime) downloadBinaries(ctx context.Context) error {
+	version := r.resolveVersion()
+	binDir := filepath.Join(r.storageDir, "bin", version)
+
+	step := steplogger.FromContext(ctx)
+	step.Start(fmt.Sprintf("Downloading OpenShell %s binaries", version), fmt.Sprintf("OpenShell %s binaries ready", version))
 
-	gatewayPath, err := ensureBinary(binDir, "openshell-gateway", openshellGatewayRelease)
+	gatewayPath, err := ensureBinary(binDir, "openshell-gateway", version)
 	if err != nil {
 		return fmt.Errorf("failed to ensure openshell-gateway binary: %w", err)
 	}
 	r.gatewayBinaryPath = gatewayPath
 
-	openshellPath, err := ensureBinary(binDir, "openshell", openshellRelease)
+	openshellPath, err := ensureBinary(binDir, "openshell", version)
 	if err != nil {
 		return fmt.Errorf("failed to ensure openshell binary: %w", err)
 	}
 	r.executor = exec.New(openshellPath)
 
 	if _, assetErr := platformAsset("openshell-driver-vm"); assetErr == nil {
-		vmDriverPath, dlErr := ensureBinary(binDir, "openshell-driver-vm", openshellDriverVMRelease)
+		vmDriverPath, dlErr := ensureBinary(binDir, "openshell-driver-vm", version)
 		if dlErr != nil {
 			return fmt.Errorf("failed to ensure openshell-driver-vm binary: %w", dlErr)
 		}

pkg/runtime/openshell/openshell_test.go

@@ -15,6 +15,7 @@
 package openshell
 
 import (
+	"context"
 	"os"
 	"path/filepath"
 	"testing"
@@ -99,8 +100,8 @@ func TestOpenshellRuntime_Flags(t *testing.T) {
 	rt := &openshellRuntime{}
 	flags := rt.Flags()
 
-	if len(flags) != 1 {
-		t.Fatalf("Expected 1 flag, got %d", len(flags))
+	if len(flags) != 2 {
+		t.Fatalf("Expected 2 flags, got %d", len(flags))
 	}
 
 	if flags[0].Name != "openshell-driver" {
@@ -109,6 +110,10 @@ func TestOpenshellRuntime_Flags(t *testing.T) {
 	if len(flags[0].Completions) != 2 {
 		t.Errorf("Expected 2 completions for openshell-driver, got %d", len(flags[0].Completions))
 	}
+
+	if flags[1].Name != "openshell-version" {
+		t.Errorf("Expected second flag name 'openshell-version', got %q", flags[1].Name)
+	}
 }
 
 func TestOpenshellRuntime_SetSecretServiceRegistry(t *testing.T) {
@@ -183,7 +188,7 @@ func TestOpenshellRuntime_EnsureBinaries_SkipsWhenDepsInjected(t *testing.T) {
 	fakeExec := exec.NewFake()
 	rt := newWithDeps(fakeExec, "/fake/openshell-gateway", t.TempDir())
 
-	err := rt.ensureBinaries()
+	err := rt.ensureBinaries(context.Background())
 	if err != nil {
 		t.Fatalf("ensureBinaries() should be no-op for test deps: %v", err)
 	}
@@ -197,7 +202,7 @@ func TestDownloadBinaries_WithPreExistingBinaries(t *testing.T) {
 	t.Parallel()
 
 	storageDir := t.TempDir()
-	binDir := filepath.Join(storageDir, "bin")
+	binDir := filepath.Join(storageDir, "bin", DefaultVersion)
 	if err := os.MkdirAll(binDir, 0755); err != nil {
 		t.Fatalf("Failed to create bin dir: %v", err)
 	}
@@ -214,7 +219,7 @@ func TestDownloadBinaries_WithPreExistingBinaries(t *testing.T) {
 	}
 
 	rt := &openshellRuntime{storageDir: storageDir}
-	err := rt.downloadBinaries()
+	err := rt.downloadBinaries(context.Background())
 	if err != nil {
 		t.Fatalf("downloadBinaries() with existing binaries: %v", err)
 	}
@@ -231,7 +236,7 @@ func TestEnsureBinaries_RunsOnce(t *testing.T) {
 	t.Parallel()
 
 	storageDir := t.TempDir()
-	binDir := filepath.Join(storageDir, "bin")
+	binDir := filepath.Join(storageDir, "bin", DefaultVersion)
 	if err := os.MkdirAll(binDir, 0755); err != nil {
 		t.Fatalf("Failed to create bin dir: %v", err)
 	}
@@ -250,12 +255,13 @@ func TestEnsureBinaries_RunsOnce(t *testing.T) {
 	rt := &openshellRuntime{storageDir: storageDir}
 
 	// Call ensureBinaries twice — downloadBinaries should only execute once
-	if err := rt.ensureBinaries(); err != nil {
+	ctx := context.Background()
+	if err := rt.ensureBinaries(ctx); err != nil {
 		t.Fatalf("First ensureBinaries() call: %v", err)
 	}
 	firstExecutor := rt.executor
 
-	if err := rt.ensureBinaries(); err != nil {
+	if err := rt.ensureBinaries(ctx); err != nil {
 		t.Fatalf("Second ensureBinaries() call: %v", err)
 	}
 

pkg/runtime/openshell/remove.go

@@ -33,7 +33,7 @@ func (r *openshellRuntime) Remove(ctx context.Context, id string) error {
 		return fmt.Errorf("%w: sandbox ID is required", runtime.ErrInvalidParams)
 	}
 
-	if err := r.ensureBinaries(); err != nil {
+	if err := r.ensureBinaries(ctx); err != nil {
 		return err
 	}
 

pkg/runtime/openshell/terminal.go

@@ -28,7 +28,7 @@ func (r *openshellRuntime) Terminal(ctx context.Context, instanceID string, _ st
 		return fmt.Errorf("%w: instance ID is required", runtime.ErrInvalidParams)
 	}
 
-	if err := r.ensureBinaries(); err != nil {
+	if err := r.ensureBinaries(ctx); err != nil {
 		return err
 	}
 

pkg/runtime/openshell/version.go

@@ -0,0 +1,19 @@
+// Copyright 2026 Red Hat, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package openshell
+
+// DefaultVersion is the default OpenShell release tag used to download binaries.
+// Override at runtime with the --openshell-version flag on kdn init.
+const DefaultVersion = "v0.0.37"