Problem Statement
Operators deploying OpenShell in enterprise environments need to pull both the Gateway image and sandbox container images from private OCI registries. Today there is no supported way to configure pull credentials for sandbox pods, blocking private-registry deployments.
Proposed Design
Gateway image (already supported)
imagePullSecrets is already wired into values.yaml and the StatefulSet template. No work needed here — operators create a kubernetes.io/dockerconfigjson Secret and reference it:
imagePullSecrets:
- name: my-registry-secret
Sandbox images (gap to fill)
The Kubernetes driver supports imagePullPolicy for sandbox pods but has no equivalent for pull secrets. The fix spans three layers:
1. Helm values — add server.sandboxImagePullSecrets parallel to the existing gateway field:
server:
sandboxImagePullSecrets: []
# e.g.:
# sandboxImagePullSecrets:
# - name: my-registry-secret
2. Server CLI / config — expose a new --sandbox-image-pull-secrets flag (env: OPENSHELL_SANDBOX_IMAGE_PULL_SECRETS) and thread it through to KubernetesComputeConfig, parallel to the existing image_pull_policy field (crates/openshell-driver-kubernetes/src/config.rs:8).
3. Driver pod spec — inject imagePullSecrets into the sandbox pod spec in the same locations where imagePullPolicy is already applied (crates/openshell-driver-kubernetes/src/driver.rs:850, 921, 967, 1033).
Supervisor image
The supervisor binary is side-loaded via a hostPath volume — it is not pulled from a registry — so no pull secret configuration is needed for it.
Alternatives Considered
ServiceAccount-attached pull secrets: Kubernetes automatically applies imagePullSecrets defined on a ServiceAccount to all pods using that SA. This is a valid cluster-level approach but requires operators to know and configure the sandbox pod SA, which is not currently surfaced. The explicit sandboxImagePullSecrets value is simpler and directly parallel to the gateway pattern already in the chart.
Agent Investigation
imagePullSecrets for the Gateway StatefulSet is already present in deploy/helm/openshell/templates/statefulset.yaml and values.yaml — no changes needed.
imagePullPolicy for sandbox pods flows through KubernetesComputeConfig.image_pull_policy → CLI arg --sandbox-image-pull-policy → Helm env var OPENSHELL_SANDBOX_IMAGE_PULL_POLICY. The imagePullSecrets addition follows the same pattern.
- Pod spec injection points are at
driver.rs:850, 921, 967, and 1033 where imagePullPolicy is currently applied.
Checklist
Problem Statement
Operators deploying OpenShell in enterprise environments need to pull both the Gateway image and sandbox container images from private OCI registries. Today there is no supported way to configure pull credentials for sandbox pods, blocking private-registry deployments.
Proposed Design
Gateway image (already supported)
imagePullSecretsis already wired intovalues.yamland the StatefulSet template. No work needed here — operators create akubernetes.io/dockerconfigjsonSecret and reference it:Sandbox images (gap to fill)
The Kubernetes driver supports
imagePullPolicyfor sandbox pods but has no equivalent for pull secrets. The fix spans three layers:1. Helm values — add
server.sandboxImagePullSecretsparallel to the existing gateway field:2. Server CLI / config — expose a new
--sandbox-image-pull-secretsflag (env:OPENSHELL_SANDBOX_IMAGE_PULL_SECRETS) and thread it through toKubernetesComputeConfig, parallel to the existingimage_pull_policyfield (crates/openshell-driver-kubernetes/src/config.rs:8).3. Driver pod spec — inject
imagePullSecretsinto the sandbox pod spec in the same locations whereimagePullPolicyis already applied (crates/openshell-driver-kubernetes/src/driver.rs:850, 921, 967, 1033).Supervisor image
The supervisor binary is side-loaded via a hostPath volume — it is not pulled from a registry — so no pull secret configuration is needed for it.
Alternatives Considered
ServiceAccount-attached pull secrets: Kubernetes automatically applies
imagePullSecretsdefined on a ServiceAccount to all pods using that SA. This is a valid cluster-level approach but requires operators to know and configure the sandbox pod SA, which is not currently surfaced. The explicitsandboxImagePullSecretsvalue is simpler and directly parallel to the gateway pattern already in the chart.Agent Investigation
imagePullSecretsfor the Gateway StatefulSet is already present indeploy/helm/openshell/templates/statefulset.yamlandvalues.yaml— no changes needed.imagePullPolicyfor sandbox pods flows throughKubernetesComputeConfig.image_pull_policy→ CLI arg--sandbox-image-pull-policy→ Helm env varOPENSHELL_SANDBOX_IMAGE_PULL_POLICY. TheimagePullSecretsaddition follows the same pattern.driver.rs:850,921,967, and1033whereimagePullPolicyis currently applied.Checklist