docs(rfc): add RFC-0011 multi-player support design

[derekwaynecarr]

Summary

This RFC introduces multi-player support for OpenShell by adding workspaces as hard isolation boundaries, expanding the role model to six roles (Platform Admin, Workspace Admin, Auditor, User, Service
Account, Sandbox Supervisor), and introducing workspace-scoped access control. The Kubernetes compute driver gains two workspace mapping modes — managed (default), which creates gateway-scoped Kubernetes
namespaces (openshell-{gateway-id}-{workspace-name}), and operator mode for 1:1 passthrough to pre-existing namespaces. A three-tier policy layering model replaces the current mutual-exclusion approach.
The design preserves backwards compatibility for single-player deployments via a default workspace.

Related Issue

#1977

Changes

• Workspaces as first-class resources and hard isolation boundaries for sandboxes, providers, and policies, with a default workspace for backwards compatibility
• Expanded role model from two-tier (admin/user) to six roles: Platform Admin, Workspace Admin, Auditor, User, Service Account, Sandbox Supervisor
• Workspace-scoped access — all workspace members can access any sandbox in the workspace; credential isolation happens at the workspace boundary
• Ownership tracking via created_by on ObjectMeta for attribution, not access control
• Kubernetes workspace mapping with two modes: managed (default, creates openshell-{gateway-id}-{workspace-name}) and operator (1:1 name passthrough to pre-existing K8s namespaces)
• Cluster-wide list/watch with label filtering replaces single-namespace watcher
• Provider credential scoping to workspaces with no raw credential visibility for non-admin roles
• Three-tier policy layering (gateway default → workspace floor → sandbox policy) replacing mutual-exclusion model; enforcement modes use most-restrictive-wins, allowlists use union across tiers
• Dual role assignment: global roles (Platform Admin, Auditor) from OIDC JWT claims, workspace-scoped roles from gateway-stored membership records
• Multi-provider OIDC authentication, plus API key authentication for service accounts
• Control-plane audit trail via OCSF ApiActivity events on every mutating gRPC call
• Per-workspace quotas for concurrent sandboxes, GPU allocations, and sandbox lifetime
• Enterprise multi-consumer gateway deployment pattern with OpenClaw integration example
• Cross-workspace sandbox sharing deferred to future work

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated (if applicable)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[drew]

Could we rename this to RFC-0011? I'll reserve the number in our tracker 😄.

[drew]

Does the parent service account create "sub" service accounts?

[dhirajsb]

Does each sandbox have to use a unique sercice account or can it be shared, but still maintain a unique agent identity using the pod name in it's SPIFFE id for example?

[dhirajsb]

We are missing a persona in this approach. CMIW, but the user persona as modeled sounds more like an end-user who's directly interacting with an agent in a Sandbox.

OpenShell multi-user architecture should support agentic app development for app developers. It should leverage K8s rbac for access control in app namespaces. It should also decouple policy management through Gateway in such a way that app developers or app workloads (or compromised workloads) can't override certain org/platform wide security policies enforced via Gateway.

I hope that makes sense.

[rhuss]

Great RFC, this fills a real gap.

My comments above are coming from a Kubernetes perspective, specifically looking at how well this proposal maps to the operator discussion in #1719. I'm not suggesting the gateway should copy the Kubernetes multi-tenancy model for Docker, VM, or bare-metal drivers. But for Kubernetes deployments, we should be careful about which existing platform concepts we can reuse (namespaces, RBAC, Secret management, admission control) so that the integration feels native to operators and platform teams already running that ecosystem.

Both proposed Kubernetes modes (managed and operator) map OpenShell namespaces (or "workspaces") to K8s namespaces. The difference is who provisions the namespace (gateway in managed mode, external tooling in operator mode), not the conceptual relationship. In both cases, providers can reference credentials managed by the cluster's secret infrastructure (external-secrets-operator, Vault). The gateway keeps its own workspace model, roles, and credential scoping for non-K8s drivers where none of that exists.

