fix(images): update gateway base and allow supervisor base override

Signed-off-by: Adrien Langou <alangou@nvidia.com>

Author: alangou

CONTRIBUTING.md

@@ -279,6 +279,22 @@ each worktree. Cache reuse therefore depends on the compiler inputs: outputs
 that embed absolute paths, including Rust dependencies in some builds, can
 still miss across worktrees.
 
+## Container Image Base Overrides
+
+The gateway and supervisor Dockerfiles accept `GATEWAY_BASE_IMAGE` and
+`SUPERVISOR_BASE_IMAGE` build arguments. Omitting them keeps the pinned
+distroless defaults. To build with your own bases, pass the argument through
+the corresponding task:
+
+```shell
+mise run build:docker:gateway -- --build-arg GATEWAY_BASE_IMAGE=registry.example.com/gateway-base:tag
+mise run build:docker:supervisor -- --build-arg SUPERVISOR_BASE_IMAGE=registry.example.com/supervisor-base:tag
+```
+
+Choose bases that provide the GNU runtime libraries required by the binaries
+and CA certificates for the target architecture. Validate the resulting images
+with your deployment. The sandbox image uses `scratch` and has no base override.
+
 ## Main Tasks
 
 These are the primary `mise` tasks for day-to-day development:

deploy/docker/Dockerfile.gateway

@@ -8,7 +8,7 @@
 #
 # Distroless Debian provides the glibc runtime required by the binary.
 
-ARG GATEWAY_BASE_IMAGE=gcr.io/distroless/cc-debian13:nonroot@sha256:54df941ed0d06a1bd95ef5e0ce391fd8d9f94b64782dc9a60062727849ee3f97
+ARG GATEWAY_BASE_IMAGE=gcr.io/distroless/cc-debian13:nonroot@sha256:e792ab3d241a468a4fd7519ddbbebe66b49b5f365771716ea688ad40b6c6f1c2
 FROM ${GATEWAY_BASE_IMAGE} AS gateway
 
 ARG TARGETARCH

deploy/docker/Dockerfile.supervisor

@@ -8,7 +8,8 @@
 
 # Keep the GNU runtime and CA roots without a shell or unused native TLS libraries.
 # The default variant preserves UID 0 and /; compute drivers set the runtime UID.
-FROM gcr.io/distroless/base-nossl-debian13@sha256:af5cb8dd589b8520b8c06bebb9efb73d7e16406cab58e85c51761fff49d370a0 AS supervisor
+ARG SUPERVISOR_BASE_IMAGE=gcr.io/distroless/base-nossl-debian13@sha256:af5cb8dd589b8520b8c06bebb9efb73d7e16406cab58e85c51761fff49d370a0
+FROM ${SUPERVISOR_BASE_IMAGE} AS supervisor
 
 ARG TARGETARCH
 

docs/how-it-works/sandboxes/runtimes.mdx

@@ -44,6 +44,11 @@ driver TOML overrides the compiled release defaults. Helm renders Kubernetes
 image fields into TOML, so they apply when these environment variables are
 unset. Sandbox requests cannot override either trusted image.
 
+When building your own gateway or supervisor image, the `GATEWAY_BASE_IMAGE`
+and `SUPERVISOR_BASE_IMAGE` build arguments override their pinned bases. See
+[Container Image Base Overrides](https://github.com/NVIDIA/OpenShell/blob/main/CONTRIBUTING.md#container-image-base-overrides)
+for build commands and base compatibility requirements.
+
 For TLS-enabled Docker, Podman, and MicroVM gateways, set `guest_tls_ca` in
 `[openshell.gateway]` or use the package-managed local CA. Remove the retired
 `guest_tls_cert` and `guest_tls_key` fields. Supervisors receive only the

skills/debug-openshell-cluster/SKILL.md

@@ -93,6 +93,11 @@ Use gateway metadata, deployment values, or the user's setup notes to identify t
 
 Before debugging the compute platform, inspect gateway logs for failures in dependencies initialized before the listener becomes ready.
 
+The gateway container uses a Distroless Debian runtime. For OS-library
+vulnerability findings, check the deployed image digest and package version;
+deploy a rebuilt gateway image with the patched base. Updating the gateway
+binary alone does not update the libraries supplied by its container image.
+
 For resource-admission failures, distinguish disabled caller driver config from
 missing resource approval. Helm defaults `server.drivers.kubernetes.allowDriverConfig`
 to false and `resourceAdmission.enabled` to true. Existing PVCs, RuntimeClasses,
@@ -213,6 +218,8 @@ rationale, configured and effective modes, active generation, and the explicit
 `previous_policy_active` state.
 
 The published supervisor image uses a shell-free distroless Debian 13 base.
+For custom builds using `SUPERVISOR_BASE_IMAGE`, check the selected base's GNU
+runtime libraries, CA certificates, and inherited user and working directory.
 Use container logs, engine inspection and the configured exec health probe for
 diagnostics; `exec ... sh`, package installation and in-container shell scripts
 are unavailable. Workload shells belong to the separate sandbox image. Preserve