openshell-driver-kubernetes

openshell-driver-kubernetes [--bind-socket PATH] [options]

openshell-driver-kubernetes is the Kubernetes compute driver for NVIDIA OpenShell. openshell-gateway can run the same driver in-process, or it can connect to this binary. The process serves the ComputeDriver gRPC API. It uses the Kubernetes API to create, delete, fetch, and watch sandbox custom resources, and it stops on SIGINT or SIGTERM.With --bind-socket, the listener is a private Unix socket (directory mode 0700, socket mode 0600) that accepts only a same-user peer. Without that flag, the process listens on --bind-address (default 127.0.0.1:50061) with no peer check.--workspace-mode chooses where sandboxes land:- shared (the default): every sandbox is rendered into --sandbox-namespace. Resource names use the workspace and the sandbox name, joined by a double hyphen, so they do not collide.- managed: the driver creates and deletes a namespace per workspace, named openshell-, the gateway id, and the workspace name. It also creates a service account in that namespace. On OpenShift it waits for the namespace's own SELinux and uid-range annotations before provisioning.- operator: workspace names map one-to-one onto namespaces that already exist. Exactly one discovery source is allowed: --operator-namespace-label or --operator-namespace-file. Creation fails closed when the workspace is not on that list. Deleting a workspace removes gateway state only. It does not delete the namespace.The workload Pod stages a static musl openshell-sandbox from --sandbox-runtime-image. A separate Pod runs a glibc openshell-supervisor from --supervisor-image. When those flags are omitted, the driver uses the images compiled into OpenShell. The workload receives no gateway credential, provider identity socket, or corporate-proxy credential. Caller driver config is off unless --admission-config-json turns it on. The default value {} disables caller driver config and requires labels. GPU devices are temporarily exempt.

--bind-socket PATH

Unix socket for the ComputeDriver service. When set, --bind-address is not used.

TCP listen address when --bind-socket is omitted. Default 127.0.0.1:50061. No peer authentication.

Operator admission policy. Default {} disables caller driver config and requires labels.

shared, managed, or operator. Default shared.

Used in managed-mode namespace names. Default openshell.

Namespace for shared mode. Default default.

The one allowlist source for operator mode. A label selector waits up to 10 seconds for the first namespace list after a restart, then returns unavailable.

Service account used by sandbox pods. Default default.

Workload image when a create request omits one.

always, if not present, or never. There is no default on this flag.

Comma-separated image-pull secret names. These are operator configuration, not caller attachments. Managed mode stages an immutable copy per runtime generation.

Comma-separated names the driver may copy onto pods.

Turn on managed SSH ingress. Default is off.

Namespace of the SSH gateway pods used by managed ingress.

Comma-separated key=value pairs selecting those pods. An entry without an equals sign is an error.

Where supervisors reach the gateway. Empty when omitted.

Kubernetes Secret that holds the gateway client TLS material.

Host address published to sandboxes, when set.

Image that contains openshell-sandbox, and its pull policy (always, if not present, or never).

Image that contains openshell-supervisor, and its pull policy.

TCP port of the sandbox protocol listener. Default 5500.

Corporate HTTP forward proxy for policy-approved TLS CONNECT egress, and a comma-separated bypass list.

Kubernetes Secret name and key that hold the upstream proxy credential.

Acknowledge cleartext Basic authentication to an http proxy. Default is off.

Send destination hostnames rather than validated IP addresses in CONNECT. Default is off.

PEM CA bundle trusted for the corporate proxy. This process reads it and stages it into each sandbox supervisor bootstrap Secret.

Enable user namespaces for sandbox pods. Default is off.

Lifetime of the projected service-account token kubelet writes for the sandbox bootstrap exchange. Default 3600. Kubelet enforces a minimum of 600. The gateway clamps values to the range 600 through 86400.

Workload API socket path projected for provider token exchange.

Run sandbox pods as this uid and gid, when set. Otherwise the namespace-resolved non-root ids are used.

Interactive SSH socket inside the sandbox. Default /run/openshell/ssh.sock.

Driver log level. Default info.

OTLP/gRPC collector and the gateway name attached to exported traces. The trace service name is openshell-driver-kubernetes.

OTLP/gRPC collector for supervisor OCSF events, and the schema version those events are downgraded to. The schema flag requires the endpoint flag.

Select this driver from the gateway with --compute-driver kubernetes. A minimal file:

$ [openshell]
version = 2

[openshell.gateway]
compute_driver = "kubernetes"

[openshell.drivers.kubernetes]
workspace_mode = "shared"
namespace = "openshell"
grpc_endpoint = "https://gateway.example:17670"