That said, there's an impedance mismatch worth checking. K8s RBAC maps well to control plane operations: who can create/delete OpenShellSandbox CRs (assuming we end up with such an abstraction), who can manage providers and policies in a namespace. But OpenShell also has a data plane authorization concern: who can exec into a running sandbox, stream relay output, share a session, or view audit logs. That's runtime authorization through the gateway's gRPC endpoints, and K8s RBAC has no reach there. The RFC's five-role model is needed for these data plane operations even in Kubernetes deployments. Trying to force runtime access checks into K8s RBAC (like SubjectAccessReview for every gRPC call) would be awkward and break parity with non-K8s drivers.

So in practice, K8s RBAC covers "who can deploy what" (platform admins install the operator, team leads manage CRs in their namespace), while the gateway's auth model from this RFC covers "who can do what at runtime" (exec, relay, session sharing). Both are needed, with clear boundaries.

One thing worth considering on phasing: if the operator (#1719) is being designed in parallel, operator mode (Phase 3) is the simpler starting point for Kubernetes (no ClusterRole for namespace create/delete, no naming conventions, no race conditions). It might make sense to design these together rather than sequentially.

[dhirajsb]

For AI Fatory at NVIDIA, the requirements are as follows:

• One cluster gateway: HA OpenShell control plane in openshell-system, backed by PostgreSQL (core architecture RFC).
• App-local data plane: Sandboxes, PVCs, service accounts and warm pools stay in each application namespace.
• Trusted namespace placement: Gateway derives the target namespace from identity and platform policy—not arbitrary user input (platform integration proposal).
• Warm allocation: App-specific SandboxTemplate + SandboxWarmPool; gateway creates SandboxClaim objects (Agent Sandbox extensions).
• Central governance: Cluster maximum policy → app baseline → sandbox-specific restrictions (managed maximum policies).
• Platform integration: Namespace operator installs RBAC, SCC, NetworkPolicy, quotas, TLS identity and Vault/ESO-backed Secrets.

I believe this proposal covers them all at a high level, but please correct it if anything is missing.

[derekwaynecarr]

@dhirajsb this proposal covers your requested items, but some items would need to be handled post this rfc. I will discuss in more detail in community call, but here is a quick summary.

1. One cluster gateway: HA OpenShell control plane in openshell-system, backed by PostgreSQL

• Covered. The RFC designs for a single gateway per compute region (Enterprise Deployment section, line 426). PostgreSQL backing and HA are existing infrastructure concerns outside this RFC's scope, already covered by RFC 0001.

2. App-local data plane: Sandboxes, PVCs, service accounts and warm pools stay in each application namespace

• Partially covered. The RFC maps workspaces to K8s namespaces (operator mode, line 382-396), so sandboxes land in per-app namespaces. How we address warm pool allocation or template-based sandbox creation is likely a configuration of the workspace, but I would add those settings once we settle on the core segmentation of the OpenShell control plane.

3. Trusted namespace placement: Gateway derives target namespace from identity and platform policy — not arbitrary user input

• Covered. Operator mode (line 382-396) does a 1:1 workspace-to-namespace mapping, but the workspace is currently set by the caller via --workspace flag. The RFC's workspace membership model constrains which workspaces a principal can target.

4. Warm allocation: App-specific SandboxTemplate + SandboxWarmPool; gateway creates SandboxClaim objects

• Not covered. The RFC covers workspace isolation and RBAC but not sandbox lifecycle optimizations like warm pools, which are good things to configure against the workspace after this rfc is accepted.

5. Central governance: Cluster maximum policy → app baseline → sandbox-specific restrictions

• Covered. The three-tier policy layering (lines 259-291) maps directly: tier 1 (gateway default = cluster maximum) → tier 2 (workspace floor = app baseline) → tier 3 (sandbox policy = sandbox-specific).
  The comment links Enterprise permission modes with managed maximum policies #2109 for managed maximum policies, which aligns with tier 1 deny rules and enforcement modes.

6. Platform integration: Namespace operator installs RBAC, SCC, NetworkPolicy, quotas, TLS identity and Vault/ESO-backed Secrets

• Covered. Operator mode (line 382-396) assumes pre-provisioned namespaces, which is the model where an external namespace operator handles RBAC, SCC, NetworkPolicy, and secrets. The RFC describes the OpenShell side of consuming those namespaces.