docs: clarify configurable hardened Agent listener

Describe 8080 as the forthcoming default rather than an unconditional requirement, matching the final AGENT_PORT contract.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

README.docker.md

@@ -1,3 +1,34 @@
 # Self-hosted with Docker Compose
 
 ....
+
+## Agent HTTP port migration
+
+This Docker Compose guide is not yet complete. For Agent installation and
+configuration, see the [Agent guide](https://learn.uug.ai/docs/agent/) and
+[Agent README](https://github.com/kerberos-io/agent#readme).
+
+Docker mappings use `HOST_PORT:CONTAINER_PORT`. Published Agent releases still
+listen on container port `80`. With `AGENT_IMAGE` set to a verified tag or digest
+for one of those releases, expose the UI at `http://localhost:8080` with:
+
+```bash
+docker run --name kerberos-agent -p 8080:80 \
+  "${AGENT_IMAGE:?Set AGENT_IMAGE to a verified port-80 Agent image}"
+```
+
+The forthcoming hardened Agent image instead listens on container port `8080`.
+Only after that image is available, set `AGENT_IMAGE` to its verified tag or
+digest and use:
+
+```bash
+docker run --name kerberos-agent -p 8080:8080 \
+  "${AGENT_IMAGE:?Set AGENT_IMAGE to a verified port-8080 Agent image}"
+```
+
+These are alternative commands for a new container, not an in-place upgrade.
+Preserve your existing environment variables, mounts and recordings when
+recreating a container. In Compose, the equivalent `ports` entry changes from
+`"8080:80"` to `"8080:8080"` together with the image. Your chosen host port and
+browser URL need not change. Do not apply the new mapping to legacy images,
+or assume `kerberos/agent:latest` already includes the hardening update.

README.k8s.md

@@ -370,6 +370,11 @@ before switching an existing installation.
 
 ### Create an Agent
 
+Check [Agent HTTP port compatibility](./README.md#agent-http-port-compatibility)
+before selecting an image: published releases use internal port `80`, while
+the forthcoming hardened image defaults to `8080`. Service targets must match
+the listener selected with `AGENT_PORT`.
+
 After deploying the Vault and configuring the necessary services for storage, database, and integration, you can proceed to deploy the Agent with the appropriate configuration. Review the `kerberos-agent-deployment.yaml` file and adjust the relevant settings, such as the RTSP URL, to ensure proper functionality. As mentioned below note that you can opt for the [Factory](https://github.com/kerberos-io/factory/tree/master/kubernetes) which gives you a UI to manage the creation of Agents. **_(Please note if you generated new the keys in the previous Vault account creation, you need to update those in the Agent deployment)_**
 
 ```bash

README.kustomize.md

@@ -14,6 +14,10 @@ In this tutorial, we will guide you through the installation of the complete sta
 
 ## Install Microk8s
 
+Before deploying, check [Agent HTTP port compatibility](./README.md#agent-http-port-compatibility).
+The Agent base keeps port `80` for currently published images; migrating to the
+forthcoming hardened image requires coordinated image and port updates.
+
 To install MicroK8s on your system, follow these steps. First, ensure that you have `snapd` installed on your machine. If not, you can install it using the following command:
 
 To install MicroK8s on your system, follow these steps.

README.md

@@ -43,6 +43,31 @@ Failed deployment jobs collect pod events and bounded logs for diagnosis.
 We harden our container images and check our solutions for known CVEs. See the
 [Secure repository](https://github.com/uug-ai/secure) for our security work.
 
+### Agent HTTP port compatibility
+
+The forthcoming Agent hardening update moves its internal HTTP listener from
+`80` to `8080`. Published Agent releases still use `80`; do not change a running
+deployment's target port until its selected image supports `8080`. Pin a verified
+image tag or digest rather than assuming `kerberos/agent:latest` has this change.
+See the [Docker port mappings](./README.docker.md#agent-http-port-migration).
+
+For Kubernetes, update the image and `containerPort` together in
+[`base/agent/kerberos-agent-deployment.yaml`](./base/agent/kerberos-agent-deployment.yaml).
+If enabling its commented Service example, change `targetPort` to `8080` as
+well; the external Service `port: 80` can stay unchanged. That example's
+`selector.app` must also match the Deployment's `app: agent1` label.
+There are no Agent HTTP health probes in this base manifest; any probes or
+direct pod port-forwards added locally must target the selected image's listener.
+The Vault URL ending in `:80/api` is a separate Service and must not be changed.
+
+Factory also selects `kerberos/agent:latest` through `KERBEROS_AGENT_IMAGE`.
+Before choosing a hardened Agent image, verify that Factory's generated Agent
+Deployments, Services and probes support port `8080`; changing the image setting
+alone does not establish compatibility. See the
+[Factory Agent-image guidance](./base/factory/README.md#agent-image-compatibility).
+These deployment defaults remain unchanged until a compatible image and
+controller are verified.
+
 ## Architecture
 
 As previously indicated, several integral components, including object storage, databases, and message brokers, are deployed and configured to support the ecosystem. The architecture diagrams below provide a visual representation of these components and how they interact in self-hosted and managed cloud deployments.

README.microk8s.md

@@ -353,6 +353,11 @@ credentials and provider name instead.
 
 ### Create an Agent
 
+Check [Agent HTTP port compatibility](./README.md#agent-http-port-compatibility)
+before selecting an image: published releases use internal port `80`, while
+the forthcoming hardened image defaults to `8080`. Service targets must match
+the listener selected with `AGENT_PORT`.
+
 After deploying the Vault and configuring the necessary services for storage, database, and integration, you can proceed to deploy the Agent with the appropriate configuration. Review the `kerberos-agent-deployment.yaml` file and adjust the relevant settings, such as the RTSP URL, to ensure proper functionality. Please note that you can allow opt for the [Factory](https://github.com/kerberos-io/factory/tree/master/kubernetes) which gives you a UI to manage the creation of Agents. Also please note if you generated new the keys in the previous Vault account creation, you need to update those in the Agent deployment.
 
 ```bash

base/factory/README.md

@@ -53,6 +53,17 @@ Other relevant environment variables:
 | `PORT` | `8080` | Unprivileged HTTP listener used by the hardened image. |
 | `K8S_PROXY` | `http://localhost:8080` | Internal proxy address Factory calls for the `/kubernetes` API. |
 
+### Agent image compatibility
+
+Factory's own port `8080` does not determine the HTTP port of the Agents it
+creates. Published Agent releases still use port `80`; the forthcoming hardened
+Agent image moves to `8080`. Before changing `KERBEROS_AGENT_IMAGE`, pin a
+verified image tag or digest and confirm that the Factory version in use
+generates compatible Agent container ports, Service target ports and any HTTP
+probes. Existing Agent resources may need a coordinated update as well.
+Do not assume changing this environment variable or pulling `latest` migrates
+those resources. See the [Agent port migration guidance](../../README.md#agent-http-port-compatibility).
+
 ## Hardened runtime and upgrades
 
 The image runs as UID/GID `65532:65532`, with a read-only root filesystem,