$ --admission-config-json              OPENSHELL_DRIVER_ADMISSION_CONFIG_JSON
--bind-socket                        OPENSHELL_COMPUTE_DRIVER_SOCKET
--bind-address                       OPENSHELL_COMPUTE_DRIVER_BIND
--workspace-mode                     OPENSHELL_WORKSPACE_MODE
--gateway-id                         OPENSHELL_GATEWAY_ID
--sandbox-namespace                  OPENSHELL_SANDBOX_NAMESPACE
--operator-namespace-label           OPENSHELL_OPERATOR_NAMESPACE_LABEL
--operator-namespace-file            OPENSHELL_OPERATOR_NAMESPACE_FILE
--sandbox-service-account            OPENSHELL_K8S_SANDBOX_SERVICE_ACCOUNT
--sandbox-image                      OPENSHELL_SANDBOX_IMAGE
--sandbox-image-pull-policy          OPENSHELL_SANDBOX_IMAGE_PULL_POLICY
--sandbox-image-pull-secrets         OPENSHELL_SANDBOX_IMAGE_PULL_SECRETS
--allowed-pod-annotations            OPENSHELL_K8S_ALLOWED_POD_ANNOTATIONS
--allowed-pod-labels                 OPENSHELL_K8S_ALLOWED_POD_LABELS
--managed-ssh-ingress-enabled        OPENSHELL_MANAGED_SSH_INGRESS_ENABLED
--managed-ssh-gateway-namespace      OPENSHELL_MANAGED_SSH_GATEWAY_NAMESPACE
--managed-ssh-gateway-pod-selector   OPENSHELL_MANAGED_SSH_GATEWAY_POD_SELECTOR
--grpc-endpoint                      OPENSHELL_GRPC_ENDPOINT
--client-tls-secret-name             OPENSHELL_CLIENT_TLS_SECRET_NAME
--host-gateway-ip                    OPENSHELL_HOST_GATEWAY_IP
--sandbox-runtime-image              OPENSHELL_SANDBOX_RUNTIME_IMAGE
--sandbox-runtime-image-pull-policy  OPENSHELL_SANDBOX_RUNTIME_IMAGE_PULL_POLICY
--supervisor-image                   OPENSHELL_SUPERVISOR_IMAGE
--supervisor-image-pull-policy       OPENSHELL_SUPERVISOR_IMAGE_PULL_POLICY
--sandbox-runtime-boundary-port      OPENSHELL_K8S_SANDBOX_RUNTIME_BOUNDARY_PORT
--https-proxy                        OPENSHELL_UPSTREAM_PROXY
--no-proxy                           OPENSHELL_UPSTREAM_NO_PROXY
--proxy-auth-secret-name             OPENSHELL_UPSTREAM_PROXY_AUTH_SECRET_NAME
--proxy-auth-secret-key              OPENSHELL_UPSTREAM_PROXY_AUTH_SECRET_KEY
--proxy-auth-allow-insecure          OPENSHELL_UPSTREAM_PROXY_AUTH_ALLOW_INSECURE
--proxy-connect-by-hostname          OPENSHELL_UPSTREAM_PROXY_CONNECT_BY_HOSTNAME
--proxy-ca-bundle                    OPENSHELL_UPSTREAM_PROXY_CA_BUNDLE
--enable-user-namespaces             OPENSHELL_ENABLE_USER_NAMESPACES
--sa-token-ttl-secs                  OPENSHELL_K8S_SA_TOKEN_TTL_SECS
--provider-spiffe-workload-api-socket OPENSHELL_PROVIDER_SPIFFE_WORKLOAD_API_SOCKET
--sandbox-uid                        OPENSHELL_K8S_SANDBOX_UID
--sandbox-gid                        OPENSHELL_K8S_SANDBOX_GID
--sandbox-ssh-socket-path            OPENSHELL_SANDBOX_SSH_SOCKET_PATH
--log-level                          OPENSHELL_LOG_LEVEL
--otlp-endpoint                      OPENSHELL_OTLP_ENDPOINT
--otlp-ocsf-endpoint                 OPENSHELL_OTLP_OCSF_ENDPOINT
--otlp-ocsf-schema-version           OPENSHELL_OTLP_OCSF_SCHEMA_VERSION
--gateway-name                       OPENSHELL_GATEWAY_NAME

$ always
if_not_present
never

TCP listen mode has no peer check. Do not expose --bind-address.--sandbox-namespace defaults to default on this binary. That is not the same string as the managed-mode namespace prefix.A runtime class name can be supplied only by the process environment. There is no flag for it:

$ OPENSHELL_K8S_DEFAULT_RUNTIME_CLASS_NAME

openshell-driver-kubernetes ships in NVIDIA OpenShell (Apache License 2.0). OpenShell was first published in March 2026. The 0.1.x line is the stable release cadence.

openshell(1), openshell-gateway(1), openshell-supervisor(1), openshell-sandbox(1), openshell-driver-docker(1), openshell-driver-podman(1), openshell-driver-kubernetes-secrets(1), openshell-driver-vm(1), kubectl(1)

Source code · Homepage · Documentation