From 025c11b8249276b870f110b6b8becdd00b205ede Mon Sep 17 00:00:00 2001
From: Dhiraj Bokde <dbokde@nvidia.com>
Date: Sun, 26 Jul 2026 20:59:22 -0700
Subject: [PATCH 1/4] feat(helm): split gateway and workspace charts

Signed-off-by: Dhiraj Bokde <dbokde@nvidia.com>
---
 .../skills/debug-openshell-cluster/SKILL.md   | 20 ++++++
 .github/actions/release-helm-oci/action.yml   | 63 ++++++++++++-------
 architecture/compute-runtimes.md              | 11 ++++
 deploy/helm/openshell-workspace/Chart.yaml    |  9 +++
 deploy/helm/openshell-workspace/README.md     | 47 ++++++++++++++
 .../helm/openshell-workspace/README.md.gotmpl | 33 ++++++++++
 .../templates/_helpers.tpl                    | 44 +++++++++++++
 .../templates/networkpolicy.yaml              | 30 +++++++++
 .../openshell-workspace/templates/role.yaml   | 39 ++++++++++++
 .../templates/rolebinding.yaml                | 19 ++++++
 .../templates/serviceaccount.yaml             | 17 +++++
 .../tests/workspace_test.yaml                 | 61 ++++++++++++++++++
 deploy/helm/openshell-workspace/values.yaml   | 31 +++++++++
 deploy/helm/openshell/README.md               |  9 +++
 deploy/helm/openshell/README.md.gotmpl        |  8 +++
 .../openshell/templates/networkpolicy.yaml    |  2 +-
 deploy/helm/openshell/templates/role.yaml     |  2 +-
 .../helm/openshell/templates/rolebinding.yaml |  2 +-
 .../openshell/templates/serviceaccount.yaml   |  4 +-
 .../tests/sandbox_namespace_test.yaml         | 18 ++++++
 .../tests/sandbox_service_account_test.yaml   | 10 +++
 deploy/helm/openshell/values.yaml             |  8 +++
 deploy/helm/test-split-ownership.sh           | 38 +++++++++++
 docs/kubernetes/setup.mdx                     | 31 +++++++++
 tasks/helm.toml                               | 29 ++++++---
 25 files changed, 550 insertions(+), 35 deletions(-)
 create mode 100644 deploy/helm/openshell-workspace/Chart.yaml
 create mode 100644 deploy/helm/openshell-workspace/README.md
 create mode 100644 deploy/helm/openshell-workspace/README.md.gotmpl
 create mode 100644 deploy/helm/openshell-workspace/templates/_helpers.tpl
 create mode 100644 deploy/helm/openshell-workspace/templates/networkpolicy.yaml
 create mode 100644 deploy/helm/openshell-workspace/templates/role.yaml
 create mode 100644 deploy/helm/openshell-workspace/templates/rolebinding.yaml
 create mode 100644 deploy/helm/openshell-workspace/templates/serviceaccount.yaml
 create mode 100644 deploy/helm/openshell-workspace/tests/workspace_test.yaml
 create mode 100644 deploy/helm/openshell-workspace/values.yaml
 create mode 100755 deploy/helm/test-split-ownership.sh

diff --git a/.agents/skills/debug-openshell-cluster/SKILL.md b/.agents/skills/debug-openshell-cluster/SKILL.md
index 90b9a38409..0eb013b23b 100644
--- a/.agents/skills/debug-openshell-cluster/SKILL.md
+++ b/.agents/skills/debug-openshell-cluster/SKILL.md
@@ -464,6 +464,26 @@ helm -n openshell get values openshell | grep sandboxNamespace
 
 Then inspect sandbox resources in that namespace.
 
+For a split release, the gateway values should have
+`workspaceResources.enabled=false`, and the target namespace should contain a
+separate `openshell-workspace` release:
+
+```bash
+helm -n openshell get values openshell | grep -A2 workspaceResources
+helm -n <sandbox-namespace> status openshell-workspace
+kubectl -n <sandbox-namespace> get serviceaccount,role,rolebinding,networkpolicy \
+  -l app.kubernetes.io/instance=openshell-workspace
+kubectl auth can-i create sandboxes.agents.x-k8s.io \
+  --namespace <sandbox-namespace> \
+  --as system:serviceaccount:openshell:openshell
+```
+
+If the gateway cannot create or watch sandboxes, verify the workspace
+RoleBinding subject matches the gateway ServiceAccount name and namespace.
+If SSH relay connections fail, verify the workspace NetworkPolicy selects the
+gateway's actual `app.kubernetes.io/name` and
+`app.kubernetes.io/instance` labels.
+
 Check the configured sandbox service account when TokenReview bootstrap or
 sandbox registration fails. Helm creates a dedicated sandbox service account by
 default and writes it to `[openshell.drivers.kubernetes].service_account_name`;
diff --git a/.github/actions/release-helm-oci/action.yml b/.github/actions/release-helm-oci/action.yml
index d20691ad0f..46649e0cb0 100644
--- a/.github/actions/release-helm-oci/action.yml
+++ b/.github/actions/release-helm-oci/action.yml
@@ -4,7 +4,7 @@
 name: Release Helm OCI
 description: >
   Patch chart version/appVersion, refuse duplicate OCI versions on public
-  releases, package the chart, and push to GHCR OCI.
+  releases, package the gateway and workspace charts, and push them to GHCR OCI.
 
 inputs:
   chart-version:
@@ -51,11 +51,16 @@ runs:
       shell: bash
       run: |
         set -euo pipefail
-        CHART_DIR="${RUNNER_TEMP}/chart-build"
-        cp -a deploy/helm/openshell/. "${CHART_DIR}"
-        sed -i "s/^version:.*/version: ${CHART_VERSION}/" "${CHART_DIR}/Chart.yaml"
-        sed -i "s/^appVersion:.*/appVersion: \"${APP_VERSION}\"/" "${CHART_DIR}/Chart.yaml"
-        echo "chart_dir=${CHART_DIR}" >> "$GITHUB_OUTPUT"
+        GATEWAY_CHART_DIR="${RUNNER_TEMP}/gateway-chart-build"
+        WORKSPACE_CHART_DIR="${RUNNER_TEMP}/workspace-chart-build"
+        cp -a deploy/helm/openshell/. "${GATEWAY_CHART_DIR}"
+        cp -a deploy/helm/openshell-workspace/. "${WORKSPACE_CHART_DIR}"
+        for chart_dir in "${GATEWAY_CHART_DIR}" "${WORKSPACE_CHART_DIR}"; do
+          sed -i "s/^version:.*/version: ${CHART_VERSION}/" "${chart_dir}/Chart.yaml"
+          sed -i "s/^appVersion:.*/appVersion: \"${APP_VERSION}\"/" "${chart_dir}/Chart.yaml"
+        done
+        echo "gateway_chart_dir=${GATEWAY_CHART_DIR}" >> "$GITHUB_OUTPUT"
+        echo "workspace_chart_dir=${WORKSPACE_CHART_DIR}" >> "$GITHUB_OUTPUT"
         echo "chart_version=${CHART_VERSION}" >> "$GITHUB_OUTPUT"
 
     - name: Refuse duplicate chart version
@@ -65,38 +70,52 @@ runs:
       shell: bash
       run: |
         set -euo pipefail
-        OCI_CHART="oci://ghcr.io/nvidia/openshell/helm-chart"
-        if helm show chart "${OCI_CHART}" --version "${CHART_VERSION}" >/dev/null 2>&1; then
-          echo "::error::Chart ${CHART_VERSION} is already published. Use a new tag or delete the existing package first."
-          exit 1
-        fi
+        for chart in helm-chart openshell-workspace; do
+          OCI_CHART="oci://ghcr.io/nvidia/openshell/${chart}"
+          if helm show chart "${OCI_CHART}" --version "${CHART_VERSION}" >/dev/null 2>&1; then
+            echo "::error::Chart ${chart}:${CHART_VERSION} is already published. Use a new tag or delete the existing package first."
+            exit 1
+          fi
+        done
 
     - name: Package Helm chart
       env:
