Set Up OpenShell on Kubernetes

Use the Kubernetes deployment when the gateway should run on a shared cluster, in a cloud environment, or as part of team infrastructure. The Helm chart handles PKI bootstrap, RBAC, sandbox namespace setup, and the gateway workload. It uses a StatefulSet by default for the SQLite database, and can render a Deployment when server.externalDbSecret points at an external database.

Prerequisites

Make sure the following are in place before you install.

Install Agent Sandbox

OpenShell uses the Agent Sandbox Kubernetes SIG project to provision sandbox pods. Install the Agent Sandbox controller and its CRDs on your cluster before installing the OpenShell Helm chart.

Apply the latest release manifest:

kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/manifest.yaml

This creates the agent-sandbox-system namespace, installs the sandboxes.agents.x-k8s.io CRD, and starts the controller.

The Helm chart checks for a supported Agent Sandbox API before it creates gateway resources. This preflight is enabled by default. Disable it only for offline helm template rendering, where Helm cannot discover cluster APIs:

helm template openshell oci://ghcr.io/nvidia/openshell/helm-chart \
  --version <version> \
  --set agentSandbox.preflight.enabled=false

The chart does not install or upgrade the cluster-scoped Agent Sandbox CRDs or controller.

Confirm the controller pod is running before proceeding:

kubectl -n agent-sandbox-system get pods

The controller pod should reach Running status within a few seconds. For cluster-specific setup instructions, including KinD and GKE walkthroughs, refer to the Agent Sandbox getting started guide.

Upgrade Agent Sandbox

OpenShell detects the served Agent Sandbox Sandbox API when the Kubernetes gateway first needs it and caches that choice for the gateway process. If you upgrade Agent Sandbox in place, restart the OpenShell gateway after the Agent Sandbox controller and CRD rollout completes so the gateway can detect the served API versions again. Existing sandboxes keep running during the upgrade, and the restarted gateway can continue managing them.

Install OpenShell

kubectl create namespace openshell

helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version <version> \
  --namespace openshell

helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version 0.0.0-dev \
  --namespace openshell

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

kubectl -n openshell rollout status statefulset/openshell

kubectl -n openshell rollout status deployment/openshell

kubectl -n openshell port-forward svc/openshell 8080:8080

mkdir -p ~/.config/openshell/gateways/k8s/mtls
kubectl -n openshell get secret openshell-client-tls \
  -o jsonpath='{.data.ca\.crt}'  | base64 -d > ~/.config/openshell/gateways/k8s/mtls/ca.crt
kubectl -n openshell get secret openshell-client-tls \
  -o jsonpath='{.data.tls\.crt}' | base64 -d > ~/.config/openshell/gateways/k8s/mtls/tls.crt
kubectl -n openshell get secret openshell-client-tls \
  -o jsonpath='{.data.tls\.key}' | base64 -d > ~/.config/openshell/gateways/k8s/mtls/tls.key

openshell gateway add https://127.0.0.1:8080 --local --name k8s \
  --oidc-issuer https://your-idp.example.com/realms/openshell \
  --oidc-client-id openshell-cli
openshell status

Configure Chart Values

The most commonly changed values are:

Use a values file for repeatable deployments:

helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version <version> \
  --namespace openshell \
  --values my-values.yaml

The chart defaults server.appArmorProfile to Unconfined because runtime/default AppArmor profiles can block the supervisor’s network namespace mount setup on AppArmor-enabled nodes. Set server.appArmorProfile to an empty string to omit the field, RuntimeDefault to force the runtime default, or Localhost/<profile-name> when you load and manage a localhost profile on each node.

To use private sandbox images, create a kubernetes.io/dockerconfigjson Secret in the sandbox namespace and reference its name:

kubectl -n openshell create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username="$REGISTRY_USER" \
  --docker-password="$REGISTRY_TOKEN"

server:
  sandboxImage: registry.example.com/team/openshell-sandbox:latest
  sandboxImagePullSecrets:
    - name: regcred

Configure a Corporate Upstream Proxy

Configure a corporate forward proxy when sandbox TLS egress cannot dial the Internet directly. OpenShell evaluates policy and SSRF checks before it opens an HTTP CONNECT tunnel through the proxy. The proxy URL is operator-owned configuration. Sandbox environment variables cannot select, replace, or bypass it.

Create the credential Secret in the sandbox namespace when the proxy requires Basic authentication. The Secret value uses the user:pass form.

kubectl -n openshell create secret generic corporate-proxy-auth \
  --from-literal=credentials="$PROXY_USER:$PROXY_PASSWORD"

Add the proxy settings to your Helm values file. Replace the DNS suffixes and CIDRs in noProxy with values for your cluster. noProxy bypasses only the corporate proxy. OpenShell policy evaluation still applies.

upstreamProxy:
  url: http://proxy.corp.example:8080
  noProxy: .svc,.svc.cluster.local,10.96.0.0/12,10.244.0.0/16
  authSecret:
    name: corporate-proxy-auth
    key: credentials
  authAllowInsecure: true
supervisor:
  topology: sidecar

Use authAllowInsecure: true only when you accept that Basic authentication is cleartext on the connection to an http:// proxy. The initial release supports http:// proxy endpoints and TLS CONNECT egress. It does not support HTTPS-to-proxy, custom corporate CA bundles, or forwarding plain HTTP egress through the proxy.

Proxy credentials require sidecar topology. It mounts the credential only into the dedicated network supervisor container. OpenShell rejects credential Secrets with combined topology because Kubernetes fsGroup volume permission handling can make a shared credential mount readable by the sandbox group.

RBAC

The chart creates the following RBAC resources in the release namespace:

The namespaced Role covers sandbox lifecycle and identity:

The ClusterRole grants node inspection and token validation:

To use an existing ServiceAccount instead of creating one, set serviceAccount.create=false and supply its name:

helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version <version> \
  --namespace openshell \
  --set serviceAccount.create=false \
  --set serviceAccount.name=my-existing-sa

The ServiceAccount must already have the Role and ClusterRole bindings described above.

Probes

The gateway exposes /healthz for process liveness and /readyz for dependency-aware readiness on the health port. The Helm chart wires both into Kubernetes probes:

• startupProbe and livenessProbe use /healthz.
• readinessProbe uses /readyz, which reflects the latest result of an in-process background database check.

Next Steps

• To choose between combined and sidecar sandbox pods, refer to Topology.
• To enable automatic certificate rotation with cert-manager, refer to Managing Certificates.
• To expose the gateway externally without port-forwarding, refer to Ingress.
• To configure OIDC or reverse-proxy authentication, refer to Access Control.
• To create your first sandbox, refer to Manage Sandboxes.