docs(kubernetes): document managed workspaces setup

docs/how-it-works/workspaces.mdx

@@ -17,6 +17,9 @@ The CLI targets the `default` workspace unless you set `--workspace` or
 `OPENSHELL_WORKSPACE`. The logical OpenShell workspace described here is
 separate from the `/sandbox` filesystem directory inside a sandbox.
 
+For Kubernetes namespace mapping and managed per-workspace namespaces, see
+[Workspace on Kubernetes](/kubernetes/workspaces).
+
 ## Understand the Role Model
 
 OpenShell combines an identity-provider role with a membership record for each

docs/kubernetes/setup.mdx

@@ -118,6 +118,10 @@ helm upgrade --install openshell \
 
 The chart automatically generates PKI secrets on first install using pre-install Helm hooks. No manual secret creation is required.
 
+The default Kubernetes driver puts all workspaces in one sandbox namespace. To
+have the gateway create a namespace for each workspace, follow
+[Workspace on Kubernetes](/kubernetes/workspaces).
+
 ### Split gateway and workspace releases
 
 For a platform-managed namespace, install the gateway without namespace-scoped

docs/kubernetes/workspaces.mdx

@@ -0,0 +1,141 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+title: "Workspace on Kubernetes"
+sidebar-title: "Workspaces"
+description: "Configure how OpenShell workspaces map to Kubernetes namespaces, including managed per-workspace namespaces."
+keywords: "Kubernetes, Workspaces, Namespaces, Managed Mode, Helm, RBAC"
+position: 2
+---
+
+The Kubernetes compute driver maps each OpenShell workspace to a Kubernetes
+namespace. Choose the mapping when you configure the gateway. OpenShell
+workspace membership and roles are separate from Kubernetes namespace access;
+see [Workspaces](/how-it-works/workspaces) to create workspaces and assign members.
+
+| Mode | Namespace mapping | Namespace owner |
+|---|---|---|
+| `shared` (default) | All workspaces use one sandbox namespace. | The platform operator. |
+| `managed` | Each workspace uses `openshell-{gateway_id}-{workspace}`. | The OpenShell Kubernetes driver. |
+| `operator` | Each workspace maps to a pre-provisioned namespace on an operator allowlist. | The platform operator. |
+
+[RFC 0011](https://github.com/NVIDIA/OpenShell/tree/main/rfc/0011-multi-player-design#kubernetes-compute-driver-workspace-mapping)
+explains the workspace-to-namespace design. The table above reflects the current
+driver modes and default.
+
+## Configure Managed Workspaces
+
+Use managed mode when the gateway should create and delete a Kubernetes
+namespace for each OpenShell workspace. Start with a working
+[Kubernetes installation](/kubernetes/setup): the Agent Sandbox controller and
+CRDs must be installed, and the cluster CNI must enforce ingress and egress
+`NetworkPolicy` in every sandbox namespace.
+
+Set the Kubernetes driver mode in the Helm values file:
+
+```yaml
+gatewayConfig:
+  openshell.drivers.kubernetes:
+    workspace_mode: managed
+```
+
+Install or upgrade the gateway with those values:
+
+```shell
+helm upgrade --install openshell \
+  oci://ghcr.io/nvidia/openshell/helm-chart \
+  --version <version> \
+  --namespace openshell \
+  -f my-values.yaml
+```
+
+Keep the chart-managed cluster RBAC enabled, or have a cluster administrator
+apply the rendered `ClusterRole` and `ClusterRoleBinding` before installing as
+a namespace administrator. Managed mode needs cluster-scoped permissions to
+create and delete namespaces and to manage sandbox resources in them. See
+[Installing without cluster-admin](/kubernetes/setup#installing-without-cluster-admin)
+for the separate RBAC procedure. The driver creates the sandbox
+`ServiceAccount` in each managed namespace; do not install the
+`openshell-workspace` chart there.
+
+<Note>
+If this gateway already runs sandboxes in `shared` mode, plan their removal or
+migration before changing `workspace_mode`. The new mode maps workspaces to
+different Kubernetes namespaces; it does not move existing sandbox resources.
+</Note>
+
+The chart uses its fullname as the default `gateway_id`. With the default
+fullname `openshell`, workspace `team-ml` uses namespace
+`openshell-openshell-team-ml`. Keep the gateway ID stable after creating
+workspaces because it is part of their namespace names. The gateway ID and
+resulting namespace name must satisfy the Kubernetes DNS-1123 label limit of
+63 characters. See the [gateway configuration reference](/how-it-works/gateways/configuration#kubernetes)
+for the driver fields.
+
+## Create and Verify a Workspace
+
+A Platform Admin creates the OpenShell workspace. Creating the workspace record
+alone does not create its Kubernetes namespace. The driver creates the namespace
+and sandbox `ServiceAccount` when an operation first needs them, such as
+provisioning a sandbox:
+
+```shell
+openshell workspace create --name team-ml
+openshell sandbox create --workspace team-ml
+```
+
+In an OIDC deployment, assign a Workspace Admin or Workspace User membership
+before that person uses the workspace. See
+[Create a Workspace and Add Members](/how-it-works/workspaces#create-a-workspace-and-add-members).
+
+Check the namespace after the sandbox is provisioned:
+
+```shell
+kubectl get namespace openshell-openshell-team-ml
+kubectl -n openshell-openshell-team-ml get serviceaccount openshell-sandbox
+```
+
+Replace the namespace name if you use another chart fullname or gateway ID.
+The gateway labels managed namespaces with `openshell.ai/managed-by=openshell`,
+`openshell.ai/gateway-id`, and `openshell.ai/sandbox-workspace`.
+
+### Pull Images from a Private Registry
+
+If the sandbox images require an image-pull Secret, create that Secret in the
+configured source namespace (`server.sandboxNamespace`, which defaults to the
+Helm release namespace) and list its name in the gateway values:
+
+```yaml
+gatewayConfig:
+  openshell.drivers.kubernetes:
+    workspace_mode: managed
+    image_pull_secrets: [regcred]
+```
+
+The driver copies each configured Secret into a managed workspace namespace
+for each sandbox runtime generation. It removes the copy with that generation.
+See the [Kubernetes driver configuration](/how-it-works/gateways/configuration#kubernetes)
+for other image settings.
+
+## Remove a Managed Workspace
+
+Delete the workspace through OpenShell after removing its sandboxes and other
+workspace resources:
+
+```shell
+openshell workspace delete team-ml
+```
+
+The gateway asks the Kubernetes driver to delete the managed namespace during
+workspace deletion. Do not delete the namespace directly while the OpenShell
+workspace still exists. See [Delete a Workspace](/how-it-works/workspaces#delete-a-workspace)
+for the full list of resources that must be removed first.
+
+## Use Operator-Managed Namespaces
+
+If your platform provisions workspace namespaces, use `operator` mode instead.
+Configure either `operator_namespace_label` or `operator_namespace_file` in
+`gatewayConfig.openshell.drivers.kubernetes`, then install the
+`openshell-workspace` chart in each allowlisted namespace. The gateway does not
+create or delete those namespaces. See
+[Split gateway and workspace releases](/kubernetes/setup#split-gateway-and-workspace-releases).