-        CHART_DIR: ${{ steps.prep.outputs.chart_dir }}
+        GATEWAY_CHART_DIR: ${{ steps.prep.outputs.gateway_chart_dir }}
+        WORKSPACE_CHART_DIR: ${{ steps.prep.outputs.workspace_chart_dir }}
       shell: bash
       run: |
         set -euo pipefail
-        helm package "${CHART_DIR}" --destination /tmp
-        ls /tmp/helm-chart-*.tgz
+        mkdir -p /tmp/helm-charts
+        helm package "${GATEWAY_CHART_DIR}" --destination /tmp/helm-charts
+        helm package "${WORKSPACE_CHART_DIR}" --destination /tmp/helm-charts
+        ls /tmp/helm-charts/*.tgz
 
     - name: Push Helm chart to GHCR OCI
       shell: bash
       run: |
         set -euo pipefail
-        helm push /tmp/helm-chart-*.tgz oci://ghcr.io/nvidia/openshell
+        for archive in /tmp/helm-charts/*.tgz; do
+          helm push "${archive}" oci://ghcr.io/nvidia/openshell
+        done
 
     - name: Push SHA-pinned chart
       if: inputs.pin-sha != ''
       env:
         PIN_SHA: ${{ inputs.pin-sha }}
-        CHART_DIR: ${{ steps.prep.outputs.chart_dir }}
+        GATEWAY_CHART_DIR: ${{ steps.prep.outputs.gateway_chart_dir }}
+        WORKSPACE_CHART_DIR: ${{ steps.prep.outputs.workspace_chart_dir }}
       shell: bash
       run: |
         set -euo pipefail
-        SHA_CHART_DIR="${RUNNER_TEMP}/chart-build-sha"
-        cp -a "${CHART_DIR}/." "${SHA_CHART_DIR}"
-        sed -i "s/^version:.*/version: 0.0.0-dev.${PIN_SHA}/" "${SHA_CHART_DIR}/Chart.yaml"
-        sed -i "s/^appVersion:.*/appVersion: \"${PIN_SHA}\"/" "${SHA_CHART_DIR}/Chart.yaml"
-        helm package "${SHA_CHART_DIR}" --destination /tmp/sha-pin
-        helm push /tmp/sha-pin/helm-chart-*.tgz oci://ghcr.io/nvidia/openshell
+        mkdir -p /tmp/sha-pin
+        for source_dir in "${GATEWAY_CHART_DIR}" "${WORKSPACE_CHART_DIR}"; do
+          chart_name="$(basename "${source_dir}")"
+          sha_chart_dir="${RUNNER_TEMP}/${chart_name}-sha"
+          cp -a "${source_dir}/." "${sha_chart_dir}"
+          sed -i "s/^version:.*/version: 0.0.0-dev.${PIN_SHA}/" "${sha_chart_dir}/Chart.yaml"
+          sed -i "s/^appVersion:.*/appVersion: \"${PIN_SHA}\"/" "${sha_chart_dir}/Chart.yaml"
+          helm package "${sha_chart_dir}" --destination /tmp/sha-pin
+        done
+        for archive in /tmp/sha-pin/*.tgz; do
+          helm push "${archive}" oci://ghcr.io/nvidia/openshell
+        done
diff --git a/architecture/compute-runtimes.md b/architecture/compute-runtimes.md
index 2a36073486..e56d03ffba 100644
--- a/architecture/compute-runtimes.md
+++ b/architecture/compute-runtimes.md
@@ -238,6 +238,17 @@ through the driver configuration. The Helm chart defaults sandbox agents to
 `Unconfined` so runtime/default AppArmor profiles do not block supervisor
 network namespace setup on AppArmor-enabled nodes.
 
+The Kubernetes deployment packaging has two ownership boundaries. The gateway
+chart owns the gateway workload, configuration, Services, PKI, and
+cluster-scoped gateway resources. It can retain the legacy combined behavior,
+or omit workspace resources. The workspace chart is installed into a
+pre-provisioned sandbox namespace and owns only the sandbox ServiceAccount,
+namespaced RBAC, and sandbox ingress NetworkPolicy. Its RoleBinding names the
+gateway ServiceAccount and namespace explicitly, so the two releases have
+disjoint lifecycle ownership. A shared-mode gateway can target one external
+namespace, while operator mode maps workspace names to multiple
+platform-provisioned namespaces.
+
 Resource requirements enter the driver layer through `SandboxSpec.resource_requirements`. This includes a set of GPU requirements, where a user
 can request a specific number of GPUs or the driver-specific default behaviour.
 For all in-tree drivers, this is equivalent to selecting a single GPU.
diff --git a/deploy/helm/openshell-workspace/Chart.yaml b/deploy/helm/openshell-workspace/Chart.yaml
new file mode 100644
index 0000000000..03a3919d46
--- /dev/null
+++ b/deploy/helm/openshell-workspace/Chart.yaml
@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+apiVersion: v2
+name: openshell-workspace
+description: Namespace-scoped prerequisites for OpenShell Kubernetes sandboxes
+type: application
+version: 0.0.0
+appVersion: "0.0.0"
diff --git a/deploy/helm/openshell-workspace/README.md b/deploy/helm/openshell-workspace/README.md
new file mode 100644
index 0000000000..96ae4ca6e4
--- /dev/null
+++ b/deploy/helm/openshell-workspace/README.md
@@ -0,0 +1,47 @@
+# OpenShell Workspace Helm Chart
+
+<!--
+This file is generated by helm-docs.
+Edit README.md.gotmpl and values.yaml, then run `mise run helm:docs`.
+-->
+
+> **Experimental** - the shared-gateway, multi-namespace deployment path is
+> under active design.
+
+This chart installs the namespace-scoped ServiceAccount, RBAC, and NetworkPolicy
+needed for OpenShell Kubernetes sandboxes. Install it once in every
+platform-managed workspace namespace. It does not create a namespace or deploy
+an OpenShell gateway.
+
+Install the gateway chart with `workspaceResources.enabled=false`, then install
+this chart with the gateway ServiceAccount identity. Configure the gateway's
+Kubernetes driver in `operator` workspace mode when it serves more than one
+pre-provisioned workspace namespace:
+
+```shell
+helm install openshell-workspace ./deploy/helm/openshell-workspace \
+  --namespace app-a \
+  --set gateway.serviceAccount.name=openshell \
+  --set gateway.serviceAccount.namespace=openshell
+```
+
+Keep `sandboxServiceAccount.name` aligned with the gateway chart's
+`sandboxServiceAccount.name`. The defaults for both charts are
+`openshell-sandbox`.
+
+## Values
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| fullnameOverride | string | `""` | Override the full generated resource name. |
+| gateway.networkPolicy.podSelector | object | `{"app.kubernetes.io/instance":"openshell","app.kubernetes.io/name":"openshell"}` | Labels selecting gateway pods allowed to reach sandbox SSH. |
+| gateway.serviceAccount.name | string | `"openshell"` | Name of the shared gateway ServiceAccount. |
+| gateway.serviceAccount.namespace | string | `"openshell"` | Namespace containing the shared gateway ServiceAccount. |
+| nameOverride | string | `""` | Override the chart name used in generated resource names. |
+| networkPolicy.enabled | bool | `true` | Restrict sandbox SSH ingress to the shared gateway pods. |
+| sandboxServiceAccount.annotations | object | `{}` | Annotations added to the generated sandbox ServiceAccount. |
+| sandboxServiceAccount.create | bool | `true` | Create the ServiceAccount assigned to sandbox pods. |
+| sandboxServiceAccount.name | string | `"openshell-sandbox"` | Sandbox ServiceAccount name. |
+
+----------------------------------------------
+Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2)
diff --git a/deploy/helm/openshell-workspace/README.md.gotmpl b/deploy/helm/openshell-workspace/README.md.gotmpl
new file mode 100644
index 0000000000..a233eef165
--- /dev/null
+++ b/deploy/helm/openshell-workspace/README.md.gotmpl
@@ -0,0 +1,33 @@
+# OpenShell Workspace Helm Chart
+
+<!--
+This file is generated by helm-docs.
+Edit README.md.gotmpl and values.yaml, then run `mise run helm:docs`.
+-->
+
+> **Experimental** - the shared-gateway, multi-namespace deployment path is
+> under active design.
+
+This chart installs the namespace-scoped ServiceAccount, RBAC, and NetworkPolicy
+needed for OpenShell Kubernetes sandboxes. Install it once in every
+platform-managed workspace namespace. It does not create a namespace or deploy
+an OpenShell gateway.
+
+Install the gateway chart with `workspaceResources.enabled=false`, then install
+this chart with the gateway ServiceAccount identity. Configure the gateway's
+Kubernetes driver in `operator` workspace mode when it serves more than one
+pre-provisioned workspace namespace:
+
+```shell
+helm install openshell-workspace ./deploy/helm/openshell-workspace \
+  --namespace app-a \
+  --set gateway.serviceAccount.name=openshell \
+  --set gateway.serviceAccount.namespace=openshell
+```
+
+Keep `sandboxServiceAccount.name` aligned with the gateway chart's
+`sandboxServiceAccount.name`. The defaults for both charts are
+`openshell-sandbox`.
+
+{{ template "chart.valuesSection" . }}
+{{ template "helm-docs.versionFooter" . }}
diff --git a/deploy/helm/openshell-workspace/templates/_helpers.tpl b/deploy/helm/openshell-workspace/templates/_helpers.tpl
new file mode 100644
index 0000000000..8eaaaab2b7
--- /dev/null
+++ b/deploy/helm/openshell-workspace/templates/_helpers.tpl
@@ -0,0 +1,44 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "openshell-workspace.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+*/}}
+{{- define "openshell-workspace.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Common labels.
+*/}}
+{{- define "openshell-workspace.labels" -}}
+helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+app.kubernetes.io/name: {{ include "openshell-workspace.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Validate required cross-namespace gateway identity values.
+*/}}
+{{- define "openshell-workspace.validateValues" -}}
+{{- required "gateway.serviceAccount.name is required" .Values.gateway.serviceAccount.name -}}
+{{- required "gateway.serviceAccount.namespace is required" .Values.gateway.serviceAccount.namespace -}}
+{{- required "sandboxServiceAccount.name is required" .Values.sandboxServiceAccount.name -}}
+{{- end }}
diff --git a/deploy/helm/openshell-workspace/templates/networkpolicy.yaml b/deploy/helm/openshell-workspace/templates/networkpolicy.yaml
new file mode 100644
index 0000000000..4a5e2c2293
--- /dev/null
+++ b/deploy/helm/openshell-workspace/templates/networkpolicy.yaml
@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+{{- include "openshell-workspace.validateValues" . -}}
+{{- if .Values.networkPolicy.enabled }}
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: {{ include "openshell-workspace.fullname" . }}-sandbox-ssh
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "openshell-workspace.labels" . | nindent 4 }}
+spec:
+  podSelector:
+    matchLabels:
+      openshell.ai/managed-by: openshell
+  policyTypes:
+    - Ingress
+  ingress:
+    - from:
+        - namespaceSelector:
+            matchLabels:
+              kubernetes.io/metadata.name: {{ .Values.gateway.serviceAccount.namespace }}
+          podSelector:
+            matchLabels:
+              {{- toYaml .Values.gateway.networkPolicy.podSelector | nindent 14 }}
+      ports:
+        - protocol: TCP
+          port: 2222
+{{- end }}
diff --git a/deploy/helm/openshell-workspace/templates/role.yaml b/deploy/helm/openshell-workspace/templates/role.yaml
new file mode 100644
index 0000000000..e0d6d9624e
--- /dev/null
+++ b/deploy/helm/openshell-workspace/templates/role.yaml
@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+{{- include "openshell-workspace.validateValues" . -}}
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: {{ include "openshell-workspace.fullname" . }}-sandbox
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "openshell-workspace.labels" . | nindent 4 }}
+rules:
+  - apiGroups:
+      - agents.x-k8s.io
+    resources:
+      - sandboxes
+      - sandboxes/status
+    verbs:
+      - create
+      - delete
+      - get
+      - list
+      - patch
+      - update
+      - watch
+  - apiGroups:
+      - ""
+    resources:
+      - events
+    verbs:
+      - get
+      - list
+      - watch
+  - apiGroups:
+      - ""
+    resources:
+      - pods
+    verbs:
+      - get
diff --git a/deploy/helm/openshell-workspace/templates/rolebinding.yaml b/deploy/helm/openshell-workspace/templates/rolebinding.yaml
new file mode 100644
index 0000000000..6b71d1f25b
--- /dev/null
+++ b/deploy/helm/openshell-workspace/templates/rolebinding.yaml
@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+{{- include "openshell-workspace.validateValues" . -}}
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: {{ include "openshell-workspace.fullname" . }}-sandbox
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "openshell-workspace.labels" . | nindent 4 }}
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: {{ include "openshell-workspace.fullname" . }}-sandbox
+subjects:
+  - kind: ServiceAccount
+    name: {{ .Values.gateway.serviceAccount.name }}
+    namespace: {{ .Values.gateway.serviceAccount.namespace }}
diff --git a/deploy/helm/openshell-workspace/templates/serviceaccount.yaml b/deploy/helm/openshell-workspace/templates/serviceaccount.yaml
new file mode 100644
index 0000000000..f30663caa4
--- /dev/null
+++ b/deploy/helm/openshell-workspace/templates/serviceaccount.yaml
@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+{{- include "openshell-workspace.validateValues" . -}}
+{{- if .Values.sandboxServiceAccount.create }}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ .Values.sandboxServiceAccount.name }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "openshell-workspace.labels" . | nindent 4 }}
+  {{- with .Values.sandboxServiceAccount.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+{{- end }}
diff --git a/deploy/helm/openshell-workspace/tests/workspace_test.yaml b/deploy/helm/openshell-workspace/tests/workspace_test.yaml
new file mode 100644
index 0000000000..2f71920eaf
--- /dev/null
+++ b/deploy/helm/openshell-workspace/tests/workspace_test.yaml
@@ -0,0 +1,61 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+suite: workspace namespace resources
+templates:
+  - templates/serviceaccount.yaml
+  - templates/role.yaml
+  - templates/rolebinding.yaml
+  - templates/networkpolicy.yaml
+release:
+  name: tenant-a
+  namespace: app-a
+
+tests:
+  - it: creates the workspace role in the release namespace
+    template: templates/role.yaml
+    asserts:
+      - hasDocuments:
+          count: 1
+      - equal:
+          path: metadata.namespace
+          value: app-a
+
+  - it: binds the shared gateway service account
+    template: templates/rolebinding.yaml
+    set:
+      gateway.serviceAccount.name: shared-gateway
+      gateway.serviceAccount.namespace: openshell-system
+    asserts:
+      - equal:
+          path: metadata.namespace
+          value: app-a
+      - equal:
+          path: subjects[0].name
+          value: shared-gateway
+      - equal:
+          path: subjects[0].namespace
+          value: openshell-system
+
+  - it: selects gateway pods in the gateway namespace
+    template: templates/networkpolicy.yaml
+    set:
+      gateway.serviceAccount.namespace: openshell-system
+      gateway.networkPolicy.podSelector:
+        app.kubernetes.io/name: openshell
+        app.kubernetes.io/instance: central
+    asserts:
+      - equal:
+          path: spec.ingress[0].from[0].namespaceSelector.matchLabels["kubernetes.io/metadata.name"]
+          value: openshell-system
+      - equal:
+          path: spec.ingress[0].from[0].podSelector.matchLabels["app.kubernetes.io/instance"]
+          value: central
+
+  - it: supports a pre-existing sandbox service account
+    template: templates/serviceaccount.yaml
+    set:
+      sandboxServiceAccount.create: false
+    asserts:
+      - hasDocuments:
+          count: 0
diff --git a/deploy/helm/openshell-workspace/values.yaml b/deploy/helm/openshell-workspace/values.yaml
new file mode 100644
index 0000000000..2c52b0460d
--- /dev/null
+++ b/deploy/helm/openshell-workspace/values.yaml
@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# -- Override the chart name used in generated resource names.
+nameOverride: ""
+# -- Override the full generated resource name.
+fullnameOverride: ""
+
+gateway:
+  serviceAccount:
+    # -- Name of the shared gateway ServiceAccount.
+    name: openshell
+    # -- Namespace containing the shared gateway ServiceAccount.
+    namespace: openshell
+  networkPolicy:
+    # -- Labels selecting gateway pods allowed to reach sandbox SSH.
+    podSelector:
+      app.kubernetes.io/name: openshell
+      app.kubernetes.io/instance: openshell
+
+sandboxServiceAccount:
+  # -- Create the ServiceAccount assigned to sandbox pods.
+  create: true
+  # -- Sandbox ServiceAccount name.
+  name: openshell-sandbox
+  # -- Annotations added to the generated sandbox ServiceAccount.
+  annotations: {}
+
+networkPolicy:
+  # -- Restrict sandbox SSH ingress to the shared gateway pods.
+  enabled: true
diff --git a/deploy/helm/openshell/README.md b/deploy/helm/openshell/README.md
index 1786a46f63..68dabf6b81 100644
--- a/deploy/helm/openshell/README.md
+++ b/deploy/helm/openshell/README.md
@@ -9,6 +9,14 @@ Edit README.md.gotmpl and values.yaml, then run `mise run helm:docs`.
 
 This chart deploys the OpenShell gateway into a Kubernetes cluster. It is published as an OCI artifact to GHCR at `oci://ghcr.io/nvidia/openshell/helm-chart`.
 
+By default, this chart also creates the namespace-scoped resources needed by
+sandboxes. For a shared-gateway deployment, install it with
+`workspaceResources.enabled=false`, then install the
+`deploy/helm/openshell-workspace` chart in every pre-provisioned workspace
+namespace. The gateway and workspace releases can then be upgraded and removed
+independently. Use Kubernetes `operator` workspace mode when one gateway serves
+multiple pre-provisioned workspace namespaces.
+
 ## Prerequisites
 
 The Kubernetes Agent Sandbox CRDs and controller must be installed on the cluster before deploying OpenShell. Install them with:
@@ -306,6 +314,7 @@ discovery endpoint or its TLS CA.
 | upstreamProxy.url | string | `""` | HTTP proxy URL in http://host:port form. HTTPS-to-proxy is not supported. |
 | workload.allowMultiReplicaStatefulSet | bool | `false` | Allow replicaCount > 1 while rendering a StatefulSet. Prefer workload.kind=deployment for external database-backed multi-replica gateways; this override exists for operators who explicitly require StatefulSet identity or storage semantics. |
 | workload.kind | string | `"statefulset"` | Gateway workload controller kind. Use `statefulset` for the default SQLite database, or `deployment` when server.externalDbSecret points at an external database. |
+| workspaceResources.enabled | bool | `true` | Create the sandbox ServiceAccount, Role, RoleBinding, and NetworkPolicy from this chart. Disable for a gateway-only release. |
 
 ----------------------------------------------
 Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2)
diff --git a/deploy/helm/openshell/README.md.gotmpl b/deploy/helm/openshell/README.md.gotmpl
index 73ebb39c88..cf8677741e 100644
--- a/deploy/helm/openshell/README.md.gotmpl
+++ b/deploy/helm/openshell/README.md.gotmpl
@@ -9,6 +9,14 @@ Edit README.md.gotmpl and values.yaml, then run `mise run helm:docs`.
 
 This chart deploys the OpenShell gateway into a Kubernetes cluster. It is published as an OCI artifact to GHCR at `oci://ghcr.io/nvidia/openshell/helm-chart`.
 
+By default, this chart also creates the namespace-scoped resources needed by
+sandboxes. For a shared-gateway deployment, install it with
+`workspaceResources.enabled=false`, then install the
+`deploy/helm/openshell-workspace` chart in every pre-provisioned workspace
+namespace. The gateway and workspace releases can then be upgraded and removed
+independently. Use Kubernetes `operator` workspace mode when one gateway serves
+multiple pre-provisioned workspace namespaces.
+
 ## Prerequisites
 
 The Kubernetes Agent Sandbox CRDs and controller must be installed on the cluster before deploying OpenShell. Install them with:
diff --git a/deploy/helm/openshell/templates/networkpolicy.yaml b/deploy/helm/openshell/templates/networkpolicy.yaml
index e85571e5f5..fb72604e60 100644
--- a/deploy/helm/openshell/templates/networkpolicy.yaml
+++ b/deploy/helm/openshell/templates/networkpolicy.yaml
@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-{{- if .Values.networkPolicy.enabled }}
+{{- if and .Values.workspaceResources.enabled .Values.networkPolicy.enabled }}
 # NetworkPolicy restricting SSH ingress on sandbox pods to the gateway pod.
 # Sandbox pods are dynamically created by the server and labelled with
 # openshell.ai/managed-by=openshell. This policy ensures only the gateway
diff --git a/deploy/helm/openshell/templates/role.yaml b/deploy/helm/openshell/templates/role.yaml
index af80989072..74d5728350 100644
--- a/deploy/helm/openshell/templates/role.yaml
+++ b/deploy/helm/openshell/templates/role.yaml
@@ -1,5 +1,5 @@
 {{- $workspaceMode := .Values.server.drivers.kubernetes.workspaceMode | default "shared" -}}
-{{- if eq $workspaceMode "shared" }}
+{{- if and (eq $workspaceMode "shared") .Values.workspaceResources.enabled }}
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 apiVersion: rbac.authorization.k8s.io/v1
diff --git a/deploy/helm/openshell/templates/rolebinding.yaml b/deploy/helm/openshell/templates/rolebinding.yaml
index 381473a58b..33add0ad15 100644
--- a/deploy/helm/openshell/templates/rolebinding.yaml
+++ b/deploy/helm/openshell/templates/rolebinding.yaml
@@ -1,5 +1,5 @@
 {{- $workspaceMode := .Values.server.drivers.kubernetes.workspaceMode | default "shared" -}}
-{{- if eq $workspaceMode "shared" }}
+{{- if and (eq $workspaceMode "shared") .Values.workspaceResources.enabled }}
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 apiVersion: rbac.authorization.k8s.io/v1
diff --git a/deploy/helm/openshell/templates/serviceaccount.yaml b/deploy/helm/openshell/templates/serviceaccount.yaml
index a98ad5363e..8346ecfc2a 100644
--- a/deploy/helm/openshell/templates/serviceaccount.yaml
+++ b/deploy/helm/openshell/templates/serviceaccount.yaml
@@ -13,10 +13,10 @@ metadata:
     {{- toYaml . | nindent 4 }}
   {{- end }}
 {{- end }}
-{{- if and .Values.serviceAccount.create .Values.sandboxServiceAccount.create }}
+{{- if and .Values.serviceAccount.create .Values.workspaceResources.enabled .Values.sandboxServiceAccount.create }}
 ---
 {{- end }}
-{{- if .Values.sandboxServiceAccount.create }}
+{{- if and .Values.workspaceResources.enabled .Values.sandboxServiceAccount.create }}
 apiVersion: v1
 kind: ServiceAccount
 metadata:
diff --git a/deploy/helm/openshell/tests/sandbox_namespace_test.yaml b/deploy/helm/openshell/tests/sandbox_namespace_test.yaml
index ee89fce53d..864e3a8512 100644
--- a/deploy/helm/openshell/tests/sandbox_namespace_test.yaml
+++ b/deploy/helm/openshell/tests/sandbox_namespace_test.yaml
@@ -75,3 +75,21 @@ tests:
           path: metadata.namespace
           value: other-ns
         documentIndex: 1
+
+  - it: omits workspace resources in gateway-only mode
+    set:
+      workspaceResources.enabled: false
+      networkPolicy.enabled: true
+    asserts:
+      - hasDocuments:
+          count: 1
+        template: templates/gateway-config.yaml
+      - hasDocuments:
+          count: 0
+        template: templates/networkpolicy.yaml
+      - hasDocuments:
+          count: 0
+        template: templates/role.yaml
+      - hasDocuments:
+          count: 0
+        template: templates/rolebinding.yaml
diff --git a/deploy/helm/openshell/tests/sandbox_service_account_test.yaml b/deploy/helm/openshell/tests/sandbox_service_account_test.yaml
index c426415823..c9f10868fe 100644
--- a/deploy/helm/openshell/tests/sandbox_service_account_test.yaml
+++ b/deploy/helm/openshell/tests/sandbox_service_account_test.yaml
@@ -29,3 +29,13 @@ tests:
     asserts:
       - hasDocuments:
           count: 1
+
+  - it: renders only the gateway service account in gateway-only mode
+    set:
+      workspaceResources.enabled: false
+    asserts:
+      - hasDocuments:
+          count: 1
+      - equal:
+          path: metadata.name
+          value: openshell
diff --git a/deploy/helm/openshell/values.yaml b/deploy/helm/openshell/values.yaml
index 6b0b6242b0..c4c4f7cf4a 100644
--- a/deploy/helm/openshell/values.yaml
+++ b/deploy/helm/openshell/values.yaml
@@ -102,6 +102,14 @@ sandboxServiceAccount:
   # -- Existing service account name for sandbox pods when sandboxServiceAccount.create is false.
   name: ""
 
+# Namespace-scoped resources needed to run sandboxes. Disable this when the
+# gateway and workspace prerequisites are managed as separate Helm releases
+# using the openshell-workspace chart.
+workspaceResources:
+  # -- Create the sandbox ServiceAccount, Role, RoleBinding, and NetworkPolicy
+  # from this chart. Disable for a gateway-only release.
+  enabled: true
+
 # -- Extra annotations to add to the gateway pod.
 podAnnotations: {}
 # -- Extra labels to add to the gateway pod.
diff --git a/deploy/helm/test-split-ownership.sh b/deploy/helm/test-split-ownership.sh
new file mode 100755
index 0000000000..8c5d09b7ad
--- /dev/null
+++ b/deploy/helm/test-split-ownership.sh
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+work_dir="$(mktemp -d)"
+trap 'rm -rf "${work_dir}"' EXIT
+
+helm template openshell "${repo_root}/deploy/helm/openshell" \
+  --namespace openshell \
+  --set agentSandbox.preflight.enabled=false \
+  --set workspaceResources.enabled=false \
+  >"${work_dir}/gateway.yaml"
+
+helm template openshell-workspace "${repo_root}/deploy/helm/openshell-workspace" \
+  --namespace app-a \
+  --set gateway.serviceAccount.name=openshell \
+  --set gateway.serviceAccount.namespace=openshell \
+  >"${work_dir}/workspace.yaml"
+
+yq ea -N -r \
+  'select(.kind != null) | [.apiVersion, .kind, (.metadata.namespace // "openshell"), .metadata.name] | @tsv' \
+  "${work_dir}/gateway.yaml" | sort -u >"${work_dir}/gateway.objects"
+yq ea -N -r \
+  'select(.kind != null) | [.apiVersion, .kind, (.metadata.namespace // "app-a"), .metadata.name] | @tsv' \
+  "${work_dir}/workspace.yaml" | sort -u >"${work_dir}/workspace.objects"
+
+comm -12 "${work_dir}/gateway.objects" "${work_dir}/workspace.objects" \
+  >"${work_dir}/overlap.objects"
+if [[ -s "${work_dir}/overlap.objects" ]]; then
+  echo "gateway and workspace charts claim the same Kubernetes objects:" >&2
+  cat "${work_dir}/overlap.objects" >&2
+  exit 1
+fi
+
+echo "gateway and workspace chart object ownership is disjoint"
diff --git a/docs/kubernetes/setup.mdx b/docs/kubernetes/setup.mdx
index 221f935eb6..fb7881af2d 100644
--- a/docs/kubernetes/setup.mdx
+++ b/docs/kubernetes/setup.mdx
@@ -99,6 +99,36 @@ helm upgrade --install openshell \
 
 The chart automatically generates PKI secrets on first install using pre-install Helm hooks. No manual secret creation is required.
 
+### Split gateway and workspace releases
+
+For a platform-managed namespace, install the gateway without namespace-scoped
+sandbox resources, then install the workspace chart in the sandbox namespace:
+
+```shell
+helm upgrade --install openshell \
+  oci://ghcr.io/nvidia/openshell/helm-chart \
+  --version <version> \
+  --namespace openshell \
+  --set workspaceResources.enabled=false \
+  --set server.sandboxNamespace=app-a
+
+helm upgrade --install openshell-workspace \
+  oci://ghcr.io/nvidia/openshell/openshell-workspace \
+  --version <version> \
+  --namespace app-a \
+  --set gateway.serviceAccount.name=openshell \
+  --set gateway.serviceAccount.namespace=openshell
+```
+
+The workspace chart does not create the namespace or deploy a gateway. It owns
+only the sandbox ServiceAccount, Role, RoleBinding, and NetworkPolicy in its
+release namespace. For one pre-provisioned namespace, keep
+`server.drivers.kubernetes.workspaceMode=shared` and set
+`server.sandboxNamespace=app-a`. To map multiple workspaces to separately
+provisioned namespaces, use `workspaceMode=operator`, configure exactly one of
+`operatorNamespaceLabel` or `operatorNamespaceFile`, and install the workspace
+chart in every allowlisted namespace.
+
 ## Wait for the gateway to be ready
 
 ```shell
@@ -163,6 +193,7 @@ The most commonly changed values are:
 | `workload.kind` | Gateway workload controller. Use `statefulset` for SQLite or `deployment` with `server.externalDbSecret`. |
 | `workload.allowMultiReplicaStatefulSet` | Allow `replicaCount > 1` with `workload.kind=statefulset`. Prefer Deployment for external database-backed multi-replica gateways. |
 | `server.sandboxNamespace` | Namespace where sandbox pods are created. Defaults to the Helm release namespace when left empty. |
+| `workspaceResources.enabled` | Create namespace-scoped sandbox prerequisites from the gateway chart. Disable when installing the workspace chart separately. |
 | `server.externalDbSecret` | Secret containing a PostgreSQL connection URI in the `uri` key. Use when the database is managed outside the chart. |
 | `server.telemetryEnabled` | Enable anonymous OpenShell telemetry from the gateway and its sandbox supervisors. Set to `false` to opt out. |
 | `server.sandboxImage` | Default sandbox image used when a sandbox does not specify one. |
diff --git a/tasks/helm.toml b/tasks/helm.toml
index f7db8f9c57..525e9c2e51 100644
--- a/tasks/helm.toml
+++ b/tasks/helm.toml
@@ -4,27 +4,36 @@
 # Helm chart tasks
 
 ["helm:docs"]
-description = "Generate the openshell Helm chart README from Chart.yaml, values.yaml, and README.md.gotmpl"
-run = "helm-docs --chart-search-root deploy/helm/openshell"
+description = "Generate the OpenShell gateway and workspace Helm chart READMEs"
+run = """
+  helm-docs --chart-search-root deploy/helm/openshell
+  helm-docs --chart-search-root deploy/helm/openshell-workspace
+"""
 
 ["helm:docs:check"]
 description = "Verify the openshell Helm chart README is generated and up to date"
 run = """
   set -e
-  tmp="$(mktemp)"
-  trap 'rm -f "$tmp"' EXIT
+  gateway_tmp="$(mktemp)"
+  workspace_tmp="$(mktemp)"
+  trap 'rm -f "$gateway_tmp" "$workspace_tmp"' EXIT
 
-  helm-docs --chart-search-root deploy/helm/openshell --dry-run > "$tmp"
-  if ! diff -u deploy/helm/openshell/README.md "$tmp"; then
+  helm-docs --chart-search-root deploy/helm/openshell --dry-run > "$gateway_tmp"
+  if ! diff -u deploy/helm/openshell/README.md "$gateway_tmp"; then
     echo "Helm chart README is out of sync. Run: mise run helm:docs" >&2
     exit 1
   fi
+  helm-docs --chart-search-root deploy/helm/openshell-workspace --dry-run > "$workspace_tmp"
+  if ! diff -u deploy/helm/openshell-workspace/README.md "$workspace_tmp"; then
+    echo "Workspace Helm chart README is out of sync. Run: mise run helm:docs" >&2
+    exit 1
+  fi
 """
 run_windows = "echo Skipping helm:docs:check: Helm validation is not part of the native Windows lane."
 hide = true
 
 ["helm:lint"]
-description = "Lint the openshell Helm chart (defaults + all CI configuration variants)"
+description = "Lint the OpenShell gateway and workspace Helm charts"
 run = """
   set -e
   helm dependency build deploy/helm/openshell
@@ -37,12 +46,14 @@ run = """
     echo "values files: deploy/helm/openshell/values.yaml, $f"
     helm lint deploy/helm/openshell -f "$f" --set agentSandbox.preflight.enabled=false
   done
+  echo "--- helm lint: workspace defaults ---"
+  helm lint deploy/helm/openshell-workspace
   echo "All variants passed."
 """
 run_windows = "echo Skipping helm:lint: Helm validation is not part of the native Windows lane."
 
 ["helm:test"]
-description = "Run Helm chart unit tests"
+description = "Run gateway and workspace Helm chart unit tests"
 run = """
   set -e
   if ! helm plugin list | grep -q unittest; then
@@ -50,6 +61,8 @@ run = """
   fi
   helm dependency build deploy/helm/openshell
   helm unittest deploy/helm/openshell
+  helm unittest deploy/helm/openshell-workspace
+  deploy/helm/test-split-ownership.sh
 """
 run_windows = "echo Skipping helm:test: Helm validation is not part of the native Windows lane."
 

From 53df022d656727dfbb4743a7103b4c94732ad1c2 Mon Sep 17 00:00:00 2001
From: Dhiraj Bokde <dbokde@nvidia.com>
Date: Fri, 28 Aug 2026 19:58:14 -0700
Subject: [PATCH 2/4] fix(helm): preserve split chart upgrade compatibility

Keep workspace manifests valid after value validation and default legacy reused values to the combined resource topology.
---
 .../templates/_helpers.tpl                    |  6 ++--
 .../templates/networkpolicy.yaml              |  2 +-
 .../openshell-workspace/templates/role.yaml   |  2 +-
 .../templates/rolebinding.yaml                |  2 +-
 .../templates/serviceaccount.yaml             |  2 +-
 deploy/helm/openshell/templates/_helpers.tpl  | 13 +++++++++
 .../openshell/templates/networkpolicy.yaml    |  2 +-
 deploy/helm/openshell/templates/role.yaml     |  2 +-
 .../helm/openshell/templates/rolebinding.yaml |  2 +-
 .../openshell/templates/serviceaccount.yaml   |  4 +--
 deploy/helm/test-split-ownership.sh           | 28 +++++++++++++++++++
 11 files changed, 53 insertions(+), 12 deletions(-)

diff --git a/deploy/helm/openshell-workspace/templates/_helpers.tpl b/deploy/helm/openshell-workspace/templates/_helpers.tpl
index 8eaaaab2b7..eb948b9907 100644
--- a/deploy/helm/openshell-workspace/templates/_helpers.tpl
+++ b/deploy/helm/openshell-workspace/templates/_helpers.tpl
@@ -38,7 +38,7 @@ app.kubernetes.io/managed-by: {{ .Release.Service }}
 Validate required cross-namespace gateway identity values.
 */}}
 {{- define "openshell-workspace.validateValues" -}}
-{{- required "gateway.serviceAccount.name is required" .Values.gateway.serviceAccount.name -}}
-{{- required "gateway.serviceAccount.namespace is required" .Values.gateway.serviceAccount.namespace -}}
-{{- required "sandboxServiceAccount.name is required" .Values.sandboxServiceAccount.name -}}
+{{- $gatewayServiceAccountName := required "gateway.serviceAccount.name is required" .Values.gateway.serviceAccount.name -}}
+{{- $gatewayServiceAccountNamespace := required "gateway.serviceAccount.namespace is required" .Values.gateway.serviceAccount.namespace -}}
+{{- $sandboxServiceAccountName := required "sandboxServiceAccount.name is required" .Values.sandboxServiceAccount.name -}}
 {{- end }}
diff --git a/deploy/helm/openshell-workspace/templates/networkpolicy.yaml b/deploy/helm/openshell-workspace/templates/networkpolicy.yaml
index 4a5e2c2293..f88cf84d04 100644
--- a/deploy/helm/openshell-workspace/templates/networkpolicy.yaml
+++ b/deploy/helm/openshell-workspace/templates/networkpolicy.yaml
@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-{{- include "openshell-workspace.validateValues" . -}}
+{{- include "openshell-workspace.validateValues" . }}
 {{- if .Values.networkPolicy.enabled }}
 apiVersion: networking.k8s.io/v1
 kind: NetworkPolicy
diff --git a/deploy/helm/openshell-workspace/templates/role.yaml b/deploy/helm/openshell-workspace/templates/role.yaml
index e0d6d9624e..45b3beb831 100644
--- a/deploy/helm/openshell-workspace/templates/role.yaml
+++ b/deploy/helm/openshell-workspace/templates/role.yaml
@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-{{- include "openshell-workspace.validateValues" . -}}
+{{- include "openshell-workspace.validateValues" . }}
 apiVersion: rbac.authorization.k8s.io/v1
 kind: Role
 metadata:
diff --git a/deploy/helm/openshell-workspace/templates/rolebinding.yaml b/deploy/helm/openshell-workspace/templates/rolebinding.yaml
index 6b71d1f25b..669ec47628 100644
--- a/deploy/helm/openshell-workspace/templates/rolebinding.yaml
+++ b/deploy/helm/openshell-workspace/templates/rolebinding.yaml
@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-{{- include "openshell-workspace.validateValues" . -}}
+{{- include "openshell-workspace.validateValues" . }}
 apiVersion: rbac.authorization.k8s.io/v1
 kind: RoleBinding
 metadata:
diff --git a/deploy/helm/openshell-workspace/templates/serviceaccount.yaml b/deploy/helm/openshell-workspace/templates/serviceaccount.yaml
index f30663caa4..20bb263b54 100644
--- a/deploy/helm/openshell-workspace/templates/serviceaccount.yaml
+++ b/deploy/helm/openshell-workspace/templates/serviceaccount.yaml
@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-{{- include "openshell-workspace.validateValues" . -}}
+{{- include "openshell-workspace.validateValues" . }}
 {{- if .Values.sandboxServiceAccount.create }}
 apiVersion: v1
 kind: ServiceAccount
diff --git a/deploy/helm/openshell/templates/_helpers.tpl b/deploy/helm/openshell/templates/_helpers.tpl
index 548418abc6..842afd6876 100644
--- a/deploy/helm/openshell/templates/_helpers.tpl
+++ b/deploy/helm/openshell/templates/_helpers.tpl
@@ -70,6 +70,19 @@ Create the name of the service account assigned to sandbox pods
 {{- end }}
 {{- end }}
 
+{{/*
+Whether this chart owns workspace-scoped resources. Missing legacy values
+default to enabled so upgrades with --reuse-values preserve the old topology.
+*/}}
+{{- define "openshell.workspaceResourcesEnabled" -}}
+{{- $workspaceResources := .Values.workspaceResources | default dict -}}
+{{- $enabled := true -}}
+{{- if hasKey $workspaceResources "enabled" -}}
+{{- $enabled = get $workspaceResources "enabled" -}}
+{{- end -}}
+{{- if $enabled -}}true{{- end -}}
+{{- end }}
+
 {{/*
 Gateway image reference. Uses image.tag when set; falls back to .Chart.AppVersion
 so a released chart automatically pulls the matching image without extra overrides.
diff --git a/deploy/helm/openshell/templates/networkpolicy.yaml b/deploy/helm/openshell/templates/networkpolicy.yaml
index fb72604e60..c9e4a760e3 100644
--- a/deploy/helm/openshell/templates/networkpolicy.yaml
+++ b/deploy/helm/openshell/templates/networkpolicy.yaml
@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-{{- if and .Values.workspaceResources.enabled .Values.networkPolicy.enabled }}
+{{- if and (include "openshell.workspaceResourcesEnabled" .) .Values.networkPolicy.enabled }}
 # NetworkPolicy restricting SSH ingress on sandbox pods to the gateway pod.
 # Sandbox pods are dynamically created by the server and labelled with
 # openshell.ai/managed-by=openshell. This policy ensures only the gateway
diff --git a/deploy/helm/openshell/templates/role.yaml b/deploy/helm/openshell/templates/role.yaml
index 74d5728350..f20091f5d3 100644
--- a/deploy/helm/openshell/templates/role.yaml
+++ b/deploy/helm/openshell/templates/role.yaml
@@ -1,5 +1,5 @@
 {{- $workspaceMode := .Values.server.drivers.kubernetes.workspaceMode | default "shared" -}}
-{{- if and (eq $workspaceMode "shared") .Values.workspaceResources.enabled }}
+{{- if and (eq $workspaceMode "shared") (include "openshell.workspaceResourcesEnabled" .) }}
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 apiVersion: rbac.authorization.k8s.io/v1
diff --git a/deploy/helm/openshell/templates/rolebinding.yaml b/deploy/helm/openshell/templates/rolebinding.yaml
index 33add0ad15..32f11644bf 100644
--- a/deploy/helm/openshell/templates/rolebinding.yaml
+++ b/deploy/helm/openshell/templates/rolebinding.yaml
@@ -1,5 +1,5 @@
 {{- $workspaceMode := .Values.server.drivers.kubernetes.workspaceMode | default "shared" -}}
-{{- if and (eq $workspaceMode "shared") .Values.workspaceResources.enabled }}
+{{- if and (eq $workspaceMode "shared") (include "openshell.workspaceResourcesEnabled" .) }}
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 apiVersion: rbac.authorization.k8s.io/v1
diff --git a/deploy/helm/openshell/templates/serviceaccount.yaml b/deploy/helm/openshell/templates/serviceaccount.yaml
index 8346ecfc2a..1a9245d4dc 100644
--- a/deploy/helm/openshell/templates/serviceaccount.yaml
+++ b/deploy/helm/openshell/templates/serviceaccount.yaml
@@ -13,10 +13,10 @@ metadata:
     {{- toYaml . | nindent 4 }}
   {{- end }}
 {{- end }}
-{{- if and .Values.serviceAccount.create .Values.workspaceResources.enabled .Values.sandboxServiceAccount.create }}
+{{- if and .Values.serviceAccount.create (include "openshell.workspaceResourcesEnabled" .) .Values.sandboxServiceAccount.create }}
 ---
 {{- end }}
-{{- if and .Values.workspaceResources.enabled .Values.sandboxServiceAccount.create }}
+{{- if and (include "openshell.workspaceResourcesEnabled" .) .Values.sandboxServiceAccount.create }}
 apiVersion: v1
 kind: ServiceAccount
 metadata:
diff --git a/deploy/helm/test-split-ownership.sh b/deploy/helm/test-split-ownership.sh
index 8c5d09b7ad..0e1626aa5e 100755
--- a/deploy/helm/test-split-ownership.sh
+++ b/deploy/helm/test-split-ownership.sh
@@ -14,12 +14,40 @@ helm template openshell "${repo_root}/deploy/helm/openshell" \
   --set workspaceResources.enabled=false \
   >"${work_dir}/gateway.yaml"
 
+if yq ea -e \
+  'select(.kind == "Role" and .metadata.name == "openshell-sandbox")' \
+  "${work_dir}/gateway.yaml" >/dev/null 2>&1; then
+  echo "gateway chart rendered workspace resources despite workspaceResources.enabled=false" >&2
+  exit 1
+fi
+
 helm template openshell-workspace "${repo_root}/deploy/helm/openshell-workspace" \
   --namespace app-a \
   --set gateway.serviceAccount.name=openshell \
   --set gateway.serviceAccount.namespace=openshell \
   >"${work_dir}/workspace.yaml"
 
+invalid_workspace_docs="$(
+  yq ea -N -r \
+    'select(. != null and (.apiVersion == null or .kind == null)) | document_index' \
+    "${work_dir}/workspace.yaml"
+)"
+if [[ -n "${invalid_workspace_docs}" ]]; then
+  echo "workspace chart rendered documents without apiVersion or kind: ${invalid_workspace_docs}" >&2
+  exit 1
+fi
+
+helm template openshell "${repo_root}/deploy/helm/openshell" \
+  --namespace openshell \
+  --set agentSandbox.preflight.enabled=false \
+  --set-json workspaceResources=null \
+  >"${work_dir}/legacy-reuse-values.yaml"
+
+yq ea -e \
+  'select(.kind == "Role" and .metadata.name == "openshell-sandbox") |
+   .apiVersion == "rbac.authorization.k8s.io/v1"' \
+  "${work_dir}/legacy-reuse-values.yaml" >/dev/null
+
 yq ea -N -r \
   'select(.kind != null) | [.apiVersion, .kind, (.metadata.namespace // "openshell"), .metadata.name] | @tsv' \
   "${work_dir}/gateway.yaml" | sort -u >"${work_dir}/gateway.objects"

From 1cc2348943d46be85c0999c05fa3c41cae116f93 Mon Sep 17 00:00:00 2001
From: Dhiraj Bokde <dbokde@nvidia.com>
Date: Sat, 29 Aug 2026 12:31:26 -0700
Subject: [PATCH 3/4] fix(ci): preserve VM runtime for E2E

The Rust cache restores target/ after VM runtime artifacts are staged,
overwriting target/vm-runtime-compressed before openshell-driver-vm is built.
Stage the compressed runtime outside target and pass that location through
OPENSHELL_VM_RUNTIME_COMPRESSED_DIR so build.rs can embed the supervisor.

Also locate the Helm split-ownership test repository root from the script
path rather than git rev-parse. The test runs in a container where the
GitHub checkout can be owned by a different UID and rejected as dubious
ownership.

Signed-off-by: Dhiraj Bokde <dbokde@nvidia.com>
---
 .github/workflows/build-vm-driver.yml | 24 ++++++++++++------------
 deploy/helm/test-split-ownership.sh   |  2 +-
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/build-vm-driver.yml b/.github/workflows/build-vm-driver.yml
index a83c8c0834..ec73619be7 100644
--- a/.github/workflows/build-vm-driver.yml
+++ b/.github/workflows/build-vm-driver.yml
@@ -70,28 +70,28 @@ jobs:
       - name: Compress Linux VM runtime
         if: runner.os == 'Linux'
         run: |
-          install -d target/vm-runtime-compressed
-          zstd -19 -T0 result/libkrun.so -o target/vm-runtime-compressed/libkrun.so.zst
-          zstd -19 -T0 result/libkrunfw.so.5 -o target/vm-runtime-compressed/libkrunfw.so.5.zst
-          zstd -19 -T0 result/gvproxy -o target/vm-runtime-compressed/gvproxy.zst
-          zstd -19 -T0 result/umoci -o target/vm-runtime-compressed/umoci.zst
+          install -d .e2e/vm-runtime-compressed
+          zstd -19 -T0 result/libkrun.so -o .e2e/vm-runtime-compressed/libkrun.so.zst
+          zstd -19 -T0 result/libkrunfw.so.5 -o .e2e/vm-runtime-compressed/libkrunfw.so.5.zst
+          zstd -19 -T0 result/gvproxy -o .e2e/vm-runtime-compressed/gvproxy.zst
+          zstd -19 -T0 result/umoci -o .e2e/vm-runtime-compressed/umoci.zst
 
       - name: Compress macOS VM runtime
         if: runner.os == 'macOS'
         run: |
-          install -d target/vm-runtime-compressed
-          zstd -19 -T0 result/libkrun.dylib -o target/vm-runtime-compressed/libkrun.dylib.zst
-          zstd -19 -T0 result/libkrunfw.5.dylib -o target/vm-runtime-compressed/libkrunfw.5.dylib.zst
-          zstd -19 -T0 result/gvproxy -o target/vm-runtime-compressed/gvproxy.zst
-          zstd -19 -T0 result/umoci -o target/vm-runtime-compressed/umoci.zst
+          install -d .e2e/vm-runtime-compressed
+          zstd -19 -T0 result/libkrun.dylib -o .e2e/vm-runtime-compressed/libkrun.dylib.zst
+          zstd -19 -T0 result/libkrunfw.5.dylib -o .e2e/vm-runtime-compressed/libkrunfw.5.dylib.zst
+          zstd -19 -T0 result/gvproxy -o .e2e/vm-runtime-compressed/gvproxy.zst
+          zstd -19 -T0 result/umoci -o .e2e/vm-runtime-compressed/umoci.zst
 
       - name: Add openshell-sandbox to VM runtime
-        run: zstd -19 -T0 sandbox/openshell-sandbox -o target/vm-runtime-compressed/openshell-sandbox.zst
+        run: zstd -19 -T0 sandbox/openshell-sandbox -o .e2e/vm-runtime-compressed/openshell-sandbox.zst
 
       - name: Build openshell-driver-vm
         uses: ./.github/actions/build-rust-binary
         env:
-          OPENSHELL_VM_RUNTIME_COMPRESSED_DIR: ${{ github.workspace }}/target/vm-runtime-compressed
+          OPENSHELL_VM_RUNTIME_COMPRESSED_DIR: ${{ github.workspace }}/.e2e/vm-runtime-compressed
         with:
           package: openshell-driver-vm
           binary: openshell-driver-vm
diff --git a/deploy/helm/test-split-ownership.sh b/deploy/helm/test-split-ownership.sh
index 0e1626aa5e..30fd7360d4 100755
--- a/deploy/helm/test-split-ownership.sh
+++ b/deploy/helm/test-split-ownership.sh
@@ -4,7 +4,7 @@
 
 set -euo pipefail
 
-repo_root="$(git rev-parse --show-toplevel)"
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd -P)"
 work_dir="$(mktemp -d)"
 trap 'rm -rf "${work_dir}"' EXIT
 

From ca67ab54eeadccaa307e6b1ab345231523bcbe16 Mon Sep 17 00:00:00 2001
From: Dhiraj Bokde <dbokde@nvidia.com>
Date: Sat, 29 Aug 2026 13:01:36 -0700
Subject: [PATCH 4/4] fix(ci): install yq for Helm ownership test

The split-chart ownership regression uses yq to inspect rendered YAML,
but the Helm CI container installs only tools declared in mise.
Declare and lock yq so mise install --locked provides the test dependency.

Signed-off-by: Dhiraj Bokde <dbokde@nvidia.com>
---
 mise.lock | 28 ++++++++++++++++++++++++++++
 mise.toml |  1 +
 2 files changed, 29 insertions(+)

diff --git a/mise.lock b/mise.lock
index 23ce8b24e0..3a57cbf0e0 100644
--- a/mise.lock
+++ b/mise.lock
@@ -438,6 +438,34 @@ url = "https://github.com/astral-sh/uv/releases/download/0.10.12/uv-x86_64-pc-wi
 url_api = "https://api.github.com/repos/astral-sh/uv/releases/assets/377491992"
 provenance = "github-attestations"
 
+[[tools.yq]]
+version = "4.53.6"
+backend = "aqua:mikefarah/yq"
+
+[tools.yq."platforms.linux-arm64"]
+checksum = "sha256:88a1016bc1d657375a35864e4f44b6f333df8ff97b559f51bba0adcb2169df09"
+url = "https://github.com/mikefarah/yq/releases/download/v4.53.6/yq_linux_arm64"
+url_api = "https://api.github.com/repos/mikefarah/yq/releases/assets/522028007"
+provenance = "cosign"
+
+[tools.yq."platforms.linux-x64"]
+checksum = "sha256:c5f056448f973ae7d39b5401949648a78f2dc1947d6a8eb65be60d5c504b9385"
+url = "https://github.com/mikefarah/yq/releases/download/v4.53.6/yq_linux_amd64"
+url_api = "https://api.github.com/repos/mikefarah/yq/releases/assets/522028022"
+provenance = "cosign"
+
+[tools.yq."platforms.macos-arm64"]
+checksum = "sha256:cceb0b8d71ea5294334121f8429f33f92b920e7217d904a2f9f35443968ac424"
+url = "https://github.com/mikefarah/yq/releases/download/v4.53.6/yq_darwin_arm64"
+url_api = "https://api.github.com/repos/mikefarah/yq/releases/assets/522028033"
+provenance = "cosign"
+
+[tools.yq."platforms.windows-x64"]
+checksum = "sha256:ece3dd8bb50d39f93610506273ea262feb91e5c486bbddbb10abf91b2a6c0f14"
+url = "https://github.com/mikefarah/yq/releases/download/v4.53.6/yq_windows_amd64.exe"
+url_api = "https://api.github.com/repos/mikefarah/yq/releases/assets/522027974"
+provenance = "cosign"
+
 [[tools.zig]]
 version = "0.14.1"
 backend = "core:zig"
diff --git a/mise.toml b/mise.toml
index ec643ed08e..bd36408b80 100644
--- a/mise.toml
+++ b/mise.toml
@@ -33,6 +33,7 @@ go = "1.26"
 buf = "1.72.0"
 helm = { version = "4.2.0", version_prefix = "v" }
 helm-docs = "1.14.2"
+yq = "4.53.6"
 skaffold = { version = "2.20.0", os = ["linux", "macos"], version_prefix = "v" }
 # Keep k3d out of Linux CI images until upstream ships a release rebuilt with
 # patched Go/container dependencies. Linux Kubernetes E2E uses kind or an