docs: document the upstream s6 runtime, security/SCC tradeoff, provider config

- README: correct the now-false claims (read-only rootfs, uv-sync init container,
  tini PID 1). Describe the FROM-upstream s6 image (gateway + OpenAI API server +
  dashboard + Playwright browser + deps), the root-start→drop-to-1000 security
  posture and its OpenShift SCC implication, the /opt/data state path, /health on
  8443, and the spec.config.raw + spec.env provider-config pattern.
- docs/runtime.md (new): "Agent runtime" page covering the image, how the operator
  runs it, the security/SCC tradeoff, and provider configuration. Linked from
  docs/index.md and the mkdocs Operations nav.
- docs/api-reference-generated.md: regenerated for the ShareProcessNamespace
  default/doc change (keeps the API Docs Sync check green).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: stubbi

README.md

@@ -35,7 +35,8 @@ helm install hermes-operator \
   oci://ghcr.io/paperclipinc/charts/hermes-operator \
   -n hermes-operator --create-namespace
 
-# 2. Apply a minimal instance.
+# 2. Apply a minimal instance. The agent runs the upstream NousResearch/hermes-agent
+#    s6 image (gateway + OpenAI-compatible API server), with /health on port 8443.
 kubectl apply -n agents -f - <<'YAML'
 apiVersion: hermes.agent/v1
 kind: HermesInstance
@@ -44,7 +45,18 @@ metadata:
 spec:
   image:
     repository: ghcr.io/paperclipinc/hermes-agent
-    tag: "v2026.5.29.2"
+    tag: "v0.16.0"
+  # Point the gateway at an LLM provider and inject the key via spec.env.
+  config:
+    raw:
+      model: gpt-4o-mini
+      base_url: https://api.openai.com/v1
+  env:
+    - name: OPENAI_API_KEY
+      valueFrom:
+        secretKeyRef:
+          name: hermes-llm
+          key: apiKey
   storage:
     persistence:
       enabled: true
@@ -54,9 +66,16 @@ YAML
 # 3. Watch it converge.
 kubectl get hi -n agents -w
 # NAME        READY   PHASE   IMAGE                                AGE
