docs(rfc): propose repository migration for a smaller core by drew · Pull Request #4426 · NVIDIA/OpenShell

drew · 2026-10-12T15:13:07Z

Summary

Propose splitting OpenShell into a smaller core and focused repositories so new maintainers can own platforms, packaging, SDKs, and provider integrations. Keep RFC 0019 short and conversational for early discussion.

Related Issue

Closes #4425

Changes

Define the proposed repository responsibilities and ownership expectations.
Outline an incremental migration, risks, and alternatives.
Leave macOS isolation, microVM placement, host process assembly, and cross-repository compatibility as open questions.

Testing

Markdown lint passes (mise exec -- markdownlint-cli2 rfc/0019-repository-migration/README.md).
git diff --check passes.
Unit and E2E tests are not applicable to this RFC-only change.

Checklist

Follows Conventional Commits
Commits are signed off (DCO)
Architecture documentation updates are not applicable to this draft proposal.

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

copy-pr-bot · 2026-10-12T15:13:11Z

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

politerealism · 2026-10-13T12:13:29Z

+| --- | --- |
+| `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. |


Simon pointed me here from #3510 (Fedora packaging), so a few notes from that work on where the packaging line might fall. Take these as ideas.

It might help to separate two kinds of packaging, because they couple to core very differently:

Repackaging published binaries (what openshell.spec does today via OPENSHELL_PREBUILT_BINARIES_DIR, and what install.sh does). This is loosely coupled to core: it needs a tag and the release artifacts.

Building from source in a distro's infrastructure (Fedora's Koji builds offline from source). This is tightly coupled. feat: package OpenShell for Fedora #3510 found several build-time contracts that currently live in core: the Rust toolchain pin and vendored dependencies, whether the build honors PROTOC instead of the bundled compiler (fix(build): honor PROTOC when generating protobuf code #4441), the Python proto stub generation (fix(rpm): build the Python SDK from older protoc and install every SDK module #4439), the Z3 bindings tied to z3-sys (feat: unbundle Z3 from gateway runtime packaging #1969), and static-PIE linking for the supervisor and sandbox binaries.

Oliver raised the lockstep concern on #4244: distro packaging needs build flags, dependencies and toolchain versions kept in sync with core. One way to keep a separate packages repo honest might be for core to document a small source-build contract (supported features, environment variables, minimum toolchain, expected outputs) and to run a cheap from-source smoke build in its own CI, so drift shows up in core before it reaches a packaging repo. That could also keep the option open of leaving the from-source recipes with core while openshell-packages owns publishing and installation.

politerealism · 2026-10-13T12:13:30Z

+  `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 the packaging side, the repackaging-published-binaries pieces (the RPM/DEB/Snap that consume release artifacts, install.sh, the Homebrew formula) look like the lowest-risk first move, since they don't depend on core's build flags. The from-source distro builds might be better to move once a source-build contract like the one above exists.

One question: how should artifacts from a packages repo feed core's release qualification? RFC 0016 says release qualification validates install and uninstall behavior using candidate artifacts, so it would be good to say whether the packages repo produces those artifacts for core's qualification to consume, or whether qualification runs from the packages repo against a pinned core release.

rhuss · 2026-10-14T08:32:01Z

+| `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. |


I wonder whether we could have one repo per SDK as I expect there is no much overlap in the maintainer group for each SDK, respectively. Since all language also uses different toolchains and setups, wdyt about using:

openshell-sdk-python

openshell-sdk-rust

openshell-sdk-typescript

openshell-sdk-go

For the rust SDK I could imagine to keep it in core as the reference SDK, especially if the CLI is leveraging the SDK, too, as part of core (which would lead to a circular dependency among repos).

Granularitywise this would be similar to the openshell-provider-<provider> taxonomy, so shouldn't be a problem.

That feels like a lot of machinery. Do we get a lot of benefit to keeping them separate? I would be worried that SDKs would drift and we'd get stuck in a tedious release process across all these repos.

My initial thought is it'd be easier to have our agents keep things in sync from a single monorepo.

I saw this a little different from providers since SDKs are more tightly coupled to core releases vs providers which would entirely be on their own release cadence.

rhuss · 2026-10-14T08:33:15Z

+
+| 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. |


What's about moving the CLI also in an own repo, to ensure that it only access the gateway via the rust SDK ?

Alternatively, if the CLI is using the rust SDK, then the rust SDK should be also part of this repository to avoid circular dependencies across repos (see below my comment on the SDK repos)

Good call. I'd lean towards keeping the rust sdk in the core repo and developing the cli the same.

rhuss · 2026-10-14T08:36:01Z

+| `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. |


I would also add the operator story here as in-scope.

I've got the operator listed under the Kubernetes repo. Did you have something else in mind?

rhuss · 2026-10-14T08:36:59Z

+
+These are the proposed homes and responsibilities:
+
+| Repository | Owns and publishes |


Additional repos that I could see and that address diferent contributor personas:

openshell-docs --> Documentation generation (pulling from other repos) and website generation.

openshell-addons --> useful addons like the policy interceptor or other examples.

openshell-enhancements (or OEPs)?

We already have RFCs, I'd prefer to keep that over OEPs. +1 to openshell-docs.

rhuss · 2026-10-14T08:42:25Z

+| `openshell-sdks` | Go, Python, Rust, and TypeScript SDKs. |
+| `openshell-providers-<provider>` | 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


In othe CNCF projects (like Knative), automation helped quite a bit to keep those permission in sync from a central definition from the main repo.

We used Prow as the build system, the Kubernetes test infrastructure and supported on the CNCF servers, which helped in this (is uses its own DSL with /.. commands). I wonder whether Prow integration is on the table or not, but it would give us some nice support to inspect the build servers, like on https://prow.k8s.io/

I'm definitely in favor of adding some automation.

rhuss · 2026-10-14T08:44:11Z

+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.


We should also ensure to have at least two maintainers per repository and mention this somewhere in this doc.

I'd like to see actual maintainer names as well. I don't think it will be tenable for the current maintainers to be the default maintainers for all repos to start. The maintainer community needs to grow substantially to support this.

rhuss · 2026-10-14T08:57:52Z

+  `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?


I'm happy to drive the work on the golang SDK, and as it tangent to the rest, I think it also makes a good first candidate.

Sounds great!

docs(rfc): propose repository migration for a smaller core

9c7aae4

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs(rfc): add Simon Scatton as repository migration author

12da837

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

SDAChess mentioned this pull request Oct 13, 2026

feat: package OpenShell for Fedora #3510

Open

2 of 37 tasks

politerealism reviewed Oct 13, 2026

View reviewed changes

rhuss reviewed Oct 14, 2026

View reviewed changes

johntmyers mentioned this pull request Oct 14, 2026

OpenShell migration to OpenShell GitHub org (CNCF) #4554

Open

TyceHerrman mentioned this pull request Oct 19, 2026

feat(server): make Kubernetes, AWS STS, and Vault integrations optional #4723

Open

2 of 11 tasks


		These are the proposed homes and responsibilities:

		\| Repository \| Owns and publishes \|

Conversation

drew commented Oct 12, 2026

Summary

Related Issue

Changes

Testing

Checklist

Uh oh!

copy-pr-bot Bot commented Oct 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

drew Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

drew Oct 20, 2026 •

edited

Loading