From 9c7aae4fdad149da82b2feb828d1efda3726fc00 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 12 Oct 2026 08:10:20 -0700 Subject: [PATCH 1/9] docs(rfc): propose repository migration for a smaller core Signed-off-by: Drew Newberry --- rfc/0019-repository-migration/README.md | 98 +++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 rfc/0019-repository-migration/README.md diff --git a/rfc/0019-repository-migration/README.md b/rfc/0019-repository-migration/README.md new file mode 100644 index 0000000000..737dcbb9e0 --- /dev/null +++ b/rfc/0019-repository-migration/README.md @@ -0,0 +1,98 @@ +--- +authors: + - "@drew" +state: draft +links: + - https://github.com/NVIDIA/OpenShell/issues/4425 +--- + +# RFC 0019 - A Smaller Core and a Wider Tent + +## Summary + +Let's split OpenShell into a smaller core repository and a set of focused +repositories for platforms, packaging, SDKs, and provider integrations. The goal +is to make it easier for new maintainers to own a useful part of OpenShell while +keeping the core small enough to maintain well. + +## Motivation + +OpenShell covers a lot of ground. Someone who wants to maintain a Kubernetes +integration, a package, or an SDK shouldn't need to take on the whole project. +We want to widen the tent: give those contributors a clear home, ownership, and +room to move. + +A smaller core lets its maintainers focus on the runtime and the contracts that +hold the ecosystem together. The surrounding repositories can build communities +with their own expertise, test infrastructure, and release responsibilities. + +## Non-goals + +- Moving everything at once or settling every migration detail here. +- Promising runtime support just because a component builds on a platform. +- Redesigning the driver interfaces or deciding every release policy. + +## Proposal + +These are the proposed homes and responsibilities: + +| Repository | Owns and publishes | +| --- | --- | +| `openshell` | CLI, gateway, and supervisor builds for Linux, Windows, and macOS; Linux sandbox runtime with Linux, gVisor, Kata, and Firecracker support; prover; a compute driver that assembles these pieces as host processes. Publishes containers and binaries. | +| `openshell-desktop` | macOS isolation and container integration, Podman, Docker, and possibly microVM support. | +| `openshell-packages` | The one-line `install.sh` installation path and RPM, DEB, and Snap packages. | +| `openshell-homebrew` | The Homebrew tap and `openshell.rb` formula. | +| `openshell-windows` | MSI installer and MXC driver. | +| `openshell-kubernetes` | Helm chart, Kubernetes compute driver supporting gVisor, Kata, Firecracker, and runc, and an operator. Publishes the Helm chart. | +| `openshell-sdks` | Go, Python, Rust, and TypeScript SDKs. | +| `openshell-providers-` | One repository per provider, such as AWS, Google, OCI, or GitHub, with test infrastructure suited to that integration. | + +Each repository should have named maintainers and own its tests and published +artifacts. Core maintainers own the shared contracts; integration maintainers +own how their implementation uses them. We need clear compatibility expectations +so users can assemble a working OpenShell without guessing which versions fit. + +The platform and isolation entries above describe the proposed destination, +including future work. Moving code does not make those capabilities available. + +## Implementation plan + +1. Agree on the boundaries, find initial maintainers, and identify shared code + and interfaces that currently depend on being in one checkout. +2. Move one focused component first, preserving history where practical. Give + its new repository tests, release automation, contribution guidance, and a + documented compatibility relationship with core. +3. Move the remaining components incrementally. Update installation paths, + documentation, and contributor skills with each move, and validate that the + released pieces still work together before retiring their old paths. + +## Risks + +More repositories mean more release and CI coordination. Changes that cross a +boundary may take longer, and an integration can fall behind core. Explicit +ownership, compatibility checks, and a gradual migration should help, but this +only works if the new repositories attract maintainers. + +## Alternatives + +We could keep the monorepo and delegate ownership through CODEOWNERS and focused +CI. That reduces migration work, but leaves everyone sharing the same repository +and release machinery. We could also split only packaging and integrations +first, then decide whether SDKs and platform drivers benefit from moving. + +## Prior art + +[RFC 0012](../0012-isolation-backend/README.md) separates compute orchestration, +supervision, and isolation behind contracts. Those boundaries give us a starting +point for deciding what can live outside core. + +## Open questions + +- What macOS isolation mechanism do we mean by "appcontainer" in the original + outline, and what belongs alongside container support? +- Should microVM support live in desktop, core, or its own repository? +- How should the host compute driver launch and isolate processes? Is + `systemd-spawn` intended to mean `systemd-nspawn`, and what do other platforms use? +- Where do shared Rust interfaces live, and how do we test compatibility and + coordinate security fixes across repositories? +- Which component should move first, and who wants to maintain each new home? From 12da8372731e513cea31d2c2a38da5700cfa8c82 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 12 Oct 2026 08:23:45 -0700 Subject: [PATCH 2/9] docs(rfc): add Simon Scatton as repository migration author Signed-off-by: Drew Newberry --- rfc/0019-repository-migration/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/rfc/0019-repository-migration/README.md b/rfc/0019-repository-migration/README.md index 737dcbb9e0..12bd914af6 100644 --- a/rfc/0019-repository-migration/README.md +++ b/rfc/0019-repository-migration/README.md @@ -1,6 +1,7 @@ --- authors: - "@drew" + - "@SDAChess" state: draft links: - https://github.com/NVIDIA/OpenShell/issues/4425 From d3c1a83a7369d693b99d53d1120db446612718e6 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 27 Oct 2026 08:02:35 -0700 Subject: [PATCH 3/9] docs(rfc): detail repository structure and migration plan Signed-off-by: Drew Newberry --- rfc/0019-repository-migration/README.md | 162 +++++++++++++++++++----- 1 file changed, 127 insertions(+), 35 deletions(-) diff --git a/rfc/0019-repository-migration/README.md b/rfc/0019-repository-migration/README.md index 12bd914af6..3e439833ab 100644 --- a/rfc/0019-repository-migration/README.md +++ b/rfc/0019-repository-migration/README.md @@ -27,45 +27,144 @@ A smaller core lets its maintainers focus on the runtime and the contracts that hold the ecosystem together. The surrounding repositories can build communities with their own expertise, test infrastructure, and release responsibilities. -## Non-goals +## Proposal -- Moving everything at once or settling every migration detail here. -- Promising runtime support just because a component builds on a platform. -- Redesigning the driver interfaces or deciding every release policy. +Organize OpenShell around a core repository and focused ecosystem repositories. +The `openshell` core owns the runtime, CLI, Rust SDK, and shared interfaces that +hold the system together. Go, Python, and TypeScript each get an SDK repository. +Packages and Homebrew own installation and distribution; Windows, desktop, and +Kubernetes repositories own their platform integrations. Each provider gets a +repository for its integration and tests. + +The proposed repository structure is: + +```text +OpenShell repositories +├── openshell Gateway, supervisor, sandbox, CLI, Rust SDK, shared Rust interfaces +├── openshell-sdk-go Go SDK +├── openshell-sdk-python Python SDK +├── openshell-sdk-typescript TypeScript SDK +├── openshell-packages install.sh, RPM, DEB, snap +├── openshell-homebrew Homebrew tap and formula +├── openshell-windows MSI installer and MXC driver +├── openshell-desktop macOS App Sandbox, Podman, Docker +├── openshell-kubernetes Helm chart, Kubernetes driver, operator +└── openshell-providers- One repository per provider integration +``` + +This gives maintainers a focused area to own while keeping the shared contracts +in core. Each repository is responsible for its releases and compatibility with +the core versions it supports. + +### Core: `openshell` + +- CLI, built for Linux, Windows, and macOS. +- Gateway, built for Linux, Windows, and macOS. +- Supervisor, built for Linux, Windows, and macOS. +- Linux sandbox runtime, with support for Linux isolation, gVisor, Kata, and + Firecracker. +- Prover. +- Rust SDK, kept alongside the CLI as the reference client. +- Shared Rust interfaces used by components across repositories. +- A compute driver that assembles these components as processes on the host. + On Linux, use `systemd-nspawn` for launch and isolation. +- Publication of binaries. + +### SDK repositories + +Each other language SDK gets its own repository: -## Proposal +| Repository | Owns and publishes | +| --- | --- | +| `openshell-sdk-go` | Go SDK, with its own maintainers, tests, and releases. | +| `openshell-sdk-python` | Python SDK, with its own maintainers, tests, and releases. | +| `openshell-sdk-typescript` | TypeScript SDK, with its own maintainers, tests, and releases. | -These are the proposed homes and responsibilities: +The Rust SDK stays in core as the reference client used by the CLI. Keeping them +together lets changes to the gateway, SDK, and CLI be developed and tested in one +repository. Each other language SDK gets its own repository so maintainers can +own its language-specific tooling and release process. + +Core remains the source of truth for the public protobuf definitions. SDK +repositories should generate bindings from a pinned, published version of those +definitions, document which core releases they support, and test against those +releases. Automation should propose updates when core publishes new definitions +so separate repositories do not depend on manual copying to stay in sync. + +### Packaging and installation | Repository | Owns and publishes | | --- | --- | -| `openshell` | CLI, gateway, and supervisor builds for Linux, Windows, and macOS; Linux sandbox runtime with Linux, gVisor, Kata, and Firecracker support; prover; a compute driver that assembles these pieces as host processes. Publishes containers and binaries. | -| `openshell-desktop` | macOS isolation and container integration, Podman, Docker, and possibly microVM support. | -| `openshell-packages` | The one-line `install.sh` installation path and RPM, DEB, and Snap packages. | -| `openshell-homebrew` | The Homebrew tap and `openshell.rb` formula. | -| `openshell-windows` | MSI installer and MXC driver. | -| `openshell-kubernetes` | Helm chart, Kubernetes compute driver supporting gVisor, Kata, Firecracker, and runc, and an operator. Publishes the Helm chart. | -| `openshell-sdks` | Go, Python, Rust, and TypeScript SDKs. | -| `openshell-providers-` | One repository per provider, such as AWS, Google, OCI, or GitHub, with test infrastructure suited to that integration. | +| `openshell-packages` | The one-line `install.sh` installation path; publishes RPM, DEB, and snap packages. | +| `openshell-homebrew` | The Homebrew tap; publishes the `openshell.rb` formula. | + +### Windows: `openshell-windows` + +- MSI installer and its publication. +- MXC driver and its publication. + +### Desktop: `openshell-desktop` + +- macOS isolation through App Sandbox and container integration. +- Podman integration. +- Docker integration. +- Possible microVM support. Whether this belongs here, in core, or in a separate + repository remains an open question. + +### Kubernetes: `openshell-kubernetes` + +- Helm chart and its publication. +- Kubernetes compute driver, with support for gVisor, Kata, Firecracker, and runc. +- Kubernetes operator. + +### Provider repositories and ownership + +Each provider gets its own `openshell-providers-` repository, such as +`openshell-providers-aws`, `openshell-providers-google`, +`openshell-providers-oci`, or `openshell-providers-github`. Each owns its provider +integration and test infrastructure suited to that integration. Each repository should have named maintainers and own its tests and published -artifacts. Core maintainers own the shared contracts; integration maintainers -own how their implementation uses them. We need clear compatibility expectations +artifacts. Shared Rust interfaces live in core alongside the Rust SDK. Core +maintainers own these shared contracts; integration maintainers own how their +implementation uses them. We need clear compatibility expectations so users can assemble a working OpenShell without guessing which versions fit. -The platform and isolation entries above describe the proposed destination, -including future work. Moving code does not make those capabilities available. - ## Implementation plan -1. Agree on the boundaries, find initial maintainers, and identify shared code - and interfaces that currently depend on being in one checkout. -2. Move one focused component first, preserving history where practical. Give - its new repository tests, release automation, contribution guidance, and a - documented compatibility relationship with core. -3. Move the remaining components incrementally. Update installation paths, - documentation, and contributor skills with each move, and validate that the - released pieces still work together before retiring their old paths. +Migrate in the following order, preserving history where practical: + +1. **SDKs.** Move Go, Python, and TypeScript into their respective repositories. + Keep the Rust SDK and shared Rust interfaces in core. Establish the pinned + protobuf inputs, SDK release automation, and compatibility tests before + retiring the existing SDK paths. Document any package or import path changes. +2. **Packages.** Move `install.sh` and RPM, DEB, and snap packaging into + `openshell-packages`. Validate installation and removal using artifacts from + a pinned core release. +3. **Homebrew.** Move the tap and `openshell.rb` formula into + `openshell-homebrew`. Validate formula installation against published core + binaries. +4. **Windows.** Move the MSI installer and MXC driver into `openshell-windows`. + Establish builds, installer checks, and driver compatibility tests against + core. +5. **Kubernetes.** Move the Helm chart, Kubernetes compute driver, and operator + into `openshell-kubernetes`. Establish chart publication and deployment tests + against a pinned core release. +6. **Core.** Consolidate `openshell` around the CLI, gateway, supervisor, Linux + sandbox runtime, prover, Rust SDK, shared Rust interfaces, and host compute + driver. Update core builds and releases to consume the extracted components + where needed, and validate that the released pieces work together. Provider + integrations remain in place until the next phase. +7. **Providers.** Break out provider integrations one at a time into + `openshell-providers-`, with maintainers, releases, and test + infrastructure appropriate to each integration. + +Before each move, name the maintainers and identify dependencies on the shared +checkout. Each new repository owns its tests, release automation, contribution +guidance, and documented compatibility relationship with core. Update +installation paths, documentation, and contributor skills with each move, and +validate the replacement before retiring its old paths. Desktop migration timing +remains an open question. ## Risks @@ -89,11 +188,4 @@ point for deciding what can live outside core. ## Open questions -- What macOS isolation mechanism do we mean by "appcontainer" in the original - outline, and what belongs alongside container support? -- Should microVM support live in desktop, core, or its own repository? -- How should the host compute driver launch and isolate processes? Is - `systemd-spawn` intended to mean `systemd-nspawn`, and what do other platforms use? -- Where do shared Rust interfaces live, and how do we test compatibility and - coordinate security fixes across repositories? -- Which component should move first, and who wants to maintain each new home? +None From 6aa92a3721c4ff6ed355b523f668ebad2a4d7c21 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 27 Oct 2026 08:33:45 -0700 Subject: [PATCH 4/9] docs(rfc): add openshell-awesome repository Signed-off-by: Drew Newberry --- rfc/0019-repository-migration/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/rfc/0019-repository-migration/README.md b/rfc/0019-repository-migration/README.md index 3e439833ab..7412287bf4 100644 --- a/rfc/0019-repository-migration/README.md +++ b/rfc/0019-repository-migration/README.md @@ -49,7 +49,8 @@ OpenShell repositories ├── openshell-windows MSI installer and MXC driver ├── openshell-desktop macOS App Sandbox, Podman, Docker ├── openshell-kubernetes Helm chart, Kubernetes driver, operator -└── openshell-providers- One repository per provider integration +├── openshell-providers- One repository per provider integration +└── openshell-awesome Curated OpenShell resources and examples ``` This gives maintainers a focused area to own while keeping the shared contracts From 3d44997e184b0543b74aba4c9ae8d473baeda3d0 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 27 Oct 2026 08:39:19 -0700 Subject: [PATCH 5/9] docs(rfc): propose shared software factory repository Signed-off-by: Drew Newberry --- rfc/0019-repository-migration/README.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/rfc/0019-repository-migration/README.md b/rfc/0019-repository-migration/README.md index 7412287bf4..c4d33fed68 100644 --- a/rfc/0019-repository-migration/README.md +++ b/rfc/0019-repository-migration/README.md @@ -34,7 +34,9 @@ The `openshell` core owns the runtime, CLI, Rust SDK, and shared interfaces that hold the system together. Go, Python, and TypeScript each get an SDK repository. Packages and Homebrew own installation and distribution; Windows, desktop, and Kubernetes repositories own their platform integrations. Each provider gets a -repository for its integration and tests. +repository for its integration and tests. A shared software factory repository +provides automation and agent workflows for working across the OpenShell +organization's repositories. The proposed repository structure is: @@ -50,7 +52,8 @@ OpenShell repositories ├── openshell-desktop macOS App Sandbox, Podman, Docker ├── openshell-kubernetes Helm chart, Kubernetes driver, operator ├── openshell-providers- One repository per provider integration -└── openshell-awesome Curated OpenShell resources and examples +├── openshell-awesome Curated OpenShell resources and examples +└── openshell-software-factory Shared action templates, skills, and agents ``` This gives maintainers a focused area to own while keeping the shared contracts @@ -118,6 +121,17 @@ so separate repositories do not depend on manual copying to stay in sync. - Kubernetes compute driver, with support for gVisor, Kata, Firecracker, and runc. - Kubernetes operator. +### Software factory: `openshell-software-factory` + +- Shared GitHub Actions templates for repository automation. +- Skills for development and maintenance across OpenShell repositories. +- Agent definitions for coordinating work across repositories. + +This repository owns the shared tooling for working across the OpenShell +organization's repositories, including changes that span multiple repositories. +Component repositories use these common workflows alongside their own +component-specific tests and release processes. + ### Provider repositories and ownership Each provider gets its own `openshell-providers-` repository, such as From d600355a6a3da2ceb754810434928b5eed1226ec Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 27 Oct 2026 08:48:27 -0700 Subject: [PATCH 6/9] docs(rfc): refine proposed repository responsibilities Signed-off-by: Drew Newberry --- rfc/0019-repository-migration/README.md | 20 +++----------------- 1 file changed, 3 insertions(+), 17 deletions(-) diff --git a/rfc/0019-repository-migration/README.md b/rfc/0019-repository-migration/README.md index c4d33fed68..9490a3d32f 100644 --- a/rfc/0019-repository-migration/README.md +++ b/rfc/0019-repository-migration/README.md @@ -34,9 +34,7 @@ The `openshell` core owns the runtime, CLI, Rust SDK, and shared interfaces that hold the system together. Go, Python, and TypeScript each get an SDK repository. Packages and Homebrew own installation and distribution; Windows, desktop, and Kubernetes repositories own their platform integrations. Each provider gets a -repository for its integration and tests. A shared software factory repository -provides automation and agent workflows for working across the OpenShell -organization's repositories. +repository for its integration and tests. The proposed repository structure is: @@ -49,11 +47,10 @@ OpenShell repositories ├── openshell-packages install.sh, RPM, DEB, snap ├── openshell-homebrew Homebrew tap and formula ├── openshell-windows MSI installer and MXC driver -├── openshell-desktop macOS App Sandbox, Podman, Docker +├── openshell-desktop Desktop drivers: macOS App Sandbox, Podman, Docker, VM ├── openshell-kubernetes Helm chart, Kubernetes driver, operator ├── openshell-providers- One repository per provider integration -├── openshell-awesome Curated OpenShell resources and examples -└── openshell-software-factory Shared action templates, skills, and agents +└── openshell-awesome Curated OpenShell resources and examples ``` This gives maintainers a focused area to own while keeping the shared contracts @@ -121,17 +118,6 @@ so separate repositories do not depend on manual copying to stay in sync. - Kubernetes compute driver, with support for gVisor, Kata, Firecracker, and runc. - Kubernetes operator. -### Software factory: `openshell-software-factory` - -- Shared GitHub Actions templates for repository automation. -- Skills for development and maintenance across OpenShell repositories. -- Agent definitions for coordinating work across repositories. - -This repository owns the shared tooling for working across the OpenShell -organization's repositories, including changes that span multiple repositories. -Component repositories use these common workflows alongside their own -component-specific tests and release processes. - ### Provider repositories and ownership Each provider gets its own `openshell-providers-` repository, such as From 6567602f5a5a92579d557d9d0e4df628493f8a8e Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 27 Oct 2026 16:24:34 -0700 Subject: [PATCH 7/9] docs(rfc): retain Kubernetes in core and revise repository names Signed-off-by: Drew Newberry --- rfc/0019-repository-migration/README.md | 101 +++++++++++++----------- 1 file changed, 57 insertions(+), 44 deletions(-) diff --git a/rfc/0019-repository-migration/README.md b/rfc/0019-repository-migration/README.md index 9490a3d32f..a17d7da411 100644 --- a/rfc/0019-repository-migration/README.md +++ b/rfc/0019-repository-migration/README.md @@ -30,27 +30,30 @@ with their own expertise, test infrastructure, and release responsibilities. ## Proposal Organize OpenShell around a core repository and focused ecosystem repositories. -The `openshell` core owns the runtime, CLI, Rust SDK, and shared interfaces that -hold the system together. Go, Python, and TypeScript each get an SDK repository. -Packages and Homebrew own installation and distribution; Windows, desktop, and -Kubernetes repositories own their platform integrations. Each provider gets a -repository for its integration and tests. +The `openshell` core owns the runtime, CLI, Rust SDK, shared interfaces, and +Kubernetes integration. Go, Python, and TypeScript each get an SDK repository. +Packages and Homebrew own installation and distribution; Windows and desktop +repositories own their platform integrations. Each provider gets a repository +for its integration and tests. A `console` repository holds the frontend. + +The core repository keeps the name `openshell`. All other repository names omit +the `openshell-` prefix. The proposed repository structure is: ```text OpenShell repositories -├── openshell Gateway, supervisor, sandbox, CLI, Rust SDK, shared Rust interfaces -├── openshell-sdk-go Go SDK -├── openshell-sdk-python Python SDK -├── openshell-sdk-typescript TypeScript SDK -├── openshell-packages install.sh, RPM, DEB, snap -├── openshell-homebrew Homebrew tap and formula -├── openshell-windows MSI installer and MXC driver -├── openshell-desktop Desktop drivers: macOS App Sandbox, Podman, Docker, VM -├── openshell-kubernetes Helm chart, Kubernetes driver, operator -├── openshell-providers- One repository per provider integration -└── openshell-awesome Curated OpenShell resources and examples +├── openshell Gateway, supervisor, sandbox, CLI, Rust SDK, shared Rust interfaces, Kubernetes +├── sdk-go Go SDK +├── sdk-python Python SDK +├── sdk-typescript TypeScript SDK +├── packages install.sh, RPM, DEB, snap +├── homebrew Homebrew tap and formula +├── windows MSI installer and MXC driver +├── desktop Desktop drivers: macOS App Sandbox, Podman, Docker, VM +├── console OpenShell frontend +├── providers- One repository per provider integration +└── awesome Curated OpenShell resources and examples ``` This gives maintainers a focused area to own while keeping the shared contracts @@ -67,19 +70,26 @@ the core versions it supports. - Prover. - Rust SDK, kept alongside the CLI as the reference client. - Shared Rust interfaces used by components across repositories. +- Kubernetes compute driver, with support for gVisor, Kata, Firecracker, and runc. +- Helm chart and its publication. +- Kubernetes operator. - A compute driver that assembles these components as processes on the host. On Linux, use `systemd-nspawn` for launch and isolation. - Publication of binaries. +Kubernetes stays in core for this migration. After this RFC is implemented, +we will explore splitting the Helm chart, Kubernetes driver, and operator into +a separate repository. + ### SDK repositories Each other language SDK gets its own repository: | Repository | Owns and publishes | | --- | --- | -| `openshell-sdk-go` | Go SDK, with its own maintainers, tests, and releases. | -| `openshell-sdk-python` | Python SDK, with its own maintainers, tests, and releases. | -| `openshell-sdk-typescript` | TypeScript SDK, with its own maintainers, tests, and releases. | +| `sdk-go` | Go SDK, with its own maintainers, tests, and releases. | +| `sdk-python` | Python SDK, with its own maintainers, tests, and releases. | +| `sdk-typescript` | TypeScript SDK, with its own maintainers, tests, and releases. | The Rust SDK stays in core as the reference client used by the CLI. Keeping them together lets changes to the gateway, SDK, and CLI be developed and tested in one @@ -96,15 +106,15 @@ so separate repositories do not depend on manual copying to stay in sync. | Repository | Owns and publishes | | --- | --- | -| `openshell-packages` | The one-line `install.sh` installation path; publishes RPM, DEB, and snap packages. | -| `openshell-homebrew` | The Homebrew tap; publishes the `openshell.rb` formula. | +| `packages` | The one-line `install.sh` installation path; publishes RPM, DEB, and snap packages. | +| `homebrew` | The Homebrew tap; publishes the `openshell.rb` formula. | -### Windows: `openshell-windows` +### Windows: `windows` - MSI installer and its publication. - MXC driver and its publication. -### Desktop: `openshell-desktop` +### Desktop: `desktop` - macOS isolation through App Sandbox and container integration. - Podman integration. @@ -112,18 +122,18 @@ so separate repositories do not depend on manual copying to stay in sync. - Possible microVM support. Whether this belongs here, in core, or in a separate repository remains an open question. -### Kubernetes: `openshell-kubernetes` +### Console: `console` -- Helm chart and its publication. -- Kubernetes compute driver, with support for gVisor, Kata, Firecracker, and runc. -- Kubernetes operator. +The `console` repository holds the OpenShell frontend and owns its development, +tests, and releases. It consumes the public gateway API and documents which +core releases it supports. ### Provider repositories and ownership -Each provider gets its own `openshell-providers-` repository, such as -`openshell-providers-aws`, `openshell-providers-google`, -`openshell-providers-oci`, or `openshell-providers-github`. Each owns its provider -integration and test infrastructure suited to that integration. +Each provider gets its own `providers-` repository, such as +`providers-aws`, `providers-google`, `providers-oci`, or `providers-github`. +Each owns its provider integration and test infrastructure suited to that +integration. Each repository should have named maintainers and own its tests and published artifacts. Shared Rust interfaces live in core alongside the Rust SDK. Core @@ -140,24 +150,23 @@ Migrate in the following order, preserving history where practical: protobuf inputs, SDK release automation, and compatibility tests before retiring the existing SDK paths. Document any package or import path changes. 2. **Packages.** Move `install.sh` and RPM, DEB, and snap packaging into - `openshell-packages`. Validate installation and removal using artifacts from + `packages`. Validate installation and removal using artifacts from a pinned core release. 3. **Homebrew.** Move the tap and `openshell.rb` formula into - `openshell-homebrew`. Validate formula installation against published core + `homebrew`. Validate formula installation against published core binaries. -4. **Windows.** Move the MSI installer and MXC driver into `openshell-windows`. +4. **Windows.** Move the MSI installer and MXC driver into `windows`. Establish builds, installer checks, and driver compatibility tests against core. -5. **Kubernetes.** Move the Helm chart, Kubernetes compute driver, and operator - into `openshell-kubernetes`. Establish chart publication and deployment tests - against a pinned core release. -6. **Core.** Consolidate `openshell` around the CLI, gateway, supervisor, Linux - sandbox runtime, prover, Rust SDK, shared Rust interfaces, and host compute - driver. Update core builds and releases to consume the extracted components - where needed, and validate that the released pieces work together. Provider - integrations remain in place until the next phase. -7. **Providers.** Break out provider integrations one at a time into - `openshell-providers-`, with maintainers, releases, and test +5. **Core.** Consolidate `openshell` around the CLI, gateway, supervisor, Linux + sandbox runtime, prover, Rust SDK, shared Rust interfaces, host compute driver, + and Kubernetes integration. Keep the Helm chart, Kubernetes driver, operator, + chart publication, and deployment tests in core. Update core builds and + releases to consume the extracted components where needed, and validate that + the released pieces work together. Provider integrations remain in place + until the next phase. +6. **Providers.** Break out provider integrations one at a time into + `providers-`, with maintainers, releases, and test infrastructure appropriate to each integration. Before each move, name the maintainers and identify dependencies on the shared @@ -167,6 +176,10 @@ installation paths, documentation, and contributor skills with each move, and validate the replacement before retiring its old paths. Desktop migration timing remains an open question. +Create `console` as the home for frontend development, with its own tests, +release automation, and documented compatibility with core. After this RFC is +implemented, explore a separate Kubernetes repository as follow-up work. + ## Risks More repositories mean more release and CI coordination. Changes that cross a From 1abde95652c1069a3c64f2e2fb9f9ecca3b32ae3 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 27 Oct 2026 16:25:28 -0700 Subject: [PATCH 8/9] docs(rfc): consolidate Homebrew into packages repository Signed-off-by: Drew Newberry --- rfc/0019-repository-migration/README.md | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/rfc/0019-repository-migration/README.md b/rfc/0019-repository-migration/README.md index a17d7da411..70836d8f0a 100644 --- a/rfc/0019-repository-migration/README.md +++ b/rfc/0019-repository-migration/README.md @@ -32,7 +32,7 @@ with their own expertise, test infrastructure, and release responsibilities. Organize OpenShell around a core repository and focused ecosystem repositories. The `openshell` core owns the runtime, CLI, Rust SDK, shared interfaces, and Kubernetes integration. Go, Python, and TypeScript each get an SDK repository. -Packages and Homebrew own installation and distribution; Windows and desktop +The packages repository owns installation and distribution; Windows and desktop repositories own their platform integrations. Each provider gets a repository for its integration and tests. A `console` repository holds the frontend. @@ -47,8 +47,7 @@ OpenShell repositories ├── sdk-go Go SDK ├── sdk-python Python SDK ├── sdk-typescript TypeScript SDK -├── packages install.sh, RPM, DEB, snap -├── homebrew Homebrew tap and formula +├── packages install.sh, RPM, DEB, snap, Homebrew tap and formula ├── windows MSI installer and MXC driver ├── desktop Desktop drivers: macOS App Sandbox, Podman, Docker, VM ├── console OpenShell frontend @@ -106,8 +105,7 @@ so separate repositories do not depend on manual copying to stay in sync. | Repository | Owns and publishes | | --- | --- | -| `packages` | The one-line `install.sh` installation path; publishes RPM, DEB, and snap packages. | -| `homebrew` | The Homebrew tap; publishes the `openshell.rb` formula. | +| `packages` | The one-line `install.sh` installation path and Homebrew tap; publishes RPM, DEB, and snap packages and the `openshell.rb` formula. | ### Windows: `windows` @@ -149,23 +147,21 @@ Migrate in the following order, preserving history where practical: Keep the Rust SDK and shared Rust interfaces in core. Establish the pinned protobuf inputs, SDK release automation, and compatibility tests before retiring the existing SDK paths. Document any package or import path changes. -2. **Packages.** Move `install.sh` and RPM, DEB, and snap packaging into - `packages`. Validate installation and removal using artifacts from - a pinned core release. -3. **Homebrew.** Move the tap and `openshell.rb` formula into - `homebrew`. Validate formula installation against published core - binaries. -4. **Windows.** Move the MSI installer and MXC driver into `windows`. +2. **Packages.** Move `install.sh`, RPM, DEB, and snap packaging, and the Homebrew + tap and `openshell.rb` formula into `packages`. Validate installation and + removal using artifacts from a pinned core release, including formula + installation against published core binaries. +3. **Windows.** Move the MSI installer and MXC driver into `windows`. Establish builds, installer checks, and driver compatibility tests against core. -5. **Core.** Consolidate `openshell` around the CLI, gateway, supervisor, Linux +4. **Core.** Consolidate `openshell` around the CLI, gateway, supervisor, Linux sandbox runtime, prover, Rust SDK, shared Rust interfaces, host compute driver, and Kubernetes integration. Keep the Helm chart, Kubernetes driver, operator, chart publication, and deployment tests in core. Update core builds and releases to consume the extracted components where needed, and validate that the released pieces work together. Provider integrations remain in place until the next phase. -6. **Providers.** Break out provider integrations one at a time into +5. **Providers.** Break out provider integrations one at a time into `providers-`, with maintainers, releases, and test infrastructure appropriate to each integration. From d78276f7a922382af02ea84a2f3b12905152fe30 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 27 Oct 2026 20:28:09 -0700 Subject: [PATCH 9/9] docs(rfc): name curated resources repository awesome-list Signed-off-by: Drew Newberry --- rfc/0019-repository-migration/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/0019-repository-migration/README.md b/rfc/0019-repository-migration/README.md index 70836d8f0a..8980e4e95e 100644 --- a/rfc/0019-repository-migration/README.md +++ b/rfc/0019-repository-migration/README.md @@ -52,7 +52,7 @@ OpenShell repositories ├── desktop Desktop drivers: macOS App Sandbox, Podman, Docker, VM ├── console OpenShell frontend ├── providers- One repository per provider integration -└── awesome Curated OpenShell resources and examples +└── awesome-list Curated OpenShell resources and examples ``` This gives maintainers a focused area to own while keeping the shared contracts