-# my-hermes   True    Ready   ghcr.io/paperclipinc/hermes-agent:v2026.5.29.2    30s
+# my-hermes   True    Ready   ghcr.io/paperclipinc/hermes-agent:v0.16.0    30s
 ```
 
+If you omit `spec.config.raw.model`, the operator injects a non-routable placeholder
+so the gateway and API server still come up (and `/health` passes) without making
+live LLM calls; inference then fails clearly until a real provider is set. Each
+instance also gets an operator-managed random `api_server_key` (in its
+`<name>-gateway-tokens` Secret) that authenticates the OpenAI-compatible
+`/v1/...` API; `/health` is unauthenticated. See [Agent runtime](docs/runtime.md).
+
 For more involved scenarios, see [`examples/`](examples/).
 
 ## Architecture
@@ -87,7 +106,7 @@ flowchart LR
     STS[StatefulSet]
     Svc[Service]
     NetPol[NetworkPolicy default-deny]
-    PVC[PVC ~/.hermes]
+    PVC[PVC /opt/data]
     Honcho[Honcho Deploy<br/>profile store]
     CronJob[Backup CronJob]
   end
@@ -132,7 +151,7 @@ fields only: explicit values on the instance always win.
 | **Adaptive** | `HermesSelfConfig` for audited agent-initiated mutations | SSA under field manager `hermes.agent/selfconfig`. Policy-gated by `spec.selfConfigure.protectedKeys`. |
 | **Adaptive** | OCI-registry-driven auto-update | Channel-pinned polling, pre-update backup, probe-failure rollback. |
 | **Secure** | Default-deny NetworkPolicy + per-gateway allow rules | Derived from `spec.gateways` and `spec.networking.egress`. |
-| **Secure** | Read-only root filesystem | Writable `emptyDir`s for `/tmp` and `~/.config` subPaths. |
+| **Secure** | Hardened container security context | The upstream s6 runtime starts as root so `/init` (PID 1) can remap the in-image user to uid/gid 1000 and chown `/opt/data`, then every service drops to uid 1000 via `s6-setuidgid`. `allowPrivilegeEscalation=false`, `fsGroup=1000`, and seccomp `RuntimeDefault` remain; `runAsNonRoot`/read-only rootfs/drop-ALL-caps are not set (s6 needs `CHOWN`/`SETUID`/`SETGID`/`DAC_OVERRIDE`/`FOWNER` and a writable `/run`). Requires an SCC that permits a root-start container (e.g. `anyuid`); incompatible with OpenShift `restricted`/`restricted-v2`. See [Agent runtime](docs/runtime.md). |
 | **Secure** | Optional Tailscale Serve sidecar | Per-instance MagicDNS hostname + Tailscale TLS cert, no LoadBalancer/Ingress. See [Tailscale Serve](#tailscale-serve). |
 | **Secure** | Per-CRD validating + defaulting webhooks | Plus warnings on unknown config keys and unresolvable gateway tokens. |
 | **Secure** | RBAC aggregation labels | `kubectl auth can-i create hermesinstances --as=jane` works out of the box. |
@@ -141,13 +160,13 @@ fields only: explicit values on the instance always win.
 | **Observable** | [Grafana dashboard](docs/grafana/) | Ships as JSON. Variables: `namespace`, `instance`. |
 | **Observable** | Exhaustive [condition catalogue](docs/conditions.md) | Every condition × every reason code, documented and stable. |
 | **Multi-platform** | Telegram / Discord / Slack / WhatsApp / Signal gateways | First-class `spec.gateways.*` sections, secret-rotation-friendly. |
-| **Python runtime** | `uv`-installable agent runtime | Init container runs `uv sync` against a lockfile bundled in the agent image. |
-| **Python runtime** | FFmpeg + ripgrep available out of the box | Hard dependencies of hermes-agent. |
+| **Upstream runtime** | Ships the supported NousResearch/hermes-agent s6 image | The published `ghcr.io/paperclipinc/hermes-agent` is built `FROM` the upstream image (pinned by digest). It bundles the gateway, dashboard, OpenAI-compatible API server, a Playwright/Chromium browser, node, ffmpeg, and all Python deps. No init-container venv build — the old `uv sync` / `init-apt`/`init-uv`/`init-pip` chain is gone. See [Agent runtime](docs/runtime.md). |
+| **Upstream runtime** | FFmpeg, ripgrep, browser, node available out of the box | Bundled in the upstream hermes-agent image. |
 | **Scalable** | Optional HPA via `spec.availability.hpa` | StatefulSet retained for identity through restarts. |
 | **Scalable** | Optional `topologySpreadConstraints` | Sane defaults plus `spec.availability.topologySpreadConstraints` override. |
 | **Resilient** | PodDisruptionBudget auto-managed when `replicas > 1` | |
 | **Resilient** | Finalizer-driven backup-on-delete | `r.Patch` (JSON patch) for finalizer mutations, never `r.Update`. |
-| **Resilient** | Zombie-process reaper | `tini` as PID 1; `shareProcessNamespace: false` by default. |
+| **Resilient** | Zombie-process reaper | s6-overlay `/init` as PID 1 reaps zombies; `shareProcessNamespace: false` by default (its `/init` must be PID 1). |
 | **Backup / Restore** | S3-compatible backups | Scheduled, on-delete, pre-update. `tar.zst` snapshots + `meta.json`. |
 | **Backup / Restore** | Declarative one-shot restore | `spec.restoreFrom` is immutable once applied. |
 | **Migration** | One-shot OpenClaw → Hermes migration | From sibling `OpenClawInstance` or S3 backup. Uses hermes-agent's importer. |

docs-site/mkdocs.yml

@@ -89,6 +89,7 @@ nav:
       - Generated API Reference: api-reference-generated.md
       - Conditions: conditions.md
   - Operations:
+      - Agent Runtime: runtime.md
       - Backup and Restore: backup-restore.md
       - Backup Format: backup-format.md
       - Auto-Update: autoupdate.md

docs/api-reference-generated.md

@@ -407,7 +407,7 @@ _Appears in:_
 | `availability` _[AvailabilitySpec](#availabilityspec)_ | Availability sets PDB, HPA, and topology-spread constraints. |  | Optional: \{\} <br /> |
 | `probes` _[ProbesSpec](#probesspec)_ | Probes lets users override the built-in liveness/readiness/startup probes. |  | Optional: \{\} <br /> |
 | `scheduling` _[SchedulingSpec](#schedulingspec)_ | Scheduling targets the agent pod at specific nodes. |  | Optional: \{\} <br /> |
-| `shareProcessNamespace` _boolean_ | ShareProcessNamespace enables PID namespace sharing between all containers<br />in the pod. When true (the default), the infrastructure (pause) container<br />becomes PID 1 and reaps zombie processes, preventing accumulation of defunct<br />helper processes (git, plugins, shells) spawned under the agent entrypoint<br />when it does not call waitpid().<br />Security note: enabling this lets every container in the pod see and signal<br />every other container's processes. A compromised sidecar could send signals<br />to the agent and vice versa. Set to false to keep per-container PID isolation;<br />you are then responsible for reaping zombies (e.g. by baking tini or dumb-init<br />into the image). | true | Optional: \{\} <br /> |
+| `shareProcessNamespace` _boolean_ | ShareProcessNamespace enables PID namespace sharing between all containers<br />in the pod. Defaults to false: the upstream hermes-agent image runs under<br />s6-overlay, whose /init must be PID 1 (s6-overlay-suexec aborts otherwise),<br />and s6 already reaps zombies non-blocking on SIGCHLD — so sharing the process<br />namespace (which makes the pause container PID 1) is both incompatible and<br />unnecessary.<br />Security note: enabling this lets every container in the pod see and signal<br />every other container's processes. A compromised sidecar could send signals<br />to the agent and vice versa. Leave false to keep per-container PID isolation. | false | Optional: \{\} <br /> |
 | `initContainers` _[Container](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#container-v1-core) array_ | InitContainers is a user-supplied list of init containers appended after<br />any operator-managed init containers (e.g. runtime-init from Plan 3). |  | Optional: \{\} <br /> |
 | `sidecars` _[Container](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#container-v1-core) array_ | Sidecars is a user-supplied list of sidecars appended after operator-managed<br />sidecars (e.g. ollama / web-terminal / tailscale from Plan 3). |  | Optional: \{\} <br /> |
 | `extraVolumes` _[Volume](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#volume-v1-core) array_ | ExtraVolumes is a user-supplied list of additional pod volumes. |  | Optional: \{\} <br /> |

docs/index.md

@@ -12,6 +12,7 @@ This site is the rendered documentation for the operator. The source of truth fo
 
 ## Operations
 
+- [Agent runtime](runtime.md) explains the upstream s6 image, how the operator runs it, the `/opt/data` state path, the security/SCC tradeoff, and LLM provider configuration.
 - [Conditions](conditions.md) documents the status conditions the operator sets.
 - [Backup and restore](backup-restore.md) and the [backup format](backup-format.md) cover data protection.
 - [Auto-update](autoupdate.md) describes registry polling and rollback.

docs/runtime.md

@@ -0,0 +1,94 @@
+# Agent runtime
+
+The operator runs the agent on the **upstream NousResearch/hermes-agent
+container image**. The published `ghcr.io/paperclipinc/hermes-agent` image is
+built `FROM` that upstream image (pinned by digest) with only operator metadata
+layered on top — there is no hand-rolled venv build any more.
+
+## What the image bundles
+
+The upstream image is an **s6-overlay** runtime. A single image ships:
+
+- the **gateway** (the long-lived agent daemon),
+- a **dashboard**,
+- the **OpenAI-compatible API server**,
+- a **Playwright/Chromium browser**,
+- node, ffmpeg, ripgrep, and every Python dependency.
+
+Because the runtime lives entirely in the image, the old init-container chain
+(`init-apt` / `init-uv` / `init-pip` running `uv sync` against a lockfile onto
+the PVC) is **gone**. Only mutable state lives on the volume.
+
+## How the operator runs it
+
+- **Args:** the container runs `["gateway", "run"]` — the foreground gateway
+  daemon.
+- **API server:** enabled via env: `API_SERVER_ENABLED=true`,
+  `API_SERVER_HOST=0.0.0.0`, `API_SERVER_PORT=8443`, and `API_SERVER_KEY` (see
+  below). This serves the OpenAI-compatible `/v1/...` endpoint plus `/health` on
+  the gateway port.
+- **Probes:** both **readiness and liveness** are `HTTPGet /health` on the
+  gateway port (8443) — not a TCP socket.
+
+## State and `HERMES_HOME`
+
+Persistent state lives at **`/opt/data`**, the PVC mount, and `HERMES_HOME` is
+set to `/opt/data`. (The previous runtime used `/home/hermes/.hermes`.) The
+rendered `config.yaml` is mounted read-only at `/opt/data/config.yaml`.
+
+## Security posture and the SCC tradeoff
+
+The s6 runtime changes the pod's security posture. `/init` **must be PID 1 and
+start as root** so the s6 stage2 hook can remap the in-image `hermes` user to
+`HERMES_UID`/`HERMES_GID` (1000) and chown `/opt/data`. After that, every
+supervised service drops privileges via `s6-setuidgid`, so the actual workload
+runs as uid 1000.
+
+Consequences for the pod:
+
+- **No** `runAsNonRoot`/`runAsUser` (the container starts as root by design).
+- **No** read-only root filesystem (s6 needs a writable `/run` and `/etc` for
+  the supervision tree).
+- **No** drop-ALL capabilities — s6 needs `CHOWN`, `SETUID`, `SETGID`,
+  `DAC_OVERRIDE`, and `FOWNER` to remap the user and chown the volume.
+- `allowPrivilegeEscalation=false`, `fsGroup=1000`, and seccomp
+  `RuntimeDefault` are retained.
+- `shareProcessNamespace` defaults to **false**: s6 reaps zombies itself, and
+  its `/init` must be PID 1 (the pause container becoming PID 1 would break it).
+
+This is a deliberate tradeoff to adopt the supported upstream runtime. It means
+the workload is **incompatible with OpenShift's `restricted`/`restricted-v2`
+SCC**, and requires an SCC that permits a root-start container (for example
+`anyuid`) — even though the workload internally drops to uid 1000.
+
+## Configuring an LLM provider
+
+Set the model and endpoint via `spec.config.raw`, and inject the API key via
+`spec.env`:
+
+```yaml
+spec:
+  config:
+    raw:
+      model: gpt-4o-mini
+      base_url: https://api.openai.com/v1
+  env:
+    - name: OPENAI_API_KEY
+      valueFrom:
+        secretKeyRef:
+          name: hermes-llm
+          key: apiKey
+```
+
+When no `model` is configured, the operator injects a non-routable placeholder
+provider so the gateway and API server still come up and `/health` passes,
+without making any live LLM calls. Inference then fails clearly until a real
+provider is configured.
+
+## API server authentication
+
+Each instance gets an operator-managed random `api_server_key` in its
+`<name>-gateway-tokens` Secret. It is wired into the container as
+`API_SERVER_KEY` and authenticates the OpenAI-compatible `/v1/...` API. The
+`/health` endpoint is **unauthenticated**, which is what the readiness and
+liveness probes hit.