docs(rfc): add RFC 1977 multi-player support design#1980
Conversation
derekwaynecarr
requested review from
a team,
maxamillion and
mrunalp
as code owners
| - **Phase 1: Namespace and ownership model.** Add `namespace` and `created_by` | ||
| fields to `ObjectMeta` in the proto. Implement namespace-scoped storage and | ||
| filtering in gRPC handlers. Create the `default` namespace for backwards | ||
| compatibility. Sandbox name uniqueness shifts from globally unique to |
There was a problem hiding this comment.
Is it critical to implement this in a backward compatible way right now?
There was a problem hiding this comment.
If we didn't create a default namespace what would be the single-player UX?
There was a problem hiding this comment.
the spirit of the default namespace is that a user never thinks about namespaces at all when using openshell in a single player setup, so the default or some other token is just there to make sure there is no friction in the single player experience by adding multiplayer support.
There was a problem hiding this comment.
We could also (automatically) create a namespace per user account in single player mode. This sets us up to have a single gateway for the workstation while supporting different user accounts on that workstation.
|
|
||
| ### Kubernetes Compute Driver: Namespace Mapping | ||
|
|
||
| OpenShell namespaces are a logical concept. When the Kubernetes compute driver |
There was a problem hiding this comment.
I think it'd be useful to outline what behaviors/patterns we hope to enable and control via namespaces. I found myself inventing reasons that it'd be useful to have namespaces, but I think a list of practical applications would be helpful.
There was a problem hiding this comment.
the simplest example i have is the friction we hit when doing a team-level gateway setup. within a team, its common for users to have their own dedicated API keys to access claude or codex, and these are private to the individual. that friction leads folks towards wanting a gateway per trust/security domain when a common gateway with some credential segmentation would satisfy. this proposal enables that concept. it also would be safe to now share a sandbox (for connect/exec) actions among users in shared coding sessions, etc. since the literal credentials are left outside the sandbox.
There was a problem hiding this comment.
@derekwaynecarr in that scenario, as described Provider Credential Scoping section a namespace admin would have to create and lifecycle manage ever user's credentials in their namespace or would each user have their own namespace and therefore be a namespace admin?
|
|
||
| - What is the identity mapping strategy for multi-provider OIDC? If a user | ||
| authenticates via both corporate SSO and GitHub, how are those identities | ||
| linked to a single internal principal? |
There was a problem hiding this comment.
Should this even be a thing? Intuitively, this feels like 2 principals to me, or at least I'd not be surprised if it were treated that way. Grant me the same permissions twice and or share with myself (my two principals) feels acceptable.
| authenticates via both corporate SSO and GitHub, how are those identities | ||
| linked to a single internal principal? | ||
|
|
||
| - Should per-namespace quota limits be hard (reject sandbox creation) or soft |
There was a problem hiding this comment.
Sounds like a reasonable configuration option (to be implemented at any time)
| also be namespace-scoped from the start, or should they remain global and be | ||
| extended later as the organizational model matures? | ||
|
|
||
| - In operator mode, should the driver validate that the target Kubernetes |
There was a problem hiding this comment.
Fail seems right here. Even if you check, it could go away by the time you try to make it.
| |------|-------------| | ||
| | **Platform Admin** | Manages gateway configuration, auth providers, compute drivers, and quotas. Full visibility across all namespaces. | | ||
| | **Namespace Admin** | Manages users, providers, policies, and quotas within a single namespace. Cannot change gateway infra or access other namespaces. | | ||
| | **Operator** | Read-only view of all sandboxes and audit logs across namespaces for monitoring, incident response, and compliance. Cannot create or modify sandboxes. | |
There was a problem hiding this comment.
I still like the term Auditor for this. Maybe operator means the same in other (kube?) communities?
There was a problem hiding this comment.
i like auditor as well.
| currently does not have a durable store beyond configuration files. | ||
|
|
||
| - Which resources beyond sandboxes are namespace-scoped? Sandboxes are the | ||
| primary namespaced resource. Should settings, policies, and provider configs |
There was a problem hiding this comment.
Earlier in the doc you said this:
Providers belong to a namespace.
Should probably ask the agent to make sure the entire document agrees with itself.
There was a problem hiding this comment.
haha, good catch! will update.
Signed-off-by: Derek Carr <decarr@redhat.com>
derekwaynecarr
force-pushed
the
decarr/multi-player-design
branch
from
3713b9b to
85e9054
Compare
|
Could we rename this to RFC-0011? I'll reserve the number in our tracker 😄. |
| - Gives a clear security boundary (namespace) without over-modeling | ||
| organizational hierarchy. | ||
| - Allows multiple overlapping groupings within a namespace via labels. | ||
| - Reuses Kubernetes-style patterns that users already understand. |
There was a problem hiding this comment.
I'm not necessarily against this, but I think assuming users of AI Agents already understand kubernetes design patterns might be a stretch.
| unique-within-namespace. Existing sandboxes are backfilled into the `default` | ||
| namespace. All existing single-player behavior continues unchanged. | ||
|
|
||
| - **Phase 2: Kubernetes driver — managed mode (default).** The driver creates |
There was a problem hiding this comment.
I was thinking about building out a podman driver version of this too. The scenario I have in mind is where an user/student/homelabber who wants to tinker with their team or learn on their own with minimal setup and admin overhead could spin up a linux VM or cloud instance, install the openshell-gateway rpm, run the openshell gateway service, create an openshell namespace for themselves or each member of their team. This obviously won't scale and is a single point of failure, but could be an interesting means to test it out and provides an easy/simple path to "my agents aren't running on my laptop".
Basically one local linux user openshell, one rootless Podman socket, one gateway process, many OpenShell namespaces, one Podman network per OpenShell namespace, one workspace volume per sandbox, no arbitrary bind mounts, namespace-scoped volumes/providers, gateway-enforced RBAC/quotas, OIDC/API-key auth required, gateway enforced quotas, OCSF attribution, and a strict shared-host driver mode that the user would have to opt into.
Or maybe that's a fools errand and the answer is just to show people how to do this with kind, minikube, k3s, or microshift. Thoughts? 🤔
5 participants
Summary
This RFC introduces multi-player support for OpenShell by adding namespaces as hard isolation boundaries, expanding the role model to five roles (Platform Admin, Namespace Admin, Operator, User, Service
Account), and threading ownership through the sandbox lifecycle. The Kubernetes compute driver gains two namespace mapping modes — managed (default), which creates gateway-scoped Kubernetes namespaces
(openshell-{gateway-id}-{namespace}), and operator mode for 1:1 passthrough to pre-existing namespaces. The design preserves backwards compatibility for single-player support via a
defaultnamespace.Related Issue
#1977
Changes
Namespaces as first-class hard isolation boundaries for sandboxes, providers, and policies, with a default namespace for backwards compatibility
Testing
mise run pre-commitpassesChecklist