refactor(docker): rename server image to gateway (#246)

* refactor(docker): rename server image to gateway

Rename Dockerfile.server to Dockerfile.gateway and update all image
references from openshell/server to openshell/gateway across Helm
charts, Kubernetes manifests, mise tasks, build/deploy scripts, CI
workflows, and documentation.

The underlying Rust binary (navigator-server) is unchanged -- this
rename only affects the Docker image name and Dockerfile.

* fix: catch remaining server->gateway references in docs and comments

Author: drew

.agents/skills/debug-navigator-cluster/SKILL.md

@@ -230,7 +230,7 @@ docker save <image-ref> | docker exec -i openshell-cluster-<name> ctr -a /run/k3
 docker exec openshell-cluster-<name> cat /etc/rancher/k3s/registries.yaml
 
 # Test pulling an image manually from inside the cluster
-docker exec openshell-cluster-<name> sh -lc 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml crictl pull ghcr.io/nvidia/openshell/server:latest'
+docker exec openshell-cluster-<name> sh -lc 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml crictl pull ghcr.io/nvidia/openshell/gateway:latest'
 ```
 
 If `registries.yaml` is missing or has wrong values, verify env wiring (`OPENSHELL_REGISTRY_HOST`, `OPENSHELL_REGISTRY_INSECURE`, username/password for authenticated registries).

.claude/agent-memory/arch-doc-writer/MEMORY.md

@@ -59,16 +59,16 @@
 - Proto files also include: `proto/inference.proto` (navigator.inference.v1)
 
 ## Container/Build Details
-- Four runtime images: sandbox (5 stages), server (2 stages), cluster (k3s base), pki-job (Alpine)
+- Four runtime images: sandbox (5 stages), gateway (2 stages), cluster (k3s base), pki-job (Alpine)
 - Two build-only images: python-wheels (Linux multi-arch), python-wheels-macos (osxcross cross-compile)
 - CI image: Dockerfile.ci (Ubuntu 24.04, pre-installs docker/buildx/aws/kubectl/helm/mise/uv/sccache/socat)
-- Cross-compilation: `deploy/docker/cross-build.sh` shared by sandbox + server Dockerfiles
+- Cross-compilation: `deploy/docker/cross-build.sh` shared by sandbox + gateway Dockerfiles
 - Sandbox image has coding-agents stage: Claude CLI (native installer), OpenCode, Codex (npm)
 - Helm chart deploys a StatefulSet (NOT Deployment), PVC 1Gi at /var/navigator
 - Cluster image does NOT bundle image tarballs -- components pulled at runtime from distribution registry
 - PKI job generates CA + server cert + client cert for mTLS (RSA 2048, 10yr, Helm pre-install hook)
 - Build tasks in `tasks/*.toml`; scripts in `tasks/scripts/`
-- `cluster-deploy-fast.sh` supports both auto mode (git diff) and explicit targets (server/sandbox/pki-job/chart/all)
+- `cluster-deploy-fast.sh` supports both auto mode (git diff) and explicit targets (gateway/sandbox/chart/all)
 - `cluster-bootstrap.sh` ensures local Docker registry on port 5000, pushes all components, then deploys
 - Default values.yaml: repository is CloudFront-backed CDN, tag: "latest", pullPolicy: Always
 - Envoy Gateway version: v1.5.8 (set in mise.toml)

.github/workflows/docker-build.yml

@@ -4,7 +4,7 @@ on:
   workflow_call:
     inputs:
       component:
-        description: "Component to build (server, sandbox, cluster)"
+        description: "Component to build (gateway, sandbox, cluster)"
         required: true
         type: string
       timeout-minutes:

.github/workflows/e2e.yml

@@ -9,11 +9,11 @@ permissions:
   packages: write
 
 jobs:
-  build-server:
+  build-gateway:
     if: contains(github.event.pull_request.labels.*.name, 'e2e')
     uses: ./.github/workflows/docker-build.yml
     with:
-      component: server
+      component: gateway
 
   build-sandbox:
     if: contains(github.event.pull_request.labels.*.name, 'e2e')
@@ -28,7 +28,7 @@ jobs:
       component: cluster
 
   e2e:
-    needs: [build-server, build-sandbox, build-cluster]
+    needs: [build-gateway, build-sandbox, build-cluster]
     uses: ./.github/workflows/e2e-test.yml
     with:
       image-tag: ${{ github.sha }}

.github/workflows/publish.yml

@@ -14,10 +14,10 @@ defaults:
     shell: bash
 
 jobs:
-  build-server:
+  build-gateway:
     uses: ./.github/workflows/docker-build.yml
     with:
-      component: server
+      component: gateway
 
   build-sandbox:
     uses: ./.github/workflows/docker-build.yml
@@ -31,7 +31,7 @@ jobs:
 
   tag-ghcr-latest:
     name: Tag GHCR Images as Latest
-    needs: [build-server, build-sandbox, build-cluster]
+    needs: [build-gateway, build-sandbox, build-cluster]
     runs-on: build-amd64
     timeout-minutes: 10
     steps:
@@ -42,7 +42,7 @@ jobs:
         run: |
           set -euo pipefail
           REGISTRY="ghcr.io/nvidia/openshell"
-          for component in server sandbox cluster; do
+          for component in gateway sandbox cluster; do
             echo "Tagging ${REGISTRY}/${component}:${{ github.sha }} as latest..."
             docker buildx imagetools create \
               --prefer-index=false \
@@ -52,7 +52,7 @@ jobs:
 
   build-python-wheels:
     name: Stage Python Wheels
-    needs: [build-server, build-sandbox, build-cluster]
+    needs: [build-gateway, build-sandbox, build-cluster]
     runs-on: build-amd64
     timeout-minutes: 120
     outputs:

architecture/build-containers.md

@@ -9,7 +9,7 @@ deploy/
   docker/
     .dockerignore
     Dockerfile.sandbox             # Sandbox container (runs agent code in isolation)
-    Dockerfile.server              # Gateway container (orchestration / control plane)
+    Dockerfile.gateway             # Gateway container (orchestration / control plane)
     Dockerfile.cluster             # Airgapped k3s cluster with Helm charts and manifests
     Dockerfile.ci                  # CI runner image with pre-installed toolchain
     Dockerfile.python-wheels       # Multi-arch Linux wheel builder for the Python CLI package
@@ -74,11 +74,11 @@ The sandbox container runs inside each sandbox pod. It contains the sandbox supe
 - Policy files are mounted at `/var/navigator/policy.rego` (rules) and `/var/navigator/data.yaml` (data) when running in file-based policy mode.
 - The Python SDK is copied directly into the venv's site-packages at `/app/.venv/lib/python3.12/site-packages/openshell/`.
 
-### Gateway Image (`openshell/server`)
+### Gateway Image (`openshell/gateway`)
 
 The gateway container runs the control plane / orchestration service.
 
-**Build stages** (2 stages in `deploy/docker/Dockerfile.server`):
+**Build stages** (2 stages in `deploy/docker/Dockerfile.gateway`):
 
 1. **builder** -- Two-pass Rust compilation with dependency caching:
    - First pass copies only `Cargo.toml`/`Cargo.lock` files and creates dummy source files (`fn main() {}` / empty `lib.rs`) to build dependencies in isolation. This layer is cached unless dependency manifests change.
@@ -195,7 +195,7 @@ Modifies the HelmChart manifest at `/var/lib/rancher/k3s/server/manifests/naviga
 | Variable | Effect |
 |---|---|
 | `IMAGE_REPO_BASE` | Rewrites `repository:` and `sandboxImage:` to use the specified base path |
-| `PUSH_IMAGE_REFS` | Parses comma-separated image refs and rewrites exact server and sandbox references (matching on path component `/server:`, `/sandbox:`) |
+| `PUSH_IMAGE_REFS` | Parses comma-separated image refs and rewrites exact gateway and sandbox references (matching on path component `/gateway:`, `/sandbox:`) |
 | `IMAGE_TAG` | Replaces `:latest` tags with the specified tag (handles both quoted and unquoted `tag: latest` formats) |
 | `IMAGE_PULL_POLICY` | Replaces `pullPolicy: Always` with the specified policy (e.g., `IfNotPresent`) |
 | `SSH_GATEWAY_HOST` / `SSH_GATEWAY_PORT` | Replaces `__SSH_GATEWAY_HOST__` and `__SSH_GATEWAY_PORT__` placeholders; clears to defaults if unset |
@@ -228,7 +228,7 @@ The Helm chart at `deploy/helm/navigator/` deploys the gateway to Kubernetes as
 replicaCount: 1
 
 image:
-  repository: ghcr.io/nvidia/openshell/server
+  repository: ghcr.io/nvidia/openshell/gateway
   pullPolicy: Always
   tag: "latest"
 
@@ -306,7 +306,7 @@ All builds use mise tasks defined in `tasks/*.toml` (included from `mise.toml`).
 |---|---|
 | `mise run docker:build` | Build all runtime images (sandbox, gateway, cluster) |
 | `mise run docker:build:sandbox` | Build sandbox image |
-| `mise run docker:build:server` | Build gateway image |
+| `mise run docker:build:gateway` | Build gateway image |
 | `mise run docker:build:cluster` | Build k3s cluster image (packages Helm charts first) |
 | `mise run docker:build:ci` | Build CI runner image |
 | `mise run docker:build:cluster:multiarch` | Build multi-arch cluster image and push to a registry |
@@ -336,11 +336,11 @@ All builds use mise tasks defined in `tasks/*.toml` (included from `mise.toml`).
 | `Cargo.toml`, `Cargo.lock`, `proto/*`, `deploy/docker/cross-build.sh` | Gateway + sandbox rebuild |
 | `crates/navigator-core/*`, `crates/navigator-providers/*` | Gateway + sandbox rebuild |
 | `crates/navigator-router/*` | Gateway rebuild |
-| `crates/navigator-server/*`, `deploy/docker/Dockerfile.server` | Gateway rebuild |
+| `crates/navigator-server/*`, `deploy/docker/Dockerfile.gateway` | Gateway rebuild |
 | `crates/navigator-sandbox/*`, `deploy/docker/sandbox/*`, `python/*`, `pyproject.toml`, `uv.lock`, `crates/navigator-sandbox/data/sandbox-policy.rego` | Sandbox rebuild |
 | `deploy/helm/navigator/*` | Helm upgrade |
 
-**Explicit target mode** (arguments: `server`, `sandbox`, `chart`, `all`): Rebuilds only the specified components.
+**Explicit target mode** (arguments: `gateway`, `sandbox`, `chart`, `all`): Rebuilds only the specified components.
 
 Auto mode persists the last deployed fingerprints in `.cache/cluster-deploy-fast.state` (or `$DEPLOY_FAST_STATE_FILE`). Re-running `mise run cluster` without new local changes prints `No new local changes since last deploy.` and skips rebuild/upgrade work.
 
@@ -461,7 +461,7 @@ When the cluster container starts, k3s automatically deploys these HelmChart CRs
 ## Implementation References
 
 - `deploy/docker/Dockerfile.sandbox` -- Sandbox image (5-stage multi-arch build)
-- `deploy/docker/Dockerfile.server` -- Gateway image (2-stage with dependency caching)
+- `deploy/docker/Dockerfile.gateway` -- Gateway image (2-stage with dependency caching)
 - `deploy/docker/Dockerfile.cluster` -- Cluster image (k3s base + charts + manifests)
 - `deploy/docker/Dockerfile.ci` -- CI runner image (Ubuntu + full toolchain)
 - `deploy/docker/Dockerfile.python-wheels` -- Linux wheel builder

architecture/gateway-single-node.md

@@ -289,7 +289,7 @@ Copies bundled manifests from `/opt/navigator/manifests/` to `/var/lib/rancher/k
 When environment variables are set, the entrypoint modifies the HelmChart manifest at `/var/lib/rancher/k3s/server/manifests/navigator-helmchart.yaml`:
 
 - `IMAGE_REPO_BASE`: Rewrites `repository:`, `sandboxImage:`, and `jobImage:` in the HelmChart.
-- `PUSH_IMAGE_REFS`: In push mode, parses comma-separated image refs and rewrites the exact gateway, sandbox, and pki-job image references (matching on path component `/server:`, `/sandbox:`, `/pki-job:`).
+- `PUSH_IMAGE_REFS`: In push mode, parses comma-separated image refs and rewrites the exact gateway, sandbox, and pki-job image references (matching on path component `/gateway:`, `/sandbox:`, `/pki-job:`).
 - `IMAGE_TAG`: Replaces `:latest` tags with the specified tag on gateway, sandbox, and pki-job images. Handles both quoted and unquoted `tag: latest` formats.
 - `IMAGE_PULL_POLICY`: Replaces `pullPolicy: Always` with the specified policy (e.g., `IfNotPresent`).
 - `SSH_GATEWAY_HOST` / `SSH_GATEWAY_PORT`: Replaces `__SSH_GATEWAY_HOST__` and `__SSH_GATEWAY_PORT__` placeholders.

deploy/docker/Dockerfile.cluster

@@ -12,7 +12,7 @@
 # - HelmChart CR for auto-deploying OpenShell
 # - Custom entrypoint for DNS configuration in Docker environments
 #
-# Component images (openshell/server, openshell/sandbox) are
+# Component images (openshell/gateway, openshell/sandbox) are
 # pulled at runtime from the distribution registry rather than bundled as tarballs.
 # Registry credentials are generated by the entrypoint script at container start.
 #

deploy/docker/Dockerfile.server deploy/docker/Dockerfile.gatewaydeploy/docker/Dockerfile.server renamed to deploy/docker/Dockerfile.gateway

@@ -3,7 +3,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-# OpenShell Server Docker image
+# OpenShell Gateway Docker image
 # Multi-stage build with cross-compilation support for multi-arch
 
 # Stage 1: Rust builder (runs on build platform, cross-compiles for target)
@@ -52,9 +52,9 @@ COPY proto/ proto/
 # sccache uses memcached in CI (SCCACHE_MEMCACHED_ENDPOINT) or the local
 # disk cache mount for local dev builds. The cargo-target mount gives cargo
 # a persistent target/ dir for true incremental rebuilds on source changes.
-RUN --mount=type=cache,id=cargo-registry-server-${TARGETARCH},sharing=locked,target=/usr/local/cargo/registry \
-    --mount=type=cache,id=cargo-target-server-${TARGETARCH}-${CARGO_TARGET_CACHE_SCOPE},sharing=locked,target=/build/target \
-    --mount=type=cache,id=sccache-server-${TARGETARCH},sharing=locked,target=/tmp/sccache \
+RUN --mount=type=cache,id=cargo-registry-gateway-${TARGETARCH},sharing=locked,target=/usr/local/cargo/registry \
+    --mount=type=cache,id=cargo-target-gateway-${TARGETARCH}-${CARGO_TARGET_CACHE_SCOPE},sharing=locked,target=/build/target \
+    --mount=type=cache,id=sccache-gateway-${TARGETARCH},sharing=locked,target=/tmp/sccache \
     . cross-build.sh && cargo_cross_build --release -p navigator-server 2>/dev/null || true
 
 # Copy actual source code
@@ -68,9 +68,9 @@ RUN touch crates/navigator-server/src/main.rs \
     proto/*.proto
 
 # Build the actual application
-RUN --mount=type=cache,id=cargo-registry-server-${TARGETARCH},sharing=locked,target=/usr/local/cargo/registry \
-    --mount=type=cache,id=cargo-target-server-${TARGETARCH}-${CARGO_TARGET_CACHE_SCOPE},sharing=locked,target=/build/target \
-    --mount=type=cache,id=sccache-server-${TARGETARCH},sharing=locked,target=/tmp/sccache \
+RUN --mount=type=cache,id=cargo-registry-gateway-${TARGETARCH},sharing=locked,target=/usr/local/cargo/registry \
+    --mount=type=cache,id=cargo-target-gateway-${TARGETARCH}-${CARGO_TARGET_CACHE_SCOPE},sharing=locked,target=/build/target \
+    --mount=type=cache,id=sccache-gateway-${TARGETARCH},sharing=locked,target=/tmp/sccache \
     . cross-build.sh && \
     if [ -n "${OPENSHELL_CARGO_VERSION:-}" ]; then \
       sed -i -E '/^\[workspace\.package\]/,/^\[/{s/^version[[:space:]]*=[[:space:]]*".*"/version = "'"${OPENSHELL_CARGO_VERSION}"'"/}' Cargo.toml; \

deploy/docker/cluster-entrypoint.sh

@@ -322,7 +322,7 @@ HELMCHART="/var/lib/rancher/k3s/server/manifests/openshell-helmchart.yaml"
 if [ -n "${IMAGE_REPO_BASE:-}" ] && [ -f "$HELMCHART" ]; then
     target_tag="${IMAGE_TAG:-latest}"
     echo "Setting image repository base: ${IMAGE_REPO_BASE}"
-    sed -i -E "s|repository:[[:space:]]*[^[:space:]]+|repository: ${IMAGE_REPO_BASE}/server|" "$HELMCHART"
+    sed -i -E "s|repository:[[:space:]]*[^[:space:]]+|repository: ${IMAGE_REPO_BASE}/gateway|" "$HELMCHART"
     sed -i -E "s|sandboxImage:[[:space:]]*[^[:space:]]+|sandboxImage: ${IMAGE_REPO_BASE}/sandbox:${target_tag}|" "$HELMCHART"
 fi
 
@@ -335,7 +335,7 @@ if [ -n "${PUSH_IMAGE_REFS:-}" ] && [ -f "$HELMCHART" ]; then
     IFS=','
     for ref in $PUSH_IMAGE_REFS; do
         case "$ref" in
-            */server:*) server_image="$ref" ;;
+            */gateway:*) server_image="$ref" ;;
             */sandbox:*) sandbox_image="$ref" ;;
         esac
     done