feat(runtime): add centralized runtime registration system

.claude/skills/add-runtime

@@ -0,0 +1 @@
+../../skills/add-runtime

AGENTS.md

@@ -186,6 +186,41 @@ type InstanceData struct {
 }
 ```
 
+### Runtime System
+
+The runtime system provides a pluggable architecture for managing workspaces on different container/VM platforms (Podman, MicroVM, Kubernetes, etc.).
+
+**Key Components:**
+- **Runtime Interface** (`pkg/runtime/runtime.go`): Contract all runtimes must implement
+- **Registry** (`pkg/runtime/registry.go`): Manages runtime registration and discovery
+- **Runtime Implementations** (`pkg/runtime/<runtime-name>/`): Platform-specific packages (e.g., `fake`)
+- **Centralized Registration** (`pkg/runtimesetup/register.go`): Automatically registers all available runtimes
+
+**Adding a New Runtime:**
+
+Use the `/add-runtime` skill which provides step-by-step instructions for creating a new runtime implementation. The `fake` runtime in `pkg/runtime/fake/` serves as a reference implementation.
+
+**Runtime Registration in Commands:**
+
+Commands use `runtimesetup.RegisterAll()` to automatically register all available runtimes:
+
+```go
+import "github.com/kortex-hub/kortex-cli/pkg/runtimesetup"
+
+// In command preRun
+manager, err := instances.NewManager(storageDir)
+if err != nil {
+    return err
+}
+
+// Register all available runtimes
+if err := runtimesetup.RegisterAll(manager); err != nil {
+    return err
+}
+```
+
+This automatically registers all runtimes from `pkg/runtimesetup/register.go` that report as available (e.g., only registers Podman if `podman` CLI is installed).
+
 ### Skills System
 Skills are reusable capabilities that can be discovered and executed by AI agents:
 - **Location**: `skills/<skill-name>/SKILL.md`

pkg/cmd/init.go

@@ -25,7 +25,7 @@ import (
 	"path/filepath"
 
 	"github.com/kortex-hub/kortex-cli/pkg/instances"
-	"github.com/kortex-hub/kortex-cli/pkg/runtime/fake"
+	"github.com/kortex-hub/kortex-cli/pkg/runtimesetup"
 	"github.com/spf13/cobra"
 )
 
@@ -74,10 +74,9 @@ func (i *initCmd) preRun(cmd *cobra.Command, args []string) error {
 		return outputErrorIfJSON(cmd, i.output, fmt.Errorf("failed to create manager: %w", err))
 	}
 
-	// Register fake runtime (for testing)
-	// TODO: In production, register only the runtimes that are available/configured
-	if err := manager.RegisterRuntime(fake.New()); err != nil {
-		return outputErrorIfJSON(cmd, i.output, fmt.Errorf("failed to register fake runtime: %w", err))
+	// Register all available runtimes
+	if err := runtimesetup.RegisterAll(manager); err != nil {
+		return outputErrorIfJSON(cmd, i.output, fmt.Errorf("failed to register runtimes: %w", err))
 	}
 
 	i.manager = manager

pkg/cmd/workspace_remove.go

@@ -26,7 +26,7 @@ import (
 
 	api "github.com/kortex-hub/kortex-cli-api/cli/go"
 	"github.com/kortex-hub/kortex-cli/pkg/instances"
-	"github.com/kortex-hub/kortex-cli/pkg/runtime/fake"
+	"github.com/kortex-hub/kortex-cli/pkg/runtimesetup"
 	"github.com/spf13/cobra"
 )
 
@@ -71,10 +71,9 @@ func (w *workspaceRemoveCmd) preRun(cmd *cobra.Command, args []string) error {
 		return outputErrorIfJSON(cmd, w.output, fmt.Errorf("failed to create manager: %w", err))
 	}
 
-	// Register fake runtime (for testing)
-	// TODO: In production, register only the runtimes that are available/configured
-	if err := manager.RegisterRuntime(fake.New()); err != nil {
-		return outputErrorIfJSON(cmd, w.output, fmt.Errorf("failed to register fake runtime: %w", err))
+	// Register all available runtimes
+	if err := runtimesetup.RegisterAll(manager); err != nil {
+		return outputErrorIfJSON(cmd, w.output, fmt.Errorf("failed to register runtimes: %w", err))
 	}
 
 	w.manager = manager

pkg/cmd/workspace_start.go

@@ -26,7 +26,7 @@ import (
 
 	api "github.com/kortex-hub/kortex-cli-api/cli/go"
 	"github.com/kortex-hub/kortex-cli/pkg/instances"
-	"github.com/kortex-hub/kortex-cli/pkg/runtime/fake"
+	"github.com/kortex-hub/kortex-cli/pkg/runtimesetup"
 	"github.com/spf13/cobra"
 )
 
@@ -71,10 +71,9 @@ func (w *workspaceStartCmd) preRun(cmd *cobra.Command, args []string) error {
 		return outputErrorIfJSON(cmd, w.output, fmt.Errorf("failed to create manager: %w", err))
 	}
 
-	// Register fake runtime (for testing)
-	// TODO: In production, register only the runtimes that are available/configured
-	if err := manager.RegisterRuntime(fake.New()); err != nil {
-		return outputErrorIfJSON(cmd, w.output, fmt.Errorf("failed to register fake runtime: %w", err))
+	// Register all available runtimes
+	if err := runtimesetup.RegisterAll(manager); err != nil {
+		return outputErrorIfJSON(cmd, w.output, fmt.Errorf("failed to register runtimes: %w", err))
 	}
 
 	w.manager = manager

pkg/cmd/workspace_stop.go

@@ -26,7 +26,7 @@ import (
 
 	api "github.com/kortex-hub/kortex-cli-api/cli/go"
 	"github.com/kortex-hub/kortex-cli/pkg/instances"
-	"github.com/kortex-hub/kortex-cli/pkg/runtime/fake"
+	"github.com/kortex-hub/kortex-cli/pkg/runtimesetup"
 	"github.com/spf13/cobra"
 )
 
@@ -71,10 +71,9 @@ func (w *workspaceStopCmd) preRun(cmd *cobra.Command, args []string) error {
 		return outputErrorIfJSON(cmd, w.output, fmt.Errorf("failed to create manager: %w", err))
 	}
 
-	// Register fake runtime (for testing)
-	// TODO: In production, register only the runtimes that are available/configured
-	if err := manager.RegisterRuntime(fake.New()); err != nil {
-		return outputErrorIfJSON(cmd, w.output, fmt.Errorf("failed to register fake runtime: %w", err))
+	// Register all available runtimes
+	if err := runtimesetup.RegisterAll(manager); err != nil {
+		return outputErrorIfJSON(cmd, w.output, fmt.Errorf("failed to register runtimes: %w", err))
 	}
 
 	w.manager = manager

pkg/runtimesetup/register.go

@@ -0,0 +1,87 @@
+// 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 runtimesetup provides centralized registration of all available runtime implementations.
+package runtimesetup
+
+import (
+	"github.com/kortex-hub/kortex-cli/pkg/runtime"
+	"github.com/kortex-hub/kortex-cli/pkg/runtime/fake"
+)
+
+// Registrar is an interface for types that can register runtimes.
+// This is implemented by instances.Manager.
+type Registrar interface {
+	RegisterRuntime(rt runtime.Runtime) error
+}
+
+// Available is an optional interface that runtimes can implement
+// to report whether they are available in the current environment.
+//
+// This allows runtimes to check for:
+//   - Operating system compatibility
+//   - Required CLI tools or binaries
+//   - Configuration prerequisites
+//   - License or permission requirements
+//
+// Example implementation:
+//
+//	type myRuntime struct {}
+//
+//	func (r *myRuntime) Available() bool {
+//	    // Check if required CLI tool exists
+//	    _, err := exec.LookPath("my-tool")
+//	    return err == nil
+//	}
+type Available interface {
+	// Available returns true if the runtime is available in the current environment.
+	Available() bool
+}
+
+// runtimeFactory is a function that creates a new runtime instance.
+type runtimeFactory func() runtime.Runtime
+
+// availableRuntimes is the list of all runtimes that can be registered.
+// Add new runtimes here to make them available for automatic registration.
+var availableRuntimes = []runtimeFactory{
+	fake.New,
+}
+
+// RegisterAll registers all available runtimes to the given registrar.
+// It skips runtimes that implement the Available interface and report false.
+// Returns an error if any runtime fails to register.
+func RegisterAll(registrar Registrar) error {
+	return registerAllWithAvailable(registrar, availableRuntimes)
+}
+
+// registerAllWithAvailable registers the given runtimes to the registrar.
+// It skips runtimes that implement the Available interface and report false.
+// Returns an error if any runtime fails to register.
+// This function is internal and used for testing with custom runtime lists.
+func registerAllWithAvailable(registrar Registrar, factories []runtimeFactory) error {
+	for _, factory := range factories {
+		rt := factory()
+
+		// Skip runtimes that are not available in this environment
+		if avail, ok := rt.(Available); ok && !avail.Available() {
+			continue
+		}
+
+		if err := registrar.RegisterRuntime(rt); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}

pkg/runtimesetup/register_test.go

@@ -0,0 +1,163 @@
+// 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 runtimesetup
+
+import (
+	"context"
+	"fmt"
+	"testing"
+
+	"github.com/kortex-hub/kortex-cli/pkg/runtime"
+)
+
+// fakeRegistrar is a test implementation of Registrar
+type fakeRegistrar struct {
+	registered []runtime.Runtime
+	failNext   bool
+}
+
+func (f *fakeRegistrar) RegisterRuntime(rt runtime.Runtime) error {
+	if f.failNext {
+		f.failNext = false
+		return runtime.ErrRuntimeNotFound // reusing an error for testing
+	}
+	f.registered = append(f.registered, rt)
+	return nil
+}
+
+// testRuntime is a simple test runtime implementation
+type testRuntime struct {
+	runtimeType string
+	available   bool
+}
+
+func (t *testRuntime) Type() string { return t.runtimeType }
+
+func (t *testRuntime) Create(ctx context.Context, params runtime.CreateParams) (runtime.RuntimeInfo, error) {
+	return runtime.RuntimeInfo{}, fmt.Errorf("not implemented")
+}
+
+func (t *testRuntime) Start(ctx context.Context, id string) (runtime.RuntimeInfo, error) {
+	return runtime.RuntimeInfo{}, fmt.Errorf("not implemented")
+}
+
+func (t *testRuntime) Stop(ctx context.Context, id string) error {
+	return fmt.Errorf("not implemented")
+}
+
+func (t *testRuntime) Remove(ctx context.Context, id string) error {
+	return fmt.Errorf("not implemented")
+}
+
+func (t *testRuntime) Info(ctx context.Context, id string) (runtime.RuntimeInfo, error) {
+	return runtime.RuntimeInfo{}, fmt.Errorf("not implemented")
+}
+
+func (t *testRuntime) Available() bool {
+	return t.available
+}
+
+func TestRegisterAll(t *testing.T) {
+	t.Parallel()
+
+	t.Run("registers all runtimes", func(t *testing.T) {
+		t.Parallel()
+
+		registrar := &fakeRegistrar{}
+
+		// Create test runtimes
+		testFactories := []runtimeFactory{
+			func() runtime.Runtime { return &testRuntime{runtimeType: "test1", available: true} },
+			func() runtime.Runtime { return &testRuntime{runtimeType: "test2", available: true} },
+		}
+
+		err := registerAllWithAvailable(registrar, testFactories)
+		if err != nil {
+			t.Fatalf("registerAllWithAvailable() failed: %v", err)
+		}
+
+		// We should have registered 2 test runtimes
+		if len(registrar.registered) != 2 {
+			t.Errorf("Expected 2 runtimes to be registered, got %d", len(registrar.registered))
+		}
+
+		// Check that both types are present
+		types := make(map[string]bool)
+		for _, rt := range registrar.registered {
+			types[rt.Type()] = true
+		}
+
+		if !types["test1"] {
+			t.Error("Expected 'test1' runtime to be registered")
+		}
+		if !types["test2"] {
+			t.Error("Expected 'test2' runtime to be registered")
+		}
+	})
+
+	t.Run("skips unavailable runtimes", func(t *testing.T) {
+		t.Parallel()
+
+		registrar := &fakeRegistrar{}
+
+		// Create test runtimes with one unavailable
+		testFactories := []runtimeFactory{
+			func() runtime.Runtime { return &testRuntime{runtimeType: "test1", available: true} },
+			func() runtime.Runtime { return &testRuntime{runtimeType: "test2", available: false} },
+			func() runtime.Runtime { return &testRuntime{runtimeType: "test3", available: true} },
+		}
+
+		err := registerAllWithAvailable(registrar, testFactories)
+		if err != nil {
+			t.Fatalf("registerAllWithAvailable() failed: %v", err)
+		}
+
+		// We should have registered only 2 runtimes (test2 is unavailable)
+		if len(registrar.registered) != 2 {
+			t.Errorf("Expected 2 runtimes to be registered, got %d", len(registrar.registered))
+		}
+
+		// Check that only available runtimes are present
+		types := make(map[string]bool)
+		for _, rt := range registrar.registered {
+			types[rt.Type()] = true
+		}
+
+		if !types["test1"] {
+			t.Error("Expected 'test1' runtime to be registered")
+		}
+		if types["test2"] {
+			t.Error("Did not expect 'test2' runtime to be registered (unavailable)")
+		}
+		if !types["test3"] {
+			t.Error("Expected 'test3' runtime to be registered")
+		}
+	})
+
+	t.Run("returns error on registration failure", func(t *testing.T) {
+		t.Parallel()
+
+		registrar := &fakeRegistrar{failNext: true}
+
+		testFactories := []runtimeFactory{
+			func() runtime.Runtime { return &testRuntime{runtimeType: "test1", available: true} },
+		}
+
+		err := registerAllWithAvailable(registrar, testFactories)
+		if err == nil {
+			t.Fatal("Expected error when registration fails, got nil")
+		}
+	})
+}