Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs: complete the configuration and reference docs
Jose Gabriel Ramirez Encinascb1f2ca6085a
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 123ffc8ed..7e8cce55e 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -18,10 +18,10 @@ NetworkPolicy layers, data flows — read:Two controllers turn Custom Resources into running workloads. Almost nothing inthe platform is deployed by hand:-| Controller | Watches | Creates |-| ------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| **[host-context-controller](host-context-controller/)** (HCC) | `Host`, `Context`, `McpServer`, `SharedFileSystem`, `GlobalFileSystem` | `mcp-host` pods, MCP server pods (+ `stdio-bridge` sidecar, `nginx-egress-proxy` for remote servers), `workspace-files-controller`, `gfs-controller`, and the Context/MCP NetworkPolicies |-| **[workflow-recipes](workflow-recipes/)** (WRC) | `WorkflowRecipe`, `WorkflowRecipePolicy` | sandbox workloads (Deployments/StatefulSets/Jobs/CronJobs), per-recipe `webhook-gateway`, derived `McpServer` CRDs, and the recipe runtime NetworkPolicies |+| Controller | Watches | Creates |+| ------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| **[host-context-controller](host-context-controller/)** (HCC) | `Host`, `Context`, `McpServer`, `SharedFileSystem`, `GlobalFileSystem`, `LlmHook` | `mcp-host` pods, MCP server pods (+ `stdio-bridge` sidecar, `nginx-egress-proxy` for remote servers), `workspace-files-controller`, `gfs-controller`, guardrail hook pods in `llm-hooks` (image-target `LlmHook`s only), and the Context/MCP NetworkPolicies |+| **[workflow-recipes](workflow-recipes/)** (WRC) | `WorkflowRecipe`, `WorkflowRecipePolicy` | sandbox workloads (Deployments/StatefulSets/Jobs/CronJobs), per-recipe `webhook-gateway`, derived `McpServer` CRDs, and the recipe runtime NetworkPolicies |Everything else — the UIs, the APIs, the channel readers, the proxies — isstatic infrastructure in [`deploy/`](deploy/).@@ -34,12 +34,14 @@ NetworkPolicy owned by whichever component is responsible for that selector.### Control plane — `control-plane`-| Service | Role |-| --------------------------------------------------- | --------------------------------------------------------------------- |-| [host-context-controller](host-context-controller/) | Reconciles Host / Context / McpServer / SFS / GFS; Discovery REST API |-| [workflow-recipes](workflow-recipes/) | The WorkflowRecipe controller (WRC) — a separate Deployment and image |-| [control-api](control-api/) | CRD lifecycle, resource CRUD, profile mapping |-| [control-ui](control-ui/) | Platform management UI |+| Service | Role |+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |+| [host-context-controller](host-context-controller/) | Reconciles Host / Context / McpServer / SFS / GFS / LlmHook; Discovery REST API |+| [workflow-recipes](workflow-recipes/) | The WorkflowRecipe controller (WRC) — a separate Deployment and image |+| [control-api](control-api/) | CRD lifecycle, resource CRUD, profile mapping |+| [control-ui](control-ui/) | Platform management UI |+| [codex-llm-proxy](codex-llm-proxy/) | Streams `codex-subscription` model calls to ChatGPT; redeems single-use tickets from control-api. Off by default (`CODEX_LLM_PROXY_EXECUTION_ENABLED`) |+| [grok-llm-proxy](grok-llm-proxy/) | Streams `grok-subscription` model calls to Grok; redeems single-use tickets from control-api. Off by default (`GROK_LLM_PROXY_EXECUTION_ENABLED`) |### Identity & profiles — `profiles`@@ -71,6 +73,14 @@ Workloads here are created by the WRC from `WorkflowRecipe` resources, not bystatic manifests. `sandbox-ui` holds untrusted recipe-supplied UIs, reachableonly through `rpc-proxy`.+### Guardrail hooks — `llm-hooks` (deny-all)++Holds the pods HCC deploys for image-target [`LlmHook`](docs/crds/llmhook.md)+resources: guardrail services that `mcp-host` calls around LLM and tool calls.+Hooks with the same image and pod settings share one pod. Service and remote+targets deploy nothing here. See+[Configure guardrails](docs/how-to/configure-guardrails.md).+### FilesBoth are brokered HTTP file APIs: nothing else mounts the underlying volume, so@@ -83,19 +93,38 @@ every read and write is an authorized, audited API call rather than a raw mount.### Edge — `rpc-proxy`, `webhook-ingress`, `ingress` (all deny-all)-| Service | Role |-| ----------------------------------- | ------------------------------------------------------------------------------------ |-| [rpc-proxy](rpc-proxy/) | Secure RPC path for the Desktop App → MCP servers / agent (RS256 JWT, scoped tokens) |-| [webhook-proxy](webhook-proxy/) | Cluster-shared public webhook router; validates and streams, holds no secrets |-| [webhook-gateway](webhook-gateway/) | Per-recipe signature verifier; deployed by WRC, sits behind `webhook-proxy` |-| cloudflared | Public tunnel ingress |+| Service | Role |+| ----------------------------------- | -------------------------------------------------------------------------------------------------- |+| [rpc-proxy](rpc-proxy/) | Secure RPC path for the Desktop App → MCP servers / agent (RS256 JWT, scoped tokens) |+| [webhook-proxy](webhook-proxy/) | Cluster-shared public webhook router; validates and streams, holds no secrets |+| [webhook-gateway](webhook-gateway/) | Per-recipe signature verifier; deployed by WRC into `sandbox-recipes`, sits behind `webhook-proxy` |+| cloudflared | Public tunnel ingress |### Clients & libraries-| Component | Role |-| --------------------------- | -------------------------------------------------------------------------------------------------------------- |-| [desktop-app](desktop-app/) | Electron + React client; authenticates via `external-rest-api`, calls `rpc-proxy` |-| [packages/](packages/) | Shared libraries: `image-policy`, `workflow-recipe-capability-policy`, `workflow-runtime-core`, `workflow-sdk` |+| Component | Role |+| --------------------------- | --------------------------------------------------------------------------------- |+| [desktop-app](desktop-app/) | Electron + React client; authenticates via `external-rest-api`, calls `rpc-proxy` |+| [packages/](packages/) | Shared libraries, listed below |++Shared packages under [`packages/`](packages/) (npm name `@clerum/<dir>`):++| Package | Purpose |+| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |+| [codex-catalog-projection](packages/codex-catalog-projection/) | Codex model allowlist snapshot and execution projection, used by HCC, mcp-host and workflow-recipes |+| [desktop-app-links](packages/desktop-app-links/) | `evenfire://app/...` link contract shared by the Desktop App and Profile UI |+| [display-field](packages/display-field/) | Validation for free-text display fields (control/bidi characters, length) |+| [frontend-components](packages/frontend-components/) | React table, record-list and edit-dialog components shared by Control UI and Profile UI |+| [gfs-interaction-policy](packages/gfs-interaction-policy/) | Browser-safe GFS upload naming/collision/retry policy, `FileReference` v1, file classifier |+| [grok-provider-attempt-contract](packages/grok-provider-attempt-contract/) | Grok subscription wire contract: limits, origins, request hashing, ticket and receipt types |+| [image-policy](packages/image-policy/) | Container image reference policy for plugins and workflow coordinators |+| [jwt-key-policy](packages/jwt-key-policy/) | RSA JWT key identity policy and local development key storage |+| [llm-provider-attempt-contract](packages/llm-provider-attempt-contract/) | Codex subscription wire contract: limits, request hashing, ticket and receipt types |+| [llm-providers](packages/llm-providers/) | Canonical LLM provider ids, credential slots and display metadata |+| [network-policy-core](packages/network-policy-core/) | Sliding-window egress IP accumulation for FQDN NetworkPolicies |+| [workflow-recipe-capability-policy](packages/workflow-recipe-capability-policy/) | Linux capability policy for WorkflowRecipe and McpServer workloads |+| [workflow-runtime-core](packages/workflow-runtime-core/) | Internal workflow runtime protocol primitives |+| [workflow-sdk](packages/workflow-sdk/) | TypeScript SDK for workflow coordinator pods (also built as the `clerum-workflow-base` image) |Product-level treatment of `control-ui`, `desktop-app`, and `profile-ui` as theplatform's three human surfaces: [docs/surfaces/README.md](docs/surfaces/README.md).diff --git a/README.md b/README.mdindex c2b0cc273..d6c7d379d 100644--- a/README.md+++ b/README.md@@ -264,6 +264,8 @@ Contributor loop: [CONTRIBUTING.md](CONTRIBUTING.md).| [webhook-gateway](webhook-gateway/README.md) | Per-recipe webhook signature verifier || [webhook-proxy](webhook-proxy/README.md) | Stateless public webhook router || [workflow-approval-request-reader](workflow-approval-request-reader/README.md) | Inbound Telegram/Slack approval callbacks |+| [codex-llm-proxy](codex-llm-proxy/README.md) | ChatGPT/Codex subscription broker (off by default) |+| [grok-llm-proxy](grok-llm-proxy/README.md) | Grok subscription broker (off by default) |Ops & platform directories:diff --git a/codex-llm-proxy/README.md b/codex-llm-proxy/README.mdnew file mode 100644index 000000000..746e3dbb7--- /dev/null+++ b/codex-llm-proxy/README.md@@ -0,0 +1,135 @@+# Codex LLM Proxy++Internal broker for the `codex-subscription` provider: ChatGPT/Codex+subscription sign-ins used as an LLM. It streams model calls from an agent to+the ChatGPT Codex endpoint. The OAuth tokens stay in control-api's database;+the proxy receives an access token for a single operation and does not store+it.++Off by default: `CODEX_LLM_PROXY_EXECUTION_ENABLED` is `"false"` in+`deploy/base`. To turn the feature on, follow+[Connect an LLM subscription](../docs/how-to/connect-llm-subscription.md).++## Where it runs++- Namespace `control-plane`, one replica.+- Manifest: [`deploy/base/control-plane/codex-llm-proxy.yaml`](../deploy/base/control-plane/codex-llm-proxy.yaml)+ (ServiceAccount without a token, ConfigMap `codex-llm-proxy-config`,+ Deployment, ClusterIP Service).+- Image: `clerum/codex-llm-proxy` (built from this directory, listed in+ [`deploy/images.json`](../deploy/images.json)).++## How it fits++1. `mcp-host` (or a recipe's workflow MCP host) asks control-api to authorize+ the attempt: `POST /api/v1/mcp-host/llm/provider-attempts/authorize`.+ control-api returns a short-lived, single-use execution ticket bound to the+ Host, model and request hash.+2. The caller sends the request and the ticket to the proxy, with a platform+ JWT as the bearer token.+3. The proxy verifies both, then redeems the ticket with control-api+ (`POST /internal/llm/provider-attempts/redeem`) through+ `control-api-rpc-gateway`. The redeem returns the access token for this+ one operation.+4. The proxy calls the ChatGPT Codex endpoint and streams the answer back as+ SSE. The model stream never passes through control-api.+5. When the stream ends, the proxy reports the outcome and token usage+ (`POST /internal/llm/provider-attempts/finalize`).++control-api also calls the admin port to list a connection's model catalog+and to test a connection (`control-api/src/services/codexSubscriptionCatalog.ts`).++The wire format, limits and error codes are frozen in the+[Codex subscription transport contract](../docs/architecture/codex-subscription-transport-contract.md).+The shared types and limits live in+[`packages/llm-provider-attempt-contract`](../packages/llm-provider-attempt-contract/).++## Endpoints++The proxy runs three HTTP servers.++| Port | Name | Route | Caller | Auth |+| ---- | ------- | --------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |+| 8080 | runtime | `POST /internal/runtime/v1/codex/completions` | mcp-host, workflow MCP host | RS256 platform JWT (`scope` `workflow:approval:request`, `workflowControlScopes` has `llm:codex:execute`) plus execution ticket in the body |+| 8081 | admin | `POST /internal/admin/v1/codex/models` | control-api | `codex-admin-permit` JWT for `catalog_list` |+| 8081 | admin | `POST /internal/admin/v1/codex/test` | control-api | `codex-admin-permit` JWT for `connection_test` |+| 9090 | metrics | `GET /healthz`, `GET /readyz`, `GET /metrics` | kubelet probes, `monitoring` ns | none |++The runtime route refuses a platform JWT whose `hostRefs` contains `*` or does+not contain the ticket's Host. Admin permits are refused on the runtime port,+and execution tickets on the admin port. Errors are JSON `{"error": "<code>"}`.++Upstream origins are fixed in `src/originPolicy.ts`:+`https://chatgpt.com/backend-api/codex/responses` for completions and+`https://chatgpt.com/backend-api/codex/models?client_version=1.0.0` for the+catalog.++## Kill switch++`CODEX_LLM_PROXY_EXECUTION_ENABLED` accepts only the exact string `true`. Any+other value, including the `"false"` in `deploy/base`, makes the completions+route and both admin routes answer `404 {"error":"disabled"}` after+authentication. Probes and metrics keep working. The minikube overlay sets it+to `"true"` (`deploy/overlays/minikube/configmaps/codex-llm-proxy-config.yaml`).+Restart the Deployment after changing it.++## Configuration++All configuration is read from environment variables in `src/config.ts`. The+proxy refuses to start when a value is invalid.++| Variable | Default | Purpose |+| ------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `CODEX_LLM_PROXY_RUNTIME_PORT` | `8080` | Runtime (completions) port |+| `CODEX_LLM_PROXY_ADMIN_PORT` | `8081` | Admin (catalog, connection test) port |+| `CODEX_LLM_PROXY_PROBE_PORT` | `9090` | Health and metrics port |+| `CODEX_LLM_PROXY_MAX_BODY_BYTES` | `8404992` | Ordinary request cap: the contract's 8 MiB `maxRequestBodyBytes` plus the 16 KiB envelope allowance. Lower values are refused. `deploy/base` leaves it unset. |+| `CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES` | `25165824` | Cap for V2 requests with images. Must equal the contract's `maxVisualRequestBodyBytes` (24 MiB) and be above `CODEX_LLM_PROXY_MAX_BODY_BYTES`. |+| `CODEX_LLM_PROXY_MAX_STREAM_DURATION_MS` | `1800000` | Longest a completion stream may run |+| `CODEX_LLM_PROXY_MAX_DEADLINE_MS` | `1800000` | Largest request deadline accepted |+| `CODEX_LLM_PROXY_UPSTREAM_IDLE_TIMEOUT_MS` | `300000` | Abort when the upstream is silent this long. Can only lower the built-in 300000. |+| `CODEX_LLM_PROXY_HEARTBEAT_INTERVAL_MS` | `15000` | SSE keepalive interval after a successful redeem. Values above `60000` are refused. |+| `CODEX_LLM_PROXY_JWT_ISSUER` | `control-api` | Expected `iss` of platform JWTs, tickets and admin permits |+| `CODEX_LLM_PROXY_JWT_PUBLIC_KEY` | — (required) | control-api's PEM public key. `deploy/base` reads it from ConfigMap `control-api-public-key`. |+| `CODEX_LLM_PROXY_EXECUTION_ENABLED` | off | Kill switch, see above. Only `true` enables. |+| `CODEX_LLM_PROXY_CONTROL_API_URL` | — (required) | Absolute http(s) base URL for redeem/finalize. `deploy/base`: `http://control-api-rpc-gateway.control-plane.svc.cluster.local:8090/api/v1` |+| `CODEX_LLM_PROXY_CONTROL_API_SERVICE` | `codex-llm-proxy` | Service name sent to control-api with the inter-service token |+| `CODEX_LLM_PROXY_CONTROL_API_TOKEN` | — (required) | Inter-service token. `deploy/base` reads it from Secret `codex-llm-proxy-secrets`, created by `deploy/scripts/apply-inter-service-tokens.sh`. |++`deploy/base` also sets `NODE_OPTIONS=--max-old-space-size=768` under a+`2048Mi` memory limit, and `terminationGracePeriodSeconds: 1935` so a rollout+lets admitted streams finish. The manifest comments explain both numbers.++## Network policy++`control-plane` is deny-all. The proxy's own policies are in+[`deploy/base/control-plane/networkpolicies.yaml`](../deploy/base/control-plane/networkpolicies.yaml):++- `codex-llm-proxy-ingress`: port 8080 from Host pods in `mcp-host`+ (`clerum.io/managed-by: host-context-controller`) and workflow MCP host pods+ in `sandbox-recipes` (`clerum.io/component: workflow-mcp-host`); port 8081+ from `control-api`; port 9090 from the `monitoring` namespace.+- `codex-llm-proxy-egress`: port 8090 to `control-api-rpc-gateway` and TCP 443+ to `0.0.0.0/0`. The private and special-use ranges in `except` are filled at+ build time by the replacements in+ [`deploy/base/kustomization.yaml`](../deploy/base/kustomization.yaml) from+ `public-egress-exceptions.yaml`. DNS comes from+ `allow-dns-egress-control-plane`.+- `control-api-to-codex-llm-proxy` and `control-api-rpc-gateway` open the+ matching control-api and gateway sides.++## Development++```bash+npm ci+npm run build # tsc -> dist/+npm test # typecheck tests, then vitest+npm run typecheck+npm start # node dist/main.js (needs the required env vars)+```++## Related++- [Connect an LLM subscription](../docs/how-to/connect-llm-subscription.md): enable flags, sign in, troubleshoot+- [Codex subscription transport contract](../docs/architecture/codex-subscription-transport-contract.md)+- [grok-llm-proxy](../grok-llm-proxy/README.md): the Grok siblingdiff --git a/docs/README.md b/docs/README.mdindex ccf1fbcb2..8a3df7709 100644--- a/docs/README.md+++ b/docs/README.md@@ -57,6 +57,7 @@ minikube overlays ship; features that are off by default say so.| [Configure approvals](how-to/configure-approvals.md) | Human-in-the-loop tool gates || [Add an MCP server](how-to/add-mcp-server.md) | Dev-mode JSON, CRD, or Control UI path || [Desktop setup & updates](how-to/desktop-setup-and-updates.md) | Environments, invitation setup, updates |+| [Manage users and teams](how-to/manage-users-and-teams.md) | Members, teams, roles, control admins, agent access || [Member invitations on self-hosted](how-to/member-invitations-self-hosted.md) | Hosted mode zero-config emails vs running your own service || [Track usage & set budgets](how-to/token-budgets-and-usage.md) | Enable budgets, scope, block vs warn || [Connect to the registry](how-to/connect-to-registry.md) | Self-hosted registry connect flow |@@ -90,12 +91,14 @@ minikube overlays ship; features that are off by default say so.## Reference-| Doc | Description |-| -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |-| [CRD index](crds/README.md) | All 9 `clerum.io` CRDs |-| [Workflow SDK](../packages/workflow-sdk/README.md) | `@clerum/workflow-sdk` — build custom workflow coordinator images |-| [llms.txt](llms.txt) | Machine-readable doc map for coding agents |-| Service READMEs | One-line map per component in the root [README components list](../README.md#docs-and-components) |+| Doc | Description |+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |+| [Configuration switches](reference/configuration.md) | Feature flags that differ between `deploy/base` and minikube, and where each service's variables are documented |+| [Plugin UI SDK](reference/plugin-ui-sdk.md) | `window.clerum` API for plugin apps embedded in the Desktop App |+| [CRD index](crds/README.md) | All 9 `clerum.io` CRDs |+| [Workflow SDK](../packages/workflow-sdk/README.md) | `@clerum/workflow-sdk` — build custom workflow coordinator images |+| [llms.txt](llms.txt) | Machine-readable doc map for coding agents |+| Service READMEs | One-line map per component in the root [README components list](../README.md#docs-and-components) |## Architecture deep divesdiff --git a/docs/architecture/overview.md b/docs/architecture/overview.mdindex 81872f958..07b0ce9d9 100644--- a/docs/architecture/overview.md+++ b/docs/architecture/overview.md@@ -8,7 +8,7 @@ evenfire is a Kubernetes-native platform for LLM orchestration with multi-channe> `channel-reader` → `mcp-host` → MCP servers, plus the `host-context-controller`> that provisions them — and on the end-to-end message lifecycle, dev mode, and> the tool approval system. It is **not** a complete service reference: the-> platform has ~18 services, and this document details four of them.+> platform has more than 20 services, and this document details four of them.>> - For every service and which controller creates it → [/ARCHITECTURE.md](../../ARCHITECTURE.md)> - For namespaces, trust boundaries, NetworkPolicy layers and the WRC → [platform-topology.md](platform-topology.md)@@ -36,7 +36,7 @@ evenfire is a Kubernetes-native platform for LLM orchestration with multi-channe### System Diagram-Scoped to the four services this document covers — for the full 12-namespace platform (all ~18 services), see [platform-topology.md §1](platform-topology.md#1-platform-architecture-12-namespaces).+Scoped to the four services this document covers — for the full 13-namespace platform (every service), see [platform-topology.md §1](platform-topology.md#1-platform-architecture-13-namespaces).```mermaid%%{init: {'theme':'base', 'themeVariables': {'fontSize':'12px'}}}%%@@ -88,6 +88,19 @@ validation flow are documented in [Desktop GFS operator parity](gfs-desktop-oper| **host-context-controller** | `/host-context-controller` | `control-plane` | 8081 | K8s operator managing MCP server Deployments/Services/NetworkPolicies; REST API for server discovery || **MCP Servers** | `/mcp-servers` | `mcp-server` | 3000 | First-party MCP servers (airtable, alphavantage, doc-generator, mongodb, playwright, web-search) |+Other services and directories this document does not detail (full list in+[/ARCHITECTURE.md](../../ARCHITECTURE.md)):++| Service | Namespace | Role |+| -------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------- |+| [webhook-proxy](../../webhook-proxy/README.md) | `webhook-ingress` | Shared public webhook router; looks the webhook up in control-api and streams it to the recipe's gateway |+| [webhook-gateway](../../webhook-gateway/README.md) | `sandbox-recipes` | Per-recipe webhook signature verifier; WRC creates one per recipe, no static manifest |+| [nginx-egress-proxy](../../nginx-egress-proxy/README.md) | `mcp-server` | Image only: the `egress-proxy` container HCC adds to remote (`spec.remote`) McpServer pods |+| [profile-ui](../../profile-ui/README.md) | `profiles` | End-user profile, invitations, Desktop App setup and app-link handoff |+| [codex-llm-proxy](../../codex-llm-proxy/README.md) | `control-plane` | Broker for `codex-subscription` model calls; off by default (`CODEX_LLM_PROXY_EXECUTION_ENABLED`) |+| [grok-llm-proxy](../../grok-llm-proxy/README.md) | `control-plane` | Broker for `grok-subscription` model calls; off by default (`GROK_LLM_PROXY_EXECUTION_ENABLED`) |+| [monitoring](../../monitoring/README.md) | `monitoring` | Not a service: optional Helm values and dashboards for Grafana and Loki, installed with its own Makefile |+### Human surfacesThe message path above is one of two ways into the platform. The other is the@@ -853,7 +866,7 @@ The HTTP response is held open until the agent finishes processing. The response### Purpose-Kubernetes operator that manages the full lifecycle of MCP servers. When an McpServer CRD appears, it creates the corresponding Deployment and Service. When a Context CRD changes, it regenerates NetworkPolicies. Also provides a REST API for mcp-host to discover available servers.+Kubernetes operator that manages the full lifecycle of MCP servers. When an McpServer CRD appears, it creates the corresponding Deployment and Service. When a Context CRD changes, it regenerates NetworkPolicies. Also provides a REST API for mcp-host to discover available servers. Beyond MCP servers, it creates the `mcp-host` pod for each Host, the file controllers for SharedFileSystem and GlobalFileSystem, and guardrail hook pods for image-target LlmHooks.### Source Structure@@ -869,6 +882,7 @@ host-context-controller/│ ├── hostReconciler.ts # Host CRD → mcp-host Deployment│ ├── sharedFileSystemReconciler.ts # SharedFileSystem → PVC + workspace-files-controller│ ├── gfsReconciler.ts # GlobalFileSystem → gfs-controller writer/reader roles+│ ├── llmHookReconciler.ts # LlmHook (image target) → hook Deployment/Service/NetworkPolicy in llm-hooks│ ├── bindingPolicyReconciler.ts # Binding policy reconciliation│ ├── secretFactory.ts # Secret projection for reconciled workloads│ ├── metrics.ts # Prometheus metrics@@ -882,8 +896,8 @@ host-context-controller/> [`deploy/base/`](../../deploy/base/), grouped by namespace — HCC's are in> `deploy/base/control-plane/host-context-controller.yaml`.-The controller reconciles five CRDs: `McpServer`, `Context`, `Host`,-`SharedFileSystem`, and `GlobalFileSystem`.+The controller reconciles six CRDs: `McpServer`, `Context`, `Host`,+`SharedFileSystem`, `GlobalFileSystem`, and `LlmHook`.### Operator Reconciliationdiff --git a/docs/architecture/platform-topology.md b/docs/architecture/platform-topology.mdindex 2be45328f..bf4b93137 100644--- a/docs/architecture/platform-topology.md+++ b/docs/architecture/platform-topology.md@@ -12,7 +12,7 @@## Table of Contents-1. [Platform Architecture (12 Namespaces)](#1-platform-architecture-12-namespaces)+1. [Platform Architecture (13 Namespaces)](#1-platform-architecture-13-namespaces)2. [Security Architecture: Deny-All by Default](#2-security-architecture-deny-all-by-default)3. [Controller Architecture](#3-controller-architecture)4. [CRD Ecosystem](#4-crd-ecosystem)@@ -33,13 +33,13 @@----## 1. Platform Architecture (12 Namespaces)+## 1. Platform Architecture (13 Namespaces)### 1.1 Platform Overviewevenfire is a Kubernetes-native platform for LLM orchestration with multi-channel communication (Telegram, Email, Slack, Desktop App) and MCP (Model Context Protocol) integration. All configuration is driven by CRDs under the historical `clerum.io/v1alpha1` API group ([code names](../concepts/code-names.md)).-The platform is deployed across **12 namespaces** (declared in `deploy/`) with a **deny-all by default** security posture. Every runtime namespace denies all ingress/egress by default: HCC reconciles the deny-all for its four runtime namespaces (mcp-server, sandbox-recipes, rpc-proxy, sandbox-ui), and `mcp-host` gets an equivalent static `deny-all-mcp-host` policy shipped in `deploy/base/mcp-host/networkpolicies.yaml`. Communication is only enabled through explicit NetworkPolicies owned by the component responsible for that selector family: HCC for Context/MCP relationships, WRC for WorkflowRecipe runtime pods, and static deploy overlays for platform infrastructure policies.+The platform is deployed across **13 namespaces** (declared in `deploy/`) with a **deny-all by default** security posture. Every runtime namespace denies all ingress/egress by default: HCC reconciles the deny-all for its four runtime namespaces (mcp-server, sandbox-recipes, rpc-proxy, sandbox-ui), `mcp-host` gets an equivalent static `deny-all-mcp-host` policy shipped in `deploy/base/mcp-host/networkpolicies.yaml`, and `llm-hooks` gets the static `llm-hooks-static-default-deny` policy from `deploy/base/llm-hooks/networkpolicies.yaml`. Communication is only enabled through explicit NetworkPolicies owned by the component responsible for that selector family: HCC for Context/MCP relationships, WRC for WorkflowRecipe runtime pods, and static deploy overlays for platform infrastructure policies.**Core architectural principle**: Think Linux — **deny everything by default, open only what is needed, with explicit justification for every exception**.@@ -68,6 +68,7 @@ flowchart TBendWRC["workflow-recipes (WRC)<br/>separate Deployment"]+ LLMP["codex-llm-proxy / grok-llm-proxy"]end%% === GATEWAY ===@@ -96,6 +97,11 @@ flowchart TBSB_JOB["Job (recipe-B)"]end+ %% === LLM HOOKS (deny-all) ===+ subgraph NS_HOOK["llm-hooks 🔒"]+ HOOK["Guardrail hook pods<br/>(LlmHook image targets)"]+ end+%% === RPC PROXY (deny-all) ===subgraph NS_RPC["rpc-proxy 🔒"]RPC_MCP["MCP Server Proxy"]@@ -117,6 +123,9 @@ flowchart TBHCC_AC -->|creates Context/MCP NetworkPolicies| NS_HOSTHCC_AC -->|creates Context/MCP NetworkPolicies| NS_SBHCC_AC -->|creates Context/MCP NetworkPolicies| NS_RPC+ HCC_BOX -->|LlmHook reconciler creates hook Deploy+Svc+NetworkPolicy| NS_HOOK+ MH -.->|guardrail hook calls| HOOK+ MH -.->|subscription model calls| LLMPMH -.->|MCP tools| MCP_AMH -.->|MCP tools| MCP_BSB_STS -.->|binding| MCP_A@@ -129,9 +138,9 @@ flowchart TBclassDef svc fill:#DBEAFE,stroke:#3B82F6,color:#1E40AFclassDef ext fill:#FEF3C7,stroke:#D97706,color:#92400E- class NS_HOST,NS_MCP,NS_SB,NS_RPC deny+ class NS_HOST,NS_MCP,NS_SB,NS_RPC,NS_HOOK denyclass HCC_BOX,WRC,HCC_MH,HCC_AC,HCC_MS ctrl- class MH,CHAN,MCP_A,MCP_B,MCP_C,RPC_MCP,RPC_HOST svc+ class MH,CHAN,MCP_A,MCP_B,MCP_C,RPC_MCP,RPC_HOST,HOOK,LLMP svcclass USER,DESKTOP ext```@@ -140,10 +149,11 @@ flowchart TB| Namespace | Purpose | Deny-All Default | Key Components || ------------------- | -------------------------------------------------------- | :--------------: | ---------------------------------------------------------------------------------------------- || **profiles** | User identity, profiles, team management, access mapping | No (management) | profile-ui, external-rest-api |-| **control-plane** | Platform management, CRD lifecycle, controllers | No (management) | control-ui, control-api, control-postgres, HCC Image (3 synchronizers), workflow-recipes (WRC) |+| **control-plane** | Platform management, CRD lifecycle, controllers | No (management) | control-ui, control-api, control-postgres, HCC Image (3 synchronizers), workflow-recipes (WRC), codex/grok LLM proxies || **channels** | External communication ingress (channels) | No (ingress) | Communication Channel Image (TG/Email/Slack) || **mcp-host** | LLM orchestration and agent state machine | **Yes** | mcp-host (Agent + MCP Client) || **mcp-server** | MCP server runtime and CRD storage | **Yes** | MCP server pods, McpServer CRDs, Context CRDs |+| **llm-hooks** | Guardrail hook runtime and LlmHook CRDs | **Yes** (static) | Hook pods HCC reconciles from `image`-target LlmHooks; PSS `baseline` enforced, `restricted` warn/audit || **sandbox-recipes** | Non-MCP workloads from WorkflowRecipes | **Yes** | StatefulSets, CronJobs, Jobs, Deployments, PVCs || **rpc-proxy** | Secure external access for Desktop App users | **Yes** | mcpProxy Image (MCP Server Proxy, MCP Host Proxy) || **sandbox-ui** | Untrusted recipe-supplied UI workloads | **Yes** | Recipe-defined UI workloads (ingress only via rpc-proxy) |@@ -152,7 +162,7 @@ flowchart TB| **ingress** | Public tunnel ingress | **Yes** | cloudflared || **registry** | Recipe registry (declared in the minikube overlay only) | No | registry-api (side-by-side registry server, port 8085) |-> Namespace names above are the ones declared in `deploy/` (`deploy/base/namespaces.yaml`, plus `deploy/base/ingress/` and `deploy/overlays/minikube/registry/`). Diagrams in this document use the historical conceptual names **profile-plane** and **gateway** for the declared namespaces `profiles` and `channels`.+> Namespace names above are the ones declared in `deploy/` (`deploy/base/namespaces.yaml`, plus `deploy/base/ingress/` and `deploy/overlays/minikube/registry/`). The `llm-hooks` deny-all is a static manifest (`llm-hooks-static-default-deny`, labeled `clerum.io/managed-by: llm-hooks`), not an HCC-reconciled L0 policy; HCC adds only the narrow allow policies (§2.2). Diagrams in this document use the historical conceptual names **profile-plane** and **gateway** for the declared namespaces `profiles` and `channels`.### 1.3 Service Map@@ -166,6 +176,8 @@ Every service in the repo. Ports are the container ports in `deploy/base/`.| **control-api** | `/control-api` | control-plane | 8090 | CRD lifecycle, resource CRUD, profile mapping || **Host Context Controller** | `/host-context-controller` | control-plane | 8081 | 3 synchronizers (MCP Host, AccessCtrl, MCP Server) + Discovery REST API || **Workflow Recipe Controller** | `/workflow-recipes` | control-plane | 8082 | Standalone `workflow-recipes` Deployment + Service — a separate process from HCC, own image and SA |+| **codex-llm-proxy** | `/codex-llm-proxy` | control-plane | 8080 | Broker for Codex subscription model calls (admin 8081, metrics 9090). Execution off by default — see [connect an LLM subscription](../how-to/connect-llm-subscription.md) |+| **grok-llm-proxy** | `/grok-llm-proxy` | control-plane | 8080 | Broker for Grok subscription model calls (admin 8081, metrics 9090). Execution off by default || **Comm Channel Image** | `/channel-reader` | channels | — | Polls TG/Email/Slack, forwards to mcp-host || **workflow-approval-request-reader** | `/workflow-approval-request-reader` | channels | 8098 | Inbound half of channel approvals — receives provider callbacks, submits decisions || **mcp-host** | `/mcp-host` | mcp-host | 8080 | LLM orchestration, agent state machine, MCP tool calling |@@ -230,6 +242,9 @@ Nothing moves until HCC creates explicit allow policies.| rpc-proxy → mcp-server | Context/server-scoped data plane + profile-scoped app auth | HCC `rpc-egress-<context>-<server>` plus matching `ctx-<context>-<server>` ingress, with control-api profile ACL || rpc-proxy → mcp-host | Host-scoped data plane + profile-scoped app auth | HCC `rpc-proxy-<host>-egress-mcp-host` and `mcp-host-<host>-ingress-rpc-proxy` NetworkPolicies plus control-api profile ACL || control-plane → mcp-server | RBAC watch-only | HCC watches CRDs, creates Deploys. No data plane access |+| mcp-host → llm-hooks | Host-scoped (hooks the Host references) | HCC `mcp-host-<host>-egress-llm-hooks` egress plus `llmhook-<podKey>` / `llmhook-svc-<crName>` ingress, over the static `llm-hooks` deny-all |+| mcp-host → LLM proxies | Host-scoped + single-use ticket | HCC `mcp-host-<host>-egress-codex-proxy` / `-grok-proxy` (only for Hosts configured for that subscription) plus static proxy ingress in `deploy/base/control-plane/networkpolicies.yaml` |+| mcp-host → public internet | Public-only | Static `mcp-host` policy: TCP 80/443 to `0.0.0.0/0` minus the ranges in `deploy/base/public-egress-exceptions.yaml` |### 2.3 Security Invariants@@ -254,7 +269,7 @@ The platform uses a **controller architecture** where all control logic runs in| Workflow Recipe Controller (WRC) | `control-plane` | Pure CRD reconciler for WorkflowRecipe lifecycle — its own Deployment (port 8082) || Control-plane triggers deploys | `control-plane` | Agents cannot trigger deploys directly || Non-MCP workloads | `sandbox-recipes` | Isolated runtime for non-MCP recipe workloads |-| 12 namespaces | — | channels, control-plane, gfs, ingress, mcp-host, mcp-server, profiles, registry (minikube overlay), rpc-proxy, sandbox-recipes, sandbox-ui, webhook-ingress |+| 13 namespaces | — | channels, control-plane, gfs, ingress, llm-hooks, mcp-host, mcp-server, profiles, registry (minikube overlay), rpc-proxy, sandbox-recipes, sandbox-ui, webhook-ingress |### 3.2 Where the WRC Fits@@ -349,8 +364,9 @@ sequenceDiagram| `CommunicationChannel` | control-api | Comm Channel Image | TG/Email/Slack channels || `SharedFileSystem` | control-api | HCC (SFS reconciler) | Team workspace: PVC + workspace-files-controller || `GlobalFileSystem` | control-api | HCC (GFS reconciler) | Global drive: PVC + gfs-controller roles |+| `LlmHook` | control-api (hook install) | HCC (LlmHook reconciler), mcp-host (read) | Installed guardrail hook in `llm-hooks` |-All eight are shipped in [`charts/clerum-crds/crds/`](../../charts/clerum-crds/crds/)+All nine are shipped in [`charts/clerum-crds/crds/`](../../charts/clerum-crds/crds/)and have a reference page under [docs/crds/](../crds/).### 4.2 McpServer CRD Status@@ -373,6 +389,8 @@ and no `status.sanitization` — reconciliation state is reported through `condi| **MCPAccessController Sync** | Context CRDs, McpServer annotations, Host CRDs | Context/MCP NetworkPolicies | mcp-server, mcp-host, sandbox-recipes, rpc-proxy || **MCP Host Sync** | Host CRDs | mcp-host configuration, Secret validation | mcp-host |+The same process also runs the `GlobalFileSystem`, `SharedFileSystem` and `LlmHook` reconcilers. The LlmHook reconciler watches `LlmHook` CRDs (and Host `spec.guardrails.hooks` references) and creates, for `image` targets, a shared Deployment + Service + NetworkPolicy per pod key in `llm-hooks`, plus a per-Host `mcp-host-<host>-egress-llm-hooks` egress policy. See the [HCC README](../../host-context-controller/README.md#llmhook-operator) and [LlmHook CRD](../crds/llmhook.md).+### 5.1 Sanitization Gate (MCP Server Sync)**The gate only runs for `managed: true` McpServers.** `reconcile()` reads `spec.managed` (CRD default `true`) and, when it is `false`, returns early into `reconcileWrcOwnedServer()` (`host-context-controller/src/reconciler.ts`), which validates the Secret, writes `Ready=True` (`reason: WrcOwnedRuntimeReady`) and does nothing else. `sanitizeCrdSpec()` is called only from `buildDeployment()`, and `classifyPluginImage()` only on the managed branch — so **neither runs on the WRC-owned path**.@@ -801,7 +819,7 @@ flowchart TD#### 11.2.5 L3-Egress — External Runtime Egress-**What it does**: Opens explicit public egress paths declared by runtime configuration. Kubernetes NetworkPolicy cannot enforce HTTP hostnames at L7, so the current architecture resolves declared hostnames to public IPv4 CIDRs and writes L3/L3-runtime egress policies that allow only those CIDRs on HTTPS port 443. Plain HTTP is intentionally not permitted because it can expose credentials or prompt content.+**What it does**: Opens explicit public egress paths declared by runtime configuration. Kubernetes NetworkPolicy cannot enforce HTTP hostnames at L7, so the current architecture resolves declared hostnames to public IPv4 CIDRs and writes L3/L3-runtime egress policies that allow only those CIDRs. Ports differ by owner: WRC runtime egress allows only HTTPS port 443 (plain HTTP is not permitted because it can expose credentials or prompt content); an HCC `exact-host` McpServer binding allows the one port/protocol it declares; an HCC `public-web` binding allows TCP 80/443 to `0.0.0.0/0` minus HCC's compiled `PUBLIC_EGRESS_EXCEPT_CIDRS` (the same ranges as `deploy/base/public-egress-exceptions.yaml`).**Applied to**:@@ -813,7 +831,7 @@ flowchart TD**Operational constraint**: Hostname-to-CIDR resolution is fail-closed. A runtime host that does not resolve, resolves only to non-IPv4 addresses, or resolves to private, metadata, link-local, carrier NAT, documentation, benchmarking, multicast, or reserved ranges must not create a permissive public egress rule. WRC refreshes active WorkflowRecipe runtime egress policies during the same steady-state loop used for runtime credential refresh. When DNS changes, WRC patches the NetworkPolicy with the new public `/32` CIDRs while retaining the previous CIDR set for the configured overlap window (`WRC_RUNTIME_EGRESS_DNS_OVERLAP_SECONDS`, default `300`) so active runs do not lose connectivity during propagation. That overlap is also a bounded trust window: previous public CIDRs remain allowed until expiry and should be tuned with that security tradeoff in mind.-**mcp-host distinction**: `runtimeEgress.http.allowedHosts[]` is a strict network contract for WorkflowRecipe code runtimes such as snippet runners and custom coordinator images. Agentic `mcp-host` workloads are different: they run LLM/tool workflows that may need dynamic public internet access for provider APIs and operator-approved HTTP tools. Those pods keep a public HTTP/S egress lane with private, metadata, link-local, carrier NAT, documentation, benchmarking, multicast, and reserved ranges excluded. Fine-grained hostname policy for agentic browsing belongs in a future L7 egress proxy/tool gateway, not in raw Kubernetes NetworkPolicy.+**mcp-host distinction**: `runtimeEgress.http.allowedHosts[]` is a strict network contract for WorkflowRecipe code runtimes such as snippet runners and custom coordinator images. Agentic `mcp-host` workloads are different: they run LLM/tool workflows that may need dynamic public internet access for provider APIs and operator-approved HTTP tools. Those pods keep a public egress lane on TCP 443 and 80 to `0.0.0.0/0` (static `mcp-host` policy in `deploy/base/mcp-host/networkpolicies.yaml`). Its `except` list is empty in the committed file and filled by kustomize `replacements` at render time from `deploy/base/public-egress-exceptions.yaml`, which excludes private, metadata, link-local, carrier NAT, documentation, benchmarking, multicast, and reserved ranges. Fine-grained hostname policy for agentic browsing belongs in a future L7 egress proxy/tool gateway, not in raw Kubernetes NetworkPolicy.### 11.3 NetworkPolicy Owner Boundariesdiff --git a/docs/crds/context.md b/docs/crds/context.mdindex aa2960cfe..be92bea3e 100644--- a/docs/crds/context.md+++ b/docs/crds/context.md@@ -18,11 +18,40 @@ inject SharedFileSystem volume mounts into the mcp-host pod.| Field | Type | Required | Description ||-------|------|----------|-------------|| `spec.contextId` | string | yes | Unique identifier for this context (e.g. `context1`). |+| `spec.displayName` | string | no | Free-text display name (spaces and capitals allowed), editable without changing the identifier. When absent, UIs fall back to `metadata.name`. control-api rejects control characters and trimmed lengths over 120. || `spec.description` | string | no | Human-readable description of the context scope. || `spec.mcpServers` | string[] | yes | List of McpServer CRD names accessible within this context. When a host requests servers for this context, only these servers are returned by the context-mapper. || `spec.sharedFileSystems` | object[] | no | Optional list of SharedFileSystem references. Each entry causes HCC to inject a read-only volume mount into every mcp-host pod whose Host references this Context. Keyed on `mountPath` (unique within a Context). Each entry requires `name` (SharedFileSystem.metadata.name in the mcp-host namespace) and `mountPath` (absolute path inside the container, matching `^/[a-zA-Z0-9_.][a-zA-Z0-9_./\-]*$`). || `spec.gfs.mounts` | object[] | no | Optional Global File System mount intents. Intent only: HCC wires a mount only if the Context identity already holds the requested scopes. Keyed on `target`. Each entry requires `drive` (gfs drive name), `target` (32-hex resource id or absolute path), and `scopes` (array from `gfs.read`, `gfs.write`, `gfs.delete`, `gfs.manage_acl`, `gfs.share`). |+## Status Fields++| Field | Type | Description |+|-------|------|-------------|+| `status.sharedFileSystems[]` | object[] | Per-entry resolution of `spec.sharedFileSystems`: `name`, `mountPath`, `phase` (`Resolving` \| `Mounted` \| `MissingTarget` \| `Failed`), optional `pvcName` and `message`. Defined in the schema, but host-context-controller does not write it in this release. Readers such as control-api fall back to each SharedFileSystem's own `status.phase` and `status.pvcName`. |++## How Contexts are created++Most Contexts are created for you. Control UI has no Contexts screen: old+`/contexts` links redirect to the Agents list, or to the owning agent's+Connectors tab when the Context belongs to an agent.++- **Agents.** The agent wizard creates a private Context for each new agent+ and sets the Host's `contextRef` to it. Its `mcpServers` are the connectors+ picked in the wizard.+- **Connector installs.** Installing a connector from the Marketplace, through+ an OAuth connector install, or as a custom connector with no existing scope+ selected creates a private Context as that connector's access scope.+- **Workflow recipes.** A WorkflowRecipe that runs MCP transport workloads and+ sets no `spec.contextRef` gets a private Context named `wf-<recipeName>`+ (hash-shortened past 63 characters), created by the workflow-recipes+ operator in the `mcp-server` namespace. An agentic recipe that does set+ `contextRef` must pass the default-deny check described in+ [WorkflowRecipePolicy](workflowrecipepolicy.md).++UI-created private Contexts are named `<subject>-<5 digits>`, where the+subject is the agent or connector name in kebab case.+## Additional Printer Columns`kubectl get contexts` displays: Context ID, MCP Servers, SharedFS.@@ -48,5 +77,7 @@ spec:- [Host CRD](host.md) -- references this Context via `spec.contextRef`- [McpServer CRD](mcpserver.md) -- entries in `spec.mcpServers` must match McpServer metadata names+- [SharedFileSystem CRD](sharedfilesystem.md) -- targets of `spec.sharedFileSystems`+- [WorkflowRecipePolicy CRD](workflowrecipepolicy.md) -- `allowContextRef` for agentic recipes- [CRD Index](README.md)- [Example](../../charts/clerum-crds/examples/context1.yaml)diff --git a/docs/crds/globalfilesystem.md b/docs/crds/globalfilesystem.mdindex 4a210f683..525f058a8 100644--- a/docs/crds/globalfilesystem.md+++ b/docs/crds/globalfilesystem.md@@ -43,14 +43,19 @@ records it to a hash-chained audit log.| Field | Type | Required | Default | Description || --------------------------------- | -------- | -------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `spec.storage.size` | string | yes | -- | PVC requested storage for the drive's flat blob layout (e.g. `"500Gi"`). |+| `spec.storage` | object | yes | -- | Persistent storage for the drive. The whole block is required. |+| `spec.storage.size` | string | yes | -- | PVC requested storage for the drive's flat blob layout (e.g. `"500Gi"`). No schema default. || `spec.storage.storageClassName` | string | no | `standard-rwo` | StorageClass for the drive PVC. RWX (`clerum-gcsfuse`) is a deferred escalation — set explicitly only when such a class exists. || `spec.storage.accessModes` | string[] | no | `[ReadWriteOnce]` | The single-replica writer and co-located readers work on RWO-only StorageClasses; `ReadWriteMany` requires an RWX-capable class. |-| `spec.layout.rootDirectories` | string[] | no | `[]` | Absolute seed paths (e.g. `/org`), max 64. Materialized as governed resources in the permission store by control-api once the writer reports `Ready` — not written directly by the reconciler. |-| `spec.security.runAsUser` | integer | no | -- | POSIX UID applied to the gfsc pods and the init Job. |-| `spec.security.fsGroup` | integer | no | -- | Supplemental group applied so gfsc can read/write the mounted drive. |-| `spec.readerReplicas` | integer | no | `2` | Number of read-only gfsc reader replicas. The writer is always exactly 1 — GFS is a single-writer drive; only readers scale. |-| `spec.retainOnDelete` | boolean | no | `true` | When `false`, deleting the CRD tears down the Deployments, Service, NetworkPolicies, and PVC (PVC last). |+| `spec.layout.rootDirectories` | string[] | no | `[]` | Absolute seed paths (e.g. `/org`), max 64 entries, each max 512 characters. Each segment must start with a letter, digit, or underscore and may contain letters, digits, underscores, dots, and hyphens; `..` and empty segments are rejected. Materialized as governed resources in the permission store by control-api once the writer reports `Ready` — not written directly by the reconciler. |+| `spec.security.runAsUser` | integer | no | `1000` | Min 1. POSIX UID for the gfsc pods. The writer's root init container chowns the drive to this UID. |+| `spec.security.fsGroup` | integer | no | value of `runAsUser` | Min 1. Pod `fsGroup`, so gfsc can read/write the mounted drive. Also used as the pods' `runAsGroup` (the CRD has no separate `runAsGroup`). Root (0) is rejected. |+| `spec.readerReplicas` | integer | no | `2` | Min 0. Number of read-only gfsc reader replicas. The writer is always exactly 1 — GFS is a single-writer drive; only readers scale. |+| `spec.retainOnDelete` | boolean | no | `true` | On delete, HCC always removes the writer and reader Deployments, the writer PodDisruptionBudget, the `gfsc-writer` and `gfsc` Services, and the NetworkPolicies. When `false`, it then deletes the PVC last; when `true`, the PVC is kept. |++`storage.storageClassName`, `storage.accessModes`, `layout.rootDirectories`,+`readerReplicas`, and `retainOnDelete` defaults come from the CRD schema. The+`security` defaults are applied by HCC.Full OpenAPI schema: `charts/clerum-crds/crds/globalfilesystem.yaml`. Thereconciler owns pod-level detail the CRD doesn't expose — securityContext@@ -61,11 +66,11 @@ anything other than `readerReplicas`.| Field | Type | Description || ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |-| `status.phase` | string | `Provisioning \| Initializing \| Ready \| Degraded \| Failed`. |-| `status.pvcName` | string | The provisioned PVC name. |-| `status.serviceName` | string | ClusterIP Service serving gfsc **reads** through the writer + readers. |+| `status.phase` | string | Schema enum: `Provisioning \| Initializing \| Ready \| Degraded \| Failed`. The reconciler currently writes only `Initializing` (writer not yet available) and `Ready`. |+| `status.pvcName` | string | The provisioned PVC name (always `gfs-drive`). |+| `status.serviceName` | string | ClusterIP Service serving gfsc **reads** through the writer + readers (always `gfsc`). || `status.serviceUrl` | string | In-cluster base URL of the read Service (e.g. `http://gfsc.gfs.svc.cluster.local:8087`). Mutations go through a separate writer-only Service, not this URL. |-| `status.conditions[]` | object[] | Standard `{type, status, reason, message, lastTransitionTime}` condition list. |+| `status.conditions[]` | object[] | Standard `{type, status, reason, message, lastTransitionTime}` condition list. Defined in the schema; the reconciler does not write conditions in this release. |## Additional Printer Columnsdiff --git a/docs/crds/sharedfilesystem.md b/docs/crds/sharedfilesystem.mdindex 83454a5a2..420933ad1 100644--- a/docs/crds/sharedfilesystem.md+++ b/docs/crds/sharedfilesystem.md@@ -2,26 +2,76 @@**API Group:** `clerum.io`**Version:** `v1alpha1`-**Scope:** Namespaced (typically `mcp-host`)+**Scope:** Namespaced (must be `mcp-host`)**Short name:** `sfs`-**Reconciled by:** host-context-controller (+ per-SFS `workspace-files-controller`)+**Reconciled by:** host-context-controller (HCC) `sharedFileSystemReconciler`## Purpose-A **per-team shared workspace**: PVC + file API, mounted **read-only** into-`mcp-host` pods for Contexts that reference it. Humans/admins write via the-workspace-files controller; agents do not mutate the mount.+A **per-team shared workspace**: a PVC plus a file API, mounted **read-only**+into `mcp-host` pods whose Context references it. Humans and admins write+through the per-SFS workspace-files-controller (wfc). Agents do not mutate the+mount.-## Spec fields (summary)+For each SharedFileSystem, HCC creates in the `mcp-host` namespace:-| Field | Description |-| ----------------------- | ---------------------------------------------------------------- |-| `spec.size` | PVC request (default e.g. `20Gi`) |-| `spec.storageClassName` | StorageClass for the PVC |-| Additional fields | See CRD OpenAPI: `charts/clerum-crds/crds/sharedfilesystem.yaml` |+- a PVC named `sfs-<hash>-files`;+- a single-replica wfc Deployment `wfc-<hash>`, with a root init container+ that creates `spec.directories` and applies the `spec.security` ownership;+- a ClusterIP Service `wfc-<hash>` and ingress/egress NetworkPolicies.-Contexts attach SFS entries via their own spec (mount path + reference) — see-[Context](context.md) and feature docs when present on your version.+`<hash>` is the first 10 hex characters of the SHA-256 of+`<namespace>/<name>`.++The wfc does not read the CRD. HCC passes it the SFS name, namespace, and mount+path through `WSF_*` environment variables.++## Spec fields++| Field | Type | Default | Description |+| --------------------------- | ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `spec.size` | string | `20Gi` | PVC storage request. |+| `spec.storageClassName` | string | cluster default | StorageClass for the PVC. Omit to use the cluster default. |+| `spec.accessModes` | string[] | `[ReadWriteOnce]` | PVC access modes. Enum: `ReadWriteOnce`, `ReadOnlyMany`, `ReadWriteMany`, `ReadWriteOncePod`. RWO works because the wfc is single-replica and consuming `mcp-host` pods co-locate with it through pod affinity. `ReadWriteMany` needs an RWX-capable StorageClass; set it explicitly only when one exists. |+| `spec.annotations` | map[string]string | none | Annotations copied onto the PVC. |+| `spec.directories` | string[] | `[]` | Relative paths the wfc init container pre-creates. Max 64 entries, each max 255 characters. Each path segment must start with a letter, digit, or underscore, and may contain letters, digits, underscores, dots, and hyphens. |+| `spec.security.runAsUser` | integer | `1000` | Min 1. UID for the wfc pod and the ownership the init container applies. |+| `spec.security.runAsGroup` | integer | `1000` | Min 1. GID for the wfc pod and the init container ownership. |+| `spec.security.fsGroup` | integer | value of `runAsGroup` | Min 1. Pod `fsGroup`, so the wfc can write the mounted files. Root (0) is rejected for all three security fields. |+| `spec.retainOnDelete` | boolean | `true` | On delete, keep the PVC when `true`. When `false`, HCC deletes the Deployment, Service, and NetworkPolicies, then the PVC last. |++`size`, `accessModes`, `directories`, and `retainOnDelete` defaults come from+the CRD schema. The `security` defaults are applied by HCC.++**PVC changes after creation.** HCC creates the PVC once and then leaves it+alone. Changing `size`, `storageClassName`, or `accessModes` on an existing+SharedFileSystem does not resize or re-mode the PVC. A change to `directories`+or `security` does re-run the init container's layout and ownership step.++## Status++| Field | Type | Description |+| ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `status.phase` | string | `Provisioning` \| `Initializing` \| `Ready` \| `Degraded` \| `Failed`. `Ready` means the PVC is bound and the wfc is serving. `Initializing` covers a binding PVC or a wfc that is still starting. `Degraded` means the wfc pod is stuck (for example unschedulable). `Failed` means the reconcile itself errored. |+| `status.pvcName` | string | Provisioned PVC name (`sfs-<hash>-files`). |+| `status.capacity` | string | Capacity reported by the bound PVC. |+| `status.storageClassName` | string | Copied from `spec.storageClassName`; empty when the cluster default is used. |+| `status.serviceName` | string | ClusterIP Service for the per-SFS wfc (`wfc-<hash>`). |+| `status.mountedByContexts[]` | object[] | `{namespace, name}` of each Context that references this SFS. |+| `status.conditions[]` | object[] | HCC writes one `Reconciled` condition. Reasons include `Ready`, `PVCBinding`, `WfcStarting`, and `ReconcileError`. |+| `status.lastInitJob` | object | `{name, completedAt, error}`. Legacy: seeding moved from a Job into the wfc init container, and HCC no longer writes this field. |++## Additional Printer Columns++`kubectl get sfs -n mcp-host` displays: Phase, PVC, Capacity, Storage Class.++## Attaching to a Context++A Context lists SharedFileSystems in `spec.sharedFileSystems[]` with a `name`+and an absolute `mountPath`. HCC then mounts the PVC read-only into every+`mcp-host` pod whose Host references that Context. The mount follows the PVC,+not the wfc: it is added once the PVC is bound and stays in place across wfc+restarts. See [Context](context.md).## Example@@ -32,14 +82,31 @@ metadata:name: team-missionnamespace: mcp-hostspec:- size: 20Gi+ size: 5Gi+ accessModes:+ - ReadWriteOnce+ directories:+ - docs+ - customer-history+ - runbooks+ security:+ runAsUser: 1000+ runAsGroup: 1000+ fsGroup: 1000+ retainOnDelete: true```-Working sample:+Working sample (SFS plus a Context that mounts it):[charts/clerum-crds/examples/sharedfilesystem-team-mission.yaml](../../charts/clerum-crds/examples/sharedfilesystem-team-mission.yaml).+Control UI and control-api (`POST /admin/shared-filesystems`) create the same+object. That route accepts `size`, `storageClassName`, `accessModes`,+`directories`, `retainOnDelete`, and `security`.+## Related- [CRD index](README.md)+- [Context CRD](context.md) — `spec.sharedFileSystems[]`- [Shared & global files how-to](../how-to/shared-and-global-files.md) — create an SFS, attach it to a Context, upload+- [GlobalFileSystem CRD](globalfilesystem.md) — the separate governed drive- [workspace-files-controller](../../workspace-files-controller/) (service tree)diff --git a/docs/crds/workflowrecipe.md b/docs/crds/workflowrecipe.mdindex 51899d793..2b1c68b81 100644--- a/docs/crds/workflowrecipe.md+++ b/docs/crds/workflowrecipe.md@@ -440,6 +440,29 @@ and is pruned by the API server.Without `spec.coordinatorImage`, each step must set exactly one of `instruction` or `run`. With `spec.coordinatorImage`, id-only steps are allowed. `run + instruction` and `run + agent` are always rejected. Snippet steps require `run.type: snippet`, `run.language: typescript`, and inline `run.code`.+Step fields (`spec.steps[]`, max 100 steps):++| Field | Type | Default | Description |+| ------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `id` | string | -- | **Required.** `^[a-z][a-z0-9-]*$`, max 63. |+| `instruction` | string | -- | Agentic step prompt. Max 10000 characters. |+| `run` | object | -- | Snippet invocation (`type`, `language`, `code` max 20000, optional `capabilities`). |+| `dependsOn` | string[] | -- | Step ids that must complete first. Max 100. |+| `mcpServers` | string[] | -- | MCP server ids available during this step. Max 20. |+| `timeoutSeconds` | integer | `300` | Min 1. Step execution timeout. |+| `maxRetries` | integer | `2` | 1–5. Retry attempts for transient failures (connection reset, timeout). |+| `backoffSeconds` | integer | `30` | 1–3600. Base delay before retrying a failed step. |+| `allowedTools.include` | string[] | -- | Tool allowlist in `serverName__toolName` form. Only listed tools are presented to the LLM. Max 100. |+| `toolChoice` | string | -- | `auto` \| `none` \| `required`. LLM tool-choice policy for this step. |+| `maxIterations` | integer | `50` | 1–100. Maximum LLM tool-calling iterations for this step. |+| `agent.provider` | string | -- | Per-step provider override. Same enum as [`spec.agent.provider`](#39-agent-configuration-specagent). |+| `agent.model` | string | -- | Per-step model override. `^[A-Za-z0-9._:/-]{1,128}$`. |+| `agent.soul` | string | -- | Per-step SOUL content, passed inline to the coordinator for this step. |+| `requiresApproval` | object | -- | Human approval gate. See [§3.1.2](#312-step-approval-gates-stepsrequiresapproval). |++`step.agent` cannot be combined with `run` (CEL). Defaults above are CRD+schema defaults.+```yamlsteps:- id: merge@@ -1031,12 +1054,12 @@ Resolution happens at reconciliation time only:### 3.9 Agent Configuration (`spec.agent`)-The **default LLM configuration** for every agentic (`instruction`) step. Steps may override `model` / `provider` via `steps[].agent`. The reconciler resolves the recipe's `mcp-host` agent from `spec.agent` first, then falls back to the first step declaring a _complete_ agent.+The **default LLM configuration** for every agentic (`instruction`) step. Steps may override `model` / `provider` (and supply inline `soul` content) via `steps[].agent`. The reconciler resolves the recipe's `mcp-host` agent from `spec.agent` first, then falls back to the first step declaring a _complete_ agent.| Field | Type | Required | Description || --------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `model` | string | No\* | LLM model name (e.g. `gpt-4o`, `claude-3-opus`). |-| `provider` | string | No\* | Enum: `openai`, `claude`, `zai`, `bailian`, `vertex`, `bedrock`, `openrouter`, `gemini`, `deepseek`, `groq`, `together`, `fireworks`, `mistral`, `xai`, `cerebras`, `deepinfra`, `perplexity`, `moonshot`, `nebius`, `novita`, `minimax`, `azure`. |+| `provider` | string | No\* | Enum (22 values): `openai`, `claude`, `zai`, `bailian`, `vertex`, `openrouter`, `gemini`, `deepseek`, `groq`, `together`, `fireworks`, `mistral`, `xai`, `cerebras`, `deepinfra`, `perplexity`, `moonshot`, `nebius`, `novita`, `minimax`, `codex-subscription`, `grok-subscription`. `bedrock` and `azure` are deliberately excluded: the WRC credential transport carries one secret value and cannot deliver Bedrock's key pair or Azure's required endpoint. The same enum applies to `steps[].agent.provider`. || `secretRef.name` | string | No | Secret holding the API key. || `secretRef.namespace` | string | No | Secret namespace. || `soulRef.storageRef` | object | No | `SOUL.md` in object storage: `bucket`, `key`, `provider` (`s3`\|`gcs`\|`spaces`\|`minio`), `region`, `endpoint`. |@@ -1059,6 +1082,7 @@ spec:- **CEL R1** — `agent requires non-empty workflow steps or spec.pluginWorkloadSdk.promptBridge`. An agent remains invalid for an ordinary workloads-only recipe, but a stepless `promptBridge` recipe uses `spec.agent` as the eager mcp-host bootstrap binding rather than as a workflow agent.- A `provider` outside the canonical provider enum.+- CEL: `spec.agent.secretRef is not allowed for oauth-broker providers` — `codex-subscription` and `grok-subscription` take no `secretRef`. See [Connect an LLM subscription](../how-to/connect-llm-subscription.md).- An `instruction` step with no resolvable agent: _"step requires an agent configuration"_.### 3.10 MCP Servers (`spec.mcpServers`)@@ -1378,11 +1402,18 @@ Declaring this block forces an always-on `mcp-host`. Runtime enforcement is addi| `promptBridge.maxRequestsPerRun` | integer | No | Min 1. **Deprecated:** accepted but ignored; platform per-minute rate limits apply. Removal planned. || `promptBridge.maxConcurrentInvocations` | integer | No | Min 1. Runtime default 5. || `promptBridge.maxInvocationsPerMinute` | integer | No | Min 1. Platform default 600 when unset (ENV `CONTROL_API_PLUGIN_SDK_PROMPTBRIDGE_PER_MIN`, issue #348). |+| `promptBridge.maxRequestContentBytes` | integer | No | Min 1. Max total bytes across `messages[].content`. **Not read at runtime in this release:** mcp-host applies a fixed 128 KiB cap. |+| `promptBridge.resultRetentionHours` | integer | No | Min 1. Schema description says default 24. **Not read at runtime in this release.** |+| `promptBridge.maxAttachments` | integer | No | Min 0. Schema description says default 0 (no attachments in v1). **Not read at runtime in this release.** |+| `promptBridge.maxAttachmentBytes` | integer | No | Min 0. Schema description says default 0. **Not read at runtime in this release.** || `clientNotifications.allowedEventTypes` | string[] | **Yes**\† | 1–64 entries. || `clientNotifications.allowedTargetRefs` | string[] | No | Max 64. || `clientNotifications.allowedUserRefs` | boolean | No | Whether `userRef` targets are permitted. || `clientNotifications.maxNotificationsPerRun` | integer | No | Min 1. **Deprecated:** accepted but ignored; platform per-minute rate limits apply. Removal planned. || `clientNotifications.maxNotificationsPerMinute` | integer | No | Min 1. Platform default 750 when unset (ENV `CONTROL_API_PLUGIN_SDK_NOTIFICATIONS_PER_MIN`, issue #348). |+| `clientNotifications.maxTitleBytes` | integer | No | Min 1. **Not read at runtime in this release:** mcp-host applies a fixed 256-byte title cap. |+| `clientNotifications.maxBodyBytes` | integer | No | Min 1. **Not read at runtime in this release:** mcp-host applies a fixed 4096-byte body cap. |+| `clientNotifications.resultRetentionHours` | integer | No | Min 1. Schema description says default 72. **Not read at runtime in this release.** || `allowedCallers` | string[] | No | Workload ids permitted to call the SDK. **Empty = all declared workloads.** || `idempotencyKeyPattern` | string | No | Regex; runtime default `^[a-zA-Z0-9_-]{1,128}$`. Must compile. |@@ -3154,6 +3185,33 @@ status:The active profile is read from **`spec.activeProfile`** (the recipe's own input),not from status.+**`status.steps[]` fields** (written by WRC from coordinator step updates):++| Field | Description |+| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `id`, `phase`, `executor`, `startedAt`, `completedAt`, `error` | Step identity and lifecycle. `phase`: `pending` \| `running` \| `completed` \| `failed` \| `skipped`. `executor`: `agentic` \| `snippet` \| `custom`. |+| `output`, `outputTruncated`, `outputLength`, `outputPreviewMaxChars` | Bounded output preview (see §3.1.1). |+| `modelUsed` | Model the step ran with. |+| `approvalBindingSha256` | Set only for steps with `requiresApproval` (§3.1.2): the SHA-256 of a one-time proof the coordinator generates for that approval gate. |+| `toolsCalled[]` | Tool calls made by the step: `serverName` and `toolName` (required), `args`, `result`, `durationMs`. WRC stores at most the first 50 calls. An `args` or `result` value longer than 1024 serialized characters is replaced by `{truncated: true, preview: "<first 1024 chars>"}`. |+| `toolsCalledTruncated` | Boolean in the schema. WRC does not set it in this release, so a list capped at 50 is not flagged. |++**`status.pluginWorkloadSdk`** (written by WRC when `spec.pluginWorkloadSdk` is+declared; control-api reads it to know which SDK families are active):++| Field | Description |+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `state` | `validated` (reconciled with an active prompt policy) \| `disabled` (`PLUGIN_WORKLOAD_SDK_ENABLED` is off) \| `degraded` (for example provider unavailable or bootstrap not ready) \| `awaiting_policy` (host identity ready, but the operator prompt policy is absent or unusable). |+| `promptBridge`, `clientNotifications` | Booleans: which capability families the spec declares. |+| `message`, `validatedAt` | Human-readable state and the time it was first validated. |+| `bootstrapContractVersion` | `2` (static-credential SDK bootstrap) or `3` (Codex reservation-only binding). WRC writes `3` when the eagerly resolved agent provider is `codex-subscription`. |+| `bootstrapPodUid`, `bootstrapProvider`, `bootstrapModel` | The mcp-host pod and provider/model the bootstrap was proven against. |+| `policyRevision`, `policyHash`, `defaultTargetRef`, `verifiedAt` | The operator prompt policy the capability was verified against (`policyRevision` min 1, `policyHash` 64-hex). |++A matching `conditions[]` entry records the reason (for example+`FeatureFlagDisabled`, `ProviderUnavailable`, `BootstrapNotReady`,+`PolicyNotConfigured`).+### 12.3 Printer Columns```yaml@@ -3318,6 +3376,11 @@ This section describes the `WorkflowRecipePolicy` CRD and the approval workflow.**This is the single source of truth for the WorkflowRecipePolicy schema.**+> Not every field below is enforced. WRC checks only `allowContextRef`, the+> five `governance` fields, and `detection.imageAllowlist`/`imageDenylist`; the+> rest are stored but unread. See the per-field table in+> [WorkflowRecipePolicy](workflowrecipepolicy.md#spec-fields).+`spec` is the only required top-level field. The complete `spec` property set is:`description`, `allowContextRef`, `governance`, `detection`, `publication`,`deployment`, `notification`, `deprecation`. The CRD has nodiff --git a/docs/crds/workflowrecipepolicy.md b/docs/crds/workflowrecipepolicy.mdindex f9f330832..810029328 100644--- a/docs/crds/workflowrecipepolicy.md+++ b/docs/crds/workflowrecipepolicy.md@@ -2,29 +2,149 @@**API Group:** `clerum.io`**Version:** `v1alpha1`-**Scope:** Namespaced (cluster governance for recipes)-**Reconciled / enforced by:** workflow-recipes operator (WRC), typically during-reconcile before workloads are admitted+**Scope:** Namespaced (must live in `sandbox-recipes`)+**Short names:** `wrp`, `policy`+**Enforced by:** workflow-recipes operator (WRC), during each recipe reconcile## Purpose-**Governance and detection policy** for `WorkflowRecipe` deployments — cluster--or environment-wide rules that can block or constrain recipes (capability-policy, image/digest expectations, detection hooks). Pair with the+Governance rules for `WorkflowRecipe` deployments in a namespace. WRC lists+every WorkflowRecipePolicy in the recipe's own namespace and checks the recipe+against all of them before it deploys anything. Pair with the[WorkflowRecipe](workflowrecipe.md) CRD.+Things to know before you write one:++- **Namespace is fixed.** A ValidatingAdmissionPolicy in `deploy/base` rejects+ any WorkflowRecipePolicy outside `sandbox-recipes`, the namespace that stores+ WorkflowRecipe CRDs.+- **No selector.** A policy has no match or selector field. Every policy in+ `sandbox-recipes` applies to every recipe there. When several policies set+ the same limit, the recipe must satisfy each one.+- **No status.** The CRD has no status subresource. A violation shows up on+ the *WorkflowRecipe*: `status.phase: failed` and `status.message:+ "Policy violation: [<policy>] <rule>: <detail>"`. WRC does not retry or+ self-heal a policy failure. Fix the recipe spec (or the policy) to re-arm+ enforcement.+- **Many fields are not enforced yet.** The schema accepts more than WRC+ checks. The tables below mark each field as **Enforced** or **Not+ enforced**. A not-enforced field is stored but nothing reads it.+- **Nothing ships by default.** `deploy/base` ships no WorkflowRecipePolicy.+ The minikube overlay ships one dev policy (see [Example](#example)).+## Spec fields-Authoritative OpenAPI lives in:+| Field | Type | Enforced? | Description |+| ---------------------- | ------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `spec.description` | string | n/a | Free text. |+| `spec.allowContextRef` | boolean | **Enforced** | Widens the default-deny on `spec.contextRef` for agentic recipes (recipes with `spec.steps[]`). Such a recipe may reference a shared Context only if the recipe sets `spec.security.allowContextRef: true` **and** at least one policy in the namespace sets this field to `true`. Checked by control-api when a recipe is validated or submitted, and again by WRC. |+| `spec.governance` | object | partly | See [governance](#specgovernance). |+| `spec.detection` | object | partly | See [detection](#specdetection). |+| `spec.publication` | object | Not enforced | See [other blocks](#other-blocks-not-enforced). |+| `spec.deployment` | object | Not enforced | See [other blocks](#other-blocks-not-enforced). |+| `spec.notification` | object | Not enforced | See [other blocks](#other-blocks-not-enforced). |+| `spec.deprecation` | object | Not enforced | See [other blocks](#other-blocks-not-enforced). |++No field carries a schema default. `spec` is the only required top-level field.++### `spec.governance`++| Field | Type | Enforced? | Description |+| ---------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `governance.requireApproval` | boolean | **Enforced** | When `true`, WRC rejects the recipe while its `status.phase` is `candidate` or `pending-approval`. Phases past the approval gate are not re-blocked. See [Approval Workflow](workflowrecipe.md#152-approval-workflow). |+| `governance.maxWorkloadsPerRecipe` | integer | **Enforced** | Min 1. Rejects a recipe with more `spec.workloads[]` entries. The CRD already caps `workloads` at 25. |+| `governance.maxReplicasPerWorkload` | integer | **Enforced** | Min 1. Rejects any workload whose `replicas` (default 1) is higher. |+| `governance.allowedWorkloadTypes` | string[] | **Enforced** | Lowercase enum: `deployment`, `statefulset`, `cronjob`, `job`, `daemonset`. Rejects a workload whose `type` is not listed. Empty or absent means all types. |+| `governance.requiredSecurityLevel` | string | **Enforced** | `minimal` \| `standard` \| `strict`. Rejects a recipe whose `spec.security.isolationLevel` is lower. A recipe without `isolationLevel` counts as `minimal`. |++### `spec.detection`++| Field | Type | Enforced? | Description |+| ---------------------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |+| `detection.imageAllowlist` | string[] | **Enforced** | Glob patterns (`*` within a path segment, `**` across segments, `?` one character). When non-empty, every workload image must match at least one. |+| `detection.imageDenylist` | string[] | **Enforced** | Glob patterns. Any workload image that matches is rejected. |+| `detection.enabled` | boolean | Not enforced | Stored only. The allow/deny lists apply whether or not this is `true`. |+| `detection.scanOnDeploy` | boolean | Not enforced | Stored only. No image scanning runs. |+| `detection.allowedStorageClasses` | string[] | Not enforced | Stored only. PVC StorageClasses are not checked. |+| `detection.maxResourceLimits.cpu` | string | Not enforced | Stored only. Container limits are not checked. |+| `detection.maxResourceLimits.memory` | string | Not enforced | Stored only. |++The workload, replica, type, and image rules all iterate `spec.workloads[]`. A+steps-only (workflow) recipe has no workloads, so those rules pass for it.++### Other blocks (not enforced)++These fields are in the schema, but no component reads them in this release.++| Field | Type | Schema description |+| ---------------------------------------- | -------- | ------------------------------------------------------------------------- |+| `publication.registry` | string | Registry URL for recipe publication. |+| `publication.autoPublish` | boolean | Auto-publish recipes to the registry. |+| `deployment.autoPromoteAfterSeconds` | integer | Min 0. Seconds before auto-promoting from testing to active. |+| `deployment.rollbackOnFailure` | boolean | Auto-rollback on deployment failure. |+| `deployment.maxConcurrentDeploys` | integer | Min 1. Maximum concurrent recipe deployments. |+| `notification.channels` | string[] | Notification channel references. |+| `notification.events` | string[] | Enum: `deploy`, `rollback`, `failed`, `deprecated`. |+| `deprecation.gracePeriodDays` | integer | Min 0. Days before a deprecated recipe is removed. |+| `deprecation.autoDeprecateInactiveDays` | integer | Min 0. Days of inactivity before auto-deprecation. |++## Additional Printer Columns++`kubectl get wrp -n sandbox-recipes` displays: MAX-WORKLOADS+(`governance.maxWorkloadsPerRecipe`), SECURITY+(`governance.requiredSecurityLevel`), Age.++## Example++The only policy the repository ships is the minikube dev policy, applied by+`make minikube-deploy-instances`. Production overlays do not ship it, so shared+Context access for agentic recipes stays off until an operator opts in:++```yaml+apiVersion: clerum.io/v1alpha1+kind: WorkflowRecipePolicy+metadata:+ name: minikube-allow-context-ref+ namespace: sandbox-recipes+spec:+ description: >-+ Minikube dev default. Permits agentic workflows to share context between+ steps via `spec.contextRef`. Pair with a recipe that sets+ `spec.security.allowContextRef: true`.+ allowContextRef: true+```++Source: [deploy/overlays/minikube/instances/workflowrecipepolicy.yaml](../../deploy/overlays/minikube/instances/workflowrecipepolicy.yaml).++A production-style policy that uses only enforced fields:-```text-charts/clerum-crds/crds/workflowrecipepolicy.yaml+```yaml+apiVersion: clerum.io/v1alpha1+kind: WorkflowRecipePolicy+metadata:+ name: prod-guardrails+ namespace: sandbox-recipes+spec:+ description: Production limits for recipe workloads.+ governance:+ maxWorkloadsPerRecipe: 10+ maxReplicasPerWorkload: 3+ allowedWorkloadTypes: [deployment, statefulset, job]+ requiredSecurityLevel: standard+ detection:+ imageAllowlist:+ - 'registry.example.com/approved/**'+ imageDenylist:+ - '**:latest'```-Use that schema plus operator logs when authoring policies. Narrative and ops-context: [workflow-recipes-guide](../deploy/workflow-recipes-guide.md).+With this policy, a recipe that omits `spec.security.isolationLevel` fails+with `requiredSecurityLevel`, because the omitted level counts as `minimal`.## Related-- [WorkflowRecipe](workflowrecipe.md)+- [WorkflowRecipe](workflowrecipe.md) — §8.6 (contextRef validation) and §15+ (approval and governance)+- [Workflow recipes guide](../deploy/workflow-recipes-guide.md)- [packages/workflow-recipe-capability-policy](../../packages/workflow-recipe-capability-policy/)+- [CRD index](README.md)diff --git a/docs/how-to/manage-users-and-teams.md b/docs/how-to/manage-users-and-teams.mdnew file mode 100644index 000000000..88ecb3b90--- /dev/null+++ b/docs/how-to/manage-users-and-teams.md@@ -0,0 +1,198 @@+# How to: manage users, teams, roles, and agent access++evenfire has two separate kinds of people:++- **Members** are Desktop App users. They belong to **teams**, and each team+ membership has a **team role**. Members and teams decide who can use which+ agents from the [Desktop App](use-the-desktop-app.md).+- **Control admins** are operators who sign in to the+ [Control UI](../surfaces/control-ui.md). They live in a separate account pool+ and are not team members unless you also give them Desktop App access.++Both are managed in **Control UI → Users & Teams**.++## Where it lives++| Screen | Path | What you do there |+| ------------- | ----------------------------------- | -------------------------------------------------------------------------------------- |+| Members tab | `/users-and-teams/users` | List members and pending member invitations; create, open, or delete a member |+| Teams tab | `/users-and-teams/teams` | List teams; create, open, or delete a team |+| Admins tab | `/users-and-teams/admins` | List control admins and pending admin invitations; invite or delete an admin |+| Invite admin | `/users-and-teams/admins/new` | The admin invitation wizard |+| Member detail | `/users-and-teams/users/<id>/<tab>` | Tabs: **Contact**, **Approval DMs**, **Communication Channels**, **Teams**, **Agents** |+| Team detail | `/users-and-teams/teams/<id>/<tab>` | Tabs: **Members**, **Agents** |++`/users-and-teams` opens the Members tab. Older `/profile-admin/*` links+redirect here, and the old `contexts` and `access` tab URLs on member and team+pages redirect to the **Agents** tab.++## Team roles++Every team membership has one of three roles. The API and database store the+value; the Control UI shows a label.++| Stored value | Control UI label | Invite members | Invite someone as `admin` | Change roles, remove members |+| ------------ | ---------------- | -------------- | ------------------------- | ---------------------------- |+| `admin` | Leader | Yes | Yes | Yes |+| `inviter` | Inviter | Yes | No | No |+| `member` | Participant | No | No | No |++The team detail Members table shows the same thing as two read-only columns,+**Can Invite Members** and **Can Delete Members**. The role editor sets the+role through those two checkboxes: delete implies invite.++These roles govern what a member can do **for their own teams** through the+member-facing API (`/external/members/*` and `/external/teams/*`), which the+[profile UI](../surfaces/profile-ui.md) uses. In that API:++- An `admin` or `inviter` can send, resend, and revoke member invitations for+ teams where they hold that role.+- Only an `admin` can change another member's role or remove them from the+ team. The `/external/members/*` routes reject changes to your own+ membership.+- An `admin` can delete another member's account only if they are `admin` on+ **every** team that member belongs to.++Control admins are not limited by team roles. Every change you make in the+Control UI goes through the control-admin API, whatever team role the target+holds.++### The global `users.role` column++The `users` table also has a global `role` column (`admin`, `operator`,+`reviewer`, `finance`, or `user`; default `user`). No Control UI screen or API+route sets it. It is **not** the team role and **not** control-admin status.+The only code that reads it is a database migration that gives users with+`role = 'admin'` the `mcp-host/standalone` workflow trigger grant.++## Members and teams++**Create a member** (Members tab → **Create member**) creates a pending+invitation and sends the invitation email. You can add the person to teams+with a role per team. The member's Desktop App access starts when they accept+the invitation and set a password.++**Create a team** (Teams tab → **Create team**), then add people on the team's+**Members** tab:++- **Existing member** adds a current member straight away with the role you+ pick.+- **Invite by email** sends a member invitation for this team.++Pending member invitations appear on the Members tab, where you can resend or+cancel them. Member invitations expire after **48 hours**.++### Invitations need a registration service++Invitation emails are not sent by control-api itself. control-api hands them+to a member registration service, and that service is **not in this+repository**. By default (`CONTROL_API_MEMBER_REGISTRATION_MODE` unset, which+means `remote`), the base ConfigMap points at+`member-registration-service.registration.svc.cluster.local`, which a+self-hosted install does not have. Until you set up one of these, sending an+invitation fails with an error:++- Set `CONTROL_API_MEMBER_REGISTRATION_MODE=hosted` to send through evenfire's+ shared registration hub.+- Run your own member registration service in `remote` mode.++See [Member invitations on a self-hosted deployment](member-invitations-self-hosted.md)+for both paths.++## Control admins++Control admins are stored in their own table (`control_admin_users`), separate+from members. Each one has the single role `admin` and a status of `active` or+`disabled`.++### Invite a control admin++Admins tab → **Invite admin** opens `/users-and-teams/admins/new`:++1. Enter the email. The email link opens the Control UI, where the invitee+ chooses a username and password.+2. Optionally tick **Create access to Desktop App** (`createDesktopAccess`).+ Pick teams and a role for each. evenfire then also creates a member+ invitation for those teams, and one email covers both.+3. Send. Admin invitations expire after **48 hours**.++You can also start from a member: a member's row menu has **Create+administrator access**, which opens the same wizard for that email. It skips+the Desktop App step because the person is already a member.++Admin invitations go through the same registration service as member+invitations.++### Hand over an admin seat with `replaceInviter` (API only)++`POST /api/v1/admin/control-admin-invitations` accepts an optional boolean+`replaceInviter`. No Control UI screen sets it.++When `replaceInviter` is `true` and the invitee accepts, the inviting admin's+seat is handed over in the same transaction:++- If the inviter also has a member account, their team roles are copied to+ the invitee's member account or pending Desktop App invitation. The higher+ role wins, so the invitee is never downgraded. The inviter's member account+ is then retired.+- The inviter's control-admin account is retired, the same way **Delete admin**+ does it.+- The inviter's other pending admin invitations, and their paired Desktop App+ invitations, are revoked.++Acceptance is refused with `replace_inviter_receiver_missing` if the inviter's+member account holds team roles and nobody can receive them. For example, the invitee has no+member account and no pending Desktop App invitation. If the inviter is no+longer active when the invitee accepts, the hand-over is skipped and the+invitee simply becomes a new admin.++## Agent access++An agent (Host) is usable from the Desktop App only by people who have been+given access. Grant it from either side:++- **Agent detail → Access tab** (`/agents/<name>/access`). It has two+ sub-tabs: **Members** and **Teams**. Use **Add member** or **Add team** to+ grant access, and the row menu's **Revoke access** to remove it.+- **Member or team detail → Agents tab.** This is the same grant, seen from+ the person or the team.++A member can use an agent if it is granted to them directly, or to the team+they are currently working in. control-api checks the grant when it resolves+the agent for that member. For a team grant it also checks that the member is+still in that team.++The grant APIs are `PUT /api/v1/admin/users/<id>/agents` and+`PUT /api/v1/admin/teams/<id>/agents`. They replace the full list and need+`expectedCurrentAgentNames` (the list you read). Without it the call fails with+`428`. If the list changed since you read it, the call is rejected instead of+overwriting another admin's change.++## Removing people and teams++There is no "deactivate" for members. The options are:++- **Remove from a team** (team detail → member row → **Remove member**). This+ ends that one membership. The account stays.+- **Delete member** (Members tab or member detail). Team memberships are+ removed first. If the member was the only person on some teams, you can tick+ **Delete empty teams too**. The account is hard-deleted, or kept as a+ retired record if it was ever linked to a control admin. Its approval DM+ accounts are disabled either way.+- **Delete a team** (Teams tab → **Delete**). The API only deletes a team with+ no active members, and returns `team_not_empty` otherwise. Remove or delete+ its members first. Deleting the team also removes its pending invitations+ and its agent and Context grants.+- **Delete admin** (Admins tab). This removes the admin's Control UI access+ immediately: their sessions end and their EvenDrive operator link is+ revoked. The record is kept as `disabled` for audit and is hidden from the+ list. You cannot delete your own admin account. Deleting an admin does+ not delete a member account they also hold.++## Related++- [Member invitations on a self-hosted deployment](member-invitations-self-hosted.md)+- [Use the Desktop App](use-the-desktop-app.md)+- [Control UI](../surfaces/control-ui.md)+- [Profile UI](../surfaces/profile-ui.md)+- [Configure approvals](configure-approvals.md)diff --git a/docs/how-to/token-budgets-and-usage.md b/docs/how-to/token-budgets-and-usage.mdindex c1e5bbc90..072b21ee1 100644--- a/docs/how-to/token-budgets-and-usage.md+++ b/docs/how-to/token-budgets-and-usage.md@@ -1,73 +1,144 @@# How to: track usage and set token budgets-Every LLM call evenfire makes is metered — tokens and cost, attributed to the-agent, team, user, provider, and model behind it. This guide covers where that-usage shows up, how to turn on **budgets** to cap it, and how a budget's `block`-vs `warn` decision actually behaves.+Every LLM call evenfire makes is metered: tokens and, once you set prices,+cost. Each call is attributed to the agent, team, user, provider, model, and+other dimensions behind it. This guide covers where that usage shows up, how+to turn on **budgets** to cap it, and how a budget's `block` vs `warn` decision+actually behaves.## What's tracked-Token usage (input, output, cache) and — once you set prices — cost, rolled up-by dimension: **agent** (Host), **team**, **user**, **provider**, and **model**.-Usage is recorded whether or not budgets are enabled.+Token usage (input, output, cache read, cache write) is rolled up by the+dimensions in the table below. Cost is derived from token counts and the rates+under **LLM Prices**. Usage is recorded whether or not budgets are enabled.++| Dimension | Control UI label | What it is |+| ----------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |+| `host_ref` | Agent | The agent (Host) that made the call |+| `context_ref` | Connector scope | The Context the agent is bound to |+| `team_id` | Team | The team the call is attributed to |+| `user_id` | User | The Desktop App user. Set for Desktop App calls only |+| `provider` | Provider | The LLM provider, such as `claude` or `openai` |+| `model` | Model | The model ID |+| `llm_secret_name` | Secret | The LLM credential secret the call used |+| `source_kind` | Source | What started the call: `channel`, `desktop`, `workflow`, `cron`, `plugin_workload_sdk`, or `unknown` |+| `recipe_name` | Recipe | The workflow recipe (plugin) behind the call |+| `cron_job_id` | Cron job | The agent's scheduled job. Set for cron calls only |++For channel calls that carry no team, the team is resolved from the agent's+Context: the team bound to that Context earliest wins.## Where to see it-In the **Control UI → Cost & Usage → Usage** tab: token totals and a-stacked-area chart you can break down by agent, team, user, provider, or model.-See the [Control UI tour](../surfaces/control-ui.md) for the screens. Cost is-derived from the rates under the **LLM Prices** tab.+Open **Control UI → Cost & Usage** (`/cost-and-usage`). It has three tabs:++| Tab | Path |+| ------------- | ------------------------------- |+| Usage | `/cost-and-usage/usage` |+| Token Budgets | `/cost-and-usage/token-budgets` |+| LLM Prices | `/cost-and-usage/llm-prices` |++The **Usage** tab shows token totals and a stacked-area chart over the last+24 hours, 7 days, or 30 days. **Break down by** splits the chart by Team,+Recipe, Model, Provider, Agent (host), LLM secret, Desktop user, or Source+kind. Some breakdowns filter by source:++- **Recipe** shows workflow calls only.+- **Agent (host)** leaves out workflow calls, so recipe Hosts do not show up+ as agents.+- **Desktop user** shows Desktop App calls only.++See the [Control UI tour](../surfaces/control-ui.md) for the screens.## Turn budgets on-Budgets are **off by default**. Set `CLERUM_BUDGETS_ENABLED=true` on-**`mcp-host`**, which is where enforcement runs. With the flag off, usage is-still tracked and budgets can still be created — nothing is enforced until the-flag is on.+Budget enforcement is **off by default** in code. Set+`CLERUM_BUDGETS_ENABLED=true` on **`mcp-host`**, which is where enforcement+runs. The minikube overlay already sets it to `true` in its `mcp-host-config`+ConfigMap. With the flag off, usage is still tracked and budgets can still be+created, but nothing is enforced.## Create a budget-In **Control UI → Cost & Usage → Token Budgets**, add a budget with:--- **Scope** — which usage it covers: any combination of dimensions such as- agent (Host), team, user, provider, and model. Leave it empty to cap- **everything** (global).-- **Unit** — `tokens` or `cost`. A `cost` budget needs a currency and **priced- models**: add rates under **LLM Prices** first. Creating a cost budget that- pins unpriced models is rejected, so it cannot silently under-count.-- **Limit** and **period** — the cap, over a `daily`, `weekly`, or `monthly`- window.-- **Enforcement** — `block` or `warn` (see below).+Go to **Cost & Usage → Token Budgets → New budget** (`/cost-and-usage/token-budgets/new`)+and fill in these fields:++| Field | What it does |+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| **Name** | A label for the budget |+| **Unit** | `tokens` (raw count) or `cost` (currency). A `cost` budget needs a currency and **priced models**. Add rates under **LLM Prices** first. Creating a cost budget whose scope names an unpriced model is rejected (`unpriced_models`), so it cannot silently under-count. |+| **Limit amount** | The cap for one period |+| **Period** | `daily`, `weekly`, or `monthly`. Calendar-aligned: spend resets at the start of each period. |+| **Timezone** | Fixed to UTC in this version |+| **Min remaining to start** | A new task is denied when the remaining amount is below this. Default `0`, which means a task can start while anything remains. |+| **Max per task** | Optional. A per-task cap. See [Per-task cap](#per-task-cap). |+| **Enforcement** | `warn` or `block`. See below. |+| **Enabled** | Disabled budgets are ignored for spend and checks |+| **Scope** | Which usage the budget covers. Leave it empty to cap **everything** (a global budget). |++### Scope++A scope is a set of dimensions, each with one or more values. Different+dimensions are ANDed. Values within one dimension are ORed. For example,+team `A` and provider `claude` or `openai` matches only team `A`'s calls to+either provider.++The scope editor in the form offers six dimensions: Provider, Model, Team,+User, Agent, and Secret. The budgets API (`/api/v1/admin/budgets`) also+accepts `context_ref`, `source_kind`, `recipe_name`, and `cron_job_id`. A+budget saved with those through the API is shown with its full scope in the+Control UI. Any other scope key is rejected.++A scope on `user_id` only matches Desktop App calls, because those are the+only calls that carry a user.## `block` vs `warn`-- **`warn`** — observation only. The agent's call always proceeds; the budget- just records that the scope is over its limit.-- **`block`** — when the scope is over its limit, the agent's next task is- denied (`budget_exceeded`) and stops rather than spending more.+Every matching budget is checked once per task. The most restrictive one wins.++- **`warn`** is observation only. The task always proceeds. When the scope is+ under its minimum, control-api logs it.+- **`block`** denies the next task (`budget_exceeded`) when the remaining+ amount is below **Min remaining to start**. The task stops instead of+ spending more.++### Per-task cap++**Max per task** applies to `block` budgets only. When several matching+budgets set it, the smallest cap per unit applies. mcp-host tracks the tokens,+or cost, that one task has used and stops the task before its next LLM call+once it goes over the cap.++When the remaining amount is already below one task's cap, control-api also+reserves that cap for the starting task. That way two tasks that start at the+same moment cannot both spend the last of the budget.## What happens on failureThe two failure modes are deliberately different:-- If **`mcp-host` cannot reach** control-api's budget check at all (a network or- service outage), the call **fails open** — the agent proceeds rather than- being blocked by infrastructure it cannot control.-- If control-api **is** reachable but **cannot compute** a `block` budget's- spend, it **fails closed** — the task is denied (`budget_eval_error`), because- it cannot prove the task is under the cap.+- If **`mcp-host` cannot get a usable answer** from control-api's budget check+ (network error, timeout, a non-200 response, or a malformed body), the task+ **fails open** and proceeds. mcp-host logs `budget_check_failed`. It retries+ once with a fresh token on `401` first, so a token rotation does not let a+ task skip an exceeded budget.+- If control-api answers but **cannot compute** a `block` budget's spend, it+ **fails closed**. The task is denied (`budget_eval_error`), because+ control-api cannot prove the task is under the cap.A `warn` budget never blocks in either case.## What budgets are not-Budgets are **cost control, not a security boundary**. They cap spend; they do-not authorize, isolate, or gate anything — that is the job of Contexts,-NetworkPolicies, and [approvals](configure-approvals.md). A cost budget is only-as accurate as the prices under **LLM Prices**.+Budgets are **cost control, not a security boundary**. They cap spend. They do+not authorize, isolate, or gate anything: that is the job of Contexts,+NetworkPolicies, [guardrails](configure-guardrails.md), and+[approvals](configure-approvals.md). A cost budget is only as accurate as the+prices under **LLM Prices**.## Related-- [Control UI](../surfaces/control-ui.md) — the Cost & Usage, LLM Prices, and Token Budgets screens-- [Configure approvals](configure-approvals.md) — the other half of governed action-- [Add an MCP server](add-mcp-server.md) — give an agent tools to spend against+- [Control UI](../surfaces/control-ui.md): the Cost & Usage screens+- [LLM providers](../llm-providers/README.md): the providers and secrets usage is attributed to+- [Configure approvals](configure-approvals.md): the other half of governed action+- [Add an MCP server](add-mcp-server.md): give an agent tools to spend againstdiff --git a/docs/llms.txt b/docs/llms.txtindex 48ad80066..22983a256 100644--- a/docs/llms.txt+++ b/docs/llms.txt@@ -42,6 +42,7 @@- Configure approvals: how-to/configure-approvals.md- Add MCP server: how-to/add-mcp-server.md- Desktop setup & updates (environments, invitation, updates): how-to/desktop-setup-and-updates.md+- Manage users and teams (roles, control admins, agent access): how-to/manage-users-and-teams.md- Member invitations on self-hosted (hosted mode vs your own service): how-to/member-invitations-self-hosted.md- Track usage & set token budgets: how-to/token-budgets-and-usage.md- Connect a self-hosted deployment to the registry: how-to/connect-to-registry.md@@ -69,6 +70,8 @@## Reference+- Configuration switches (feature flags, base vs minikube): reference/configuration.md+- Plugin UI SDK (window.clerum for embedded plugin apps): reference/plugin-ui-sdk.md- CRD index: crds/README.md- Host: crds/host.md- Context: crds/context.md@@ -136,5 +139,7 @@- ../control-ui/README.md — admin console routes, config, tests- ../desktop-app/README.md — Electron client, scopes, endpoint table, E2E- ../profile-ui/README.md — profile and invitation flows+- ../codex-llm-proxy/README.md — Codex subscription model proxy+- ../grok-llm-proxy/README.md — Grok subscription model proxy- ../rpc-proxy/README.md — external JWT-gated gateway for desktop traffic- ../external-rest-api/README.md — auth, profiles, teams, RPC-token brokeragediff --git a/docs/reference/configuration.md b/docs/reference/configuration.mdnew file mode 100644index 000000000..3f8a6c0a0--- /dev/null+++ b/docs/reference/configuration.md@@ -0,0 +1,77 @@+# Configuration reference: feature switches++Most evenfire behaviour is on by default. This page lists the **switches**+whose value differs between `deploy/base` and the minikube overlay, or that+are off by default, so you can see what a fresh `deploy/base` install does+not do yet.++Full per-service variable lists live in each service's README (see+[Where every variable is documented](#where-every-variable-is-documented)).++> **`mcp-host-config` is not in `deploy/base`.** host-context-controller loads+> the `mcp-host-config` ConfigMap into every agent pod, but only the minikube+> overlay ships one (`deploy/overlays/minikube/configmaps/mcp-host-config.yaml`).+> Without it, mcp-host uses its code defaults, so the mcp-host rows below are+> off until your overlay provides that ConfigMap.++Boolean switches accept only the string `true` unless noted.++## Off in `deploy/base`, on in the minikube overlay++| Switch | Service (where to set it) | What it turns on | Guide |+| -------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |+| `MCP_OAUTH_BROKER_ENABLED` | control-api (`control-api-config`) | OAuth sign-in for MCP connectors; without it OAuth connectors never receive a token | [Connect an OAuth connector](../how-to/connect-oauth-connector.md) |+| `CONTROL_API_OAUTH_CALLBACK_BASE_URL` | control-api (`control-api-config`) | Browser-reachable origin for OAuth callbacks (a URL, not a boolean) | [Connect an OAuth connector](../how-to/connect-oauth-connector.md) |+| `CONTROL_API_CODEX_SUBSCRIPTION_ENABLED` | control-api (`control-api-config`) | ChatGPT (Codex) subscription connections | [Use a subscription](../how-to/connect-llm-subscription.md) |+| `CODEX_LLM_PROXY_EXECUTION_ENABLED` | codex-llm-proxy (`codex-llm-proxy-config`) | Model calls through the Codex proxy | [Use a subscription](../how-to/connect-llm-subscription.md) |+| `MCP_HOST_CODEX_SUBSCRIPTION_ENABLED` | mcp-host (`mcp-host-config`) | The `codex-subscription` provider in agents | [Use a subscription](../how-to/connect-llm-subscription.md) |+| `CONTROL_API_GROK_SUBSCRIPTION_ENABLED` | control-api (`control-api-config`) | Grok subscription connections (mcp-host's Grok flag is injected per Host) | [Use a subscription](../how-to/connect-llm-subscription.md) |+| `GROK_LLM_PROXY_EXECUTION_ENABLED` | grok-llm-proxy (`grok-llm-proxy-config`) | Model calls through the Grok proxy | [Use a subscription](../how-to/connect-llm-subscription.md) |+| `WRC_GROK_SUBSCRIPTION_ENABLED` | workflow-recipes (Deployment env) | Grok in WorkflowRecipe steps | [Use a subscription](../how-to/connect-llm-subscription.md) |+| `CLERUM_BUDGETS_ENABLED` | mcp-host (`mcp-host-config`) | Token budget checks before tasks | [Track usage & set budgets](../how-to/token-budgets-and-usage.md) |+| `CLERUM_MEMORY_ENABLED` | mcp-host (`mcp-host-config`) | Agent workspace memory | [mcp-host README](../../mcp-host/README.md) |+| `CLERUM_SESSION_SEARCH_ENABLED` | mcp-host (`mcp-host-config`) | Session search for agents | [mcp-host README](../../mcp-host/README.md) |+| `CONTROL_API_DESKTOP_GFS_OPERATOR_LINKING_ENABLED` | control-api (`control-api-config`) | Makes the initial Desktop admin an EvenDrive operator on self-hosted installs | [GFS operator parity](../architecture/gfs-desktop-operator-parity.md) |+| `PLUGIN_WORKLOAD_SDK_ENABLED` | workflow-recipes (Deployment env) | The Plugin Workload SDK for recipe workloads | [Plugin Workload SDK upgrade](../deploy/plugin-workload-sdk-upgrade.md) |+| `WRC_ENABLE_SNIPPET_RUNTIME` | workflow-recipes (Deployment env) | Snippet-based workflow coordinators | [WorkflowRecipes operations](../deploy/workflow-recipes-guide.md) |+| `WRC_ENABLE_CUSTOM_COORDINATOR_IMAGE` | workflow-recipes (Deployment env) | Custom coordinator images (digest-pinned) | [Workflow SDK](../../packages/workflow-sdk/README.md) |+| `CLERUM_NETWORK_POLICY_ENFORCEMENT_CONFIRMED` | workflow-recipes (Deployment env) | Confirms the cluster CNI enforces NetworkPolicies (enforcement mode is `required` in both) | [WorkflowRecipes operations](../deploy/workflow-recipes-guide.md) |+| `REGISTRY_CONNECTION_MODE` | control-api (`control-api-config`) | `self-hosted` in minikube; unset means `managed` | [Connect to the registry](../how-to/connect-to-registry.md) |+| `CONTEXT_MAPPER_GFSC_UPLOAD_V2_ENABLED` | host-context-controller (Deployment env) | The chunked EvenDrive upload protocol | [Shared & global files](../how-to/shared-and-global-files.md) |++## Off in both `deploy/base` and the minikube overlay++| Switch | Service | What it turns on |+| ----------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------- |+| `CONTROL_API_ENFORCE_IMAGE_ALLOWLIST` | control-api | Reject connector images that are not on the allowlist (otherwise audit mode) |+| `CONTEXT_MAPPER_ENFORCE_IMAGE_ALLOWLIST` | host-context-controller | Block non-allowlisted connector images at reconcile (otherwise logged and allowed) |+| `SUBSCRIPTION_CATALOG_SYNC_CRON_ENABLED` | control-api | Periodic model-catalog refresh for subscription connections |+| `OAUTH_PROACTIVE_REFRESH_CRON_ENABLED` | control-api | Refresh remote-connector OAuth tokens before they expire |+| `TRACING_APPROVAL_PROMPT_HISTORY_ENABLED` | control-api | Keep prompt history in approval traces |+| `CLERUM_PERSONALIZATION_ENABLED` | mcp-host | Identity files from `CLERUM_IDENTITY_SEED` in dev mode (Hosts use `spec.personalization`) |+| `MCP_PROXY_ENABLED` | mcp-host | Route MCP traffic through mcp-proxy |++## On by default++| Switch | Service | Note |+| ------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------- |+| `CLERUM_ENABLE_APPROVAL` | mcp-host | Human approval gate ([Configure approvals](../how-to/configure-approvals.md)) |+| `LLM_CATALOG_SYNC_CRON_ENABLED` | control-api | models.dev catalog sync; new rows arrive disabled for review |+| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | channel-reader | Send generated files back to channels |+| `WRC_ENABLE_DETERMINISTIC` | workflow-recipes | Deterministic workflow steps |+| `WORKFLOW_APPROVAL_NOTIFICATION_DELIVERY_ENABLED` | control-api | Deliver workflow approval notifications |++## Where every variable is documented++| Service | Reference |+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |+| mcp-host (agent runtime) | [mcp-host/README.md](../../mcp-host/README.md) |+| control-api | [control-api/README.md](../../control-api/README.md) |+| host-context-controller | [host-context-controller/README.md](../../host-context-controller/README.md) |+| workflow-recipes | [workflow-recipes/README.md](../../workflow-recipes/README.md) |+| channel-reader | [channel-reader/README.md](../../channel-reader/README.md) |+| rpc-proxy | [rpc-proxy/README.md](../../rpc-proxy/README.md) |+| external-rest-api | [external-rest-api/README.md](../../external-rest-api/README.md) |+| codex-llm-proxy / grok-llm-proxy | [codex-llm-proxy/README.md](../../codex-llm-proxy/README.md), [grok-llm-proxy/README.md](../../grok-llm-proxy/README.md) |+| LLM providers and models | [Configure LLM providers](../deploy/llm-providers.md) |+| Rate limits | [Administrative rate limits](../architecture/administrative-rate-limits.md) |diff --git a/docs/reference/plugin-ui-sdk.md b/docs/reference/plugin-ui-sdk.mdnew file mode 100644index 000000000..048bc59f4--- /dev/null+++ b/docs/reference/plugin-ui-sdk.md@@ -0,0 +1,378 @@+# Plugin UI SDK (`window.clerum`)++A plugin can ship a web app that the Desktop App shows under **Apps**. Inside+that app, the Desktop App exposes a small JavaScript API on `window.clerum`. The+app uses it to ask the user for access to their information (who they are,+their team, agents, contexts, MCP servers, shared files), to follow the app's+light or dark theme, and to send desktop notifications.++There is no npm package for this API. Your app's JavaScript calls+`window.clerum` directly, and the Desktop App injects it.++SDK version `1.0.0`, wire protocol `1`.++## Where it is available++The API on this page is injected only into a **sandbox UI embedded in the+Desktop App**: the web app a recipe declares in `spec.ui`. It is not available+in the Control UI, in Profile UI, in a normal browser tab, or in a recipe's+backend workloads. The Desktop App's own interface has a separate, trusted+`window.clerum` bridge with a different shape (see+[Desktop App § Electron security posture](../surfaces/desktop-app.md#electron-security-posture));+plugins cannot reach it.++A recipe declares one sandbox UI by pointing `spec.ui.workloadRef` at a+`type: deployment` workload and naming its HTTP `port`. See+[WorkflowRecipe § Sandbox UI (`spec.ui`)](../crds/workflowrecipe.md#316-sandbox-ui-specui)+for the fields and validation rules, and the+[recipe authoring guide](../agents/CLERUM_WORKFLOW_RECIPE_GUIDE.md#6-sandbox-ui-specui)+for build and image requirements.++The Desktop App loads the UI through `rpc-proxy` into its own+`WebContentsView` and attaches the SDK as that view's preload script. Each+mounted UI is registered with the Desktop App under the plugin id+`<recipeNamespace>/<recipeName>`. The plugin never says who it is; the Desktop+App derives the id from the view that sent the call.++Always feature-detect, so the same UI still works outside the Desktop App:++```js+const sdk = window.clerum && window.clerum.sdk+if (!sdk) {+ // Not running inside the Desktop App. Render without the SDK.+}+```++## Response shape++Every SDK method except `on` and `onOauthCompleted` returns a promise that+resolves to one of two shapes. It does not reject for a refused call.++```ts+type PluginSdkResponse<T> =+ | { ok: true; data: T }+ | { ok: false; error: { code: string; message: string; retryable: boolean } }+```++`message` is safe to show to the user. It never carries upstream error bodies.+`retryable` is `true` when the same call may succeed later without the user+doing anything (for example, after a rate limit).++## API surface++### `clerum.sdk`++| Member | Returns | Notes |+| ----------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `sdk.version` | `'1.0.0'` | String constant. |+| `sdk.protocol` | `1` | Number constant. |+| `sdk.capabilities()` | `{ capabilities: string[], version: string }` | The capability ids this Desktop build implements. Use it to degrade gracefully on an older Desktop App. |+| `sdk.requestPermissions(ids)` | `{ granted: Record<string, boolean>, all: boolean }` | Asks for 1 to 8 capabilities in **one** consent prompt. Shows a prompt only for ids that are not already granted. A partial grant is a normal result, not an error. |+| `sdk.permissions(ids?)` | `{ granted: Record<string, boolean> }` | Reads grant state **without** prompting. With no argument it reports every capability. Up to 8 ids when you pass a list. |+| `sdk.on(callback)` | an unsubscribe function | Receives [events](#events). |++`requestPermissions` and `permissions` return `invalid_request` for an empty+list (for `requestPermissions`), more than 8 ids, a duplicate id, a non-string+entry, or an unknown capability id.++### Capability methods++Each method below sends one capability call. If the capability needs consent+and the user has not granted it yet, the call itself opens a one-row consent+prompt. Call `requestPermissions` first so the user sees one prompt for+everything your app needs.++| Method | Capability id | Consent |+| ----------------------------------------------------- | ---------------------- | ------- |+| `clerum.identity.get()` | `identity.read` | Yes |+| `clerum.org.get()` | `org.read` | Yes |+| `clerum.agents.list()` | `agents.read` | Yes |+| `clerum.contexts.list()` | `contexts.read` | Yes |+| `clerum.mcp.list()` | `mcp.read` | Yes |+| `clerum.gfs.list({ drive?, resourceId?, cursor? })` | `gfs.list` | Yes |+| `clerum.gfs.read({ uri, as })` | `gfs.read` | Yes |+| `clerum.gfs.open(uri)` | `gfs.open` | No |+| `clerum.theme.get()` | `theme.read` | No |+| `clerum.notifications.notify({ title, body?, ref? })` | `notifications.notify` | Yes |++### Legacy methods++These two predate the SDK and are kept unchanged.++| Method | What it does |+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `clerum.requestSessionRefresh()` | Asks the Desktop App to mint a fresh embed session cookie, for when a fetch or SSE stream gets a `401` between scheduled refreshes. Limited to one refresh per 30 seconds per view; a refused call rejects the promise. |+| `clerum.onOauthCompleted(callback)` | Calls `callback({ oauthClientId, provider })` when an OAuth connect flow started from this UI finishes. Returns an unsubscribe function. See the [OAuth embed lifecycle](../agents/CLERUM_WORKFLOW_RECIPE_GUIDE.md#73-embed-lifecycle-canonical). |++## Capabilities++Every capability goes through the user's own Desktop session, so Control API+authorizes it exactly as it would for the Desktop App's own pages. Consent is+an extra gate on top of what the user can already see, never a way around it.+Each capability returns a reduced view of the data, listed below.++The **Prompt text** column is what the user reads in the consent prompt and in+Settings for capabilities that need consent. Your app cannot change it.+`gfs.open` and `theme.read` never prompt and never appear as grants.++| Capability | Returns (`data`) | Consent | Prompt text |+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |+| `identity.read` | `{ userId, email, name }`. No profile picture URL. | Yes | See who you are. _Your name, email address, and user id._ |+| `org.read` | `{ teamId, teamName, role }` for the user's current team. | Yes | See your current team. _Its name and your role in it._ |+| `agents.read` | `{ agents: [{ id, name, contextRef, provider, mcpServers }] }`. `mcpServers` is a list of server names. `contextRef` and `provider` can be `null`. | Yes | See the agents you have access to. _Their names and which MCP servers they use._ |+| `contexts.read` | `{ contexts: [{ id, scope }] }`, where `scope` is `'user'` or `'team'`. | Yes | See the contexts you have access to. _The names of the contexts available to you._ |+| `mcp.read` | `{ servers: [{ name, agents }] }`. `agents` lists the user's agents that can call that server. Server URLs are removed. | Yes | See the MCP servers you have access to. _Their names and which of your agents can call them._ |+| `gfs.list` | `{ items: [{ resourceId, gfsUri, name, kind, bytes, version }], nextCursor }`. Without `resourceId`, lists the shared files the user can access; with it, lists that folder's children. | Yes | See the shared files you have access to. _Their names, folders, and sizes. It will not be able to open them._ |+| `gfs.read` | `as: 'text'`: `{ gfsUri, name, bytes, as, mimeType: 'text/plain', text }`. `as: 'dataUrl'`: `{ gfsUri, name, bytes, as, mimeType, dataUrl }`. | Yes | Open shared files you have access to. _It will be able to read the contents of any file you can read._ |+| `gfs.open` | `{ opened: boolean }`. Opens the file in the Desktop App's own viewer, over the plugin. The plugin never sees the file. | No | Open a shared file in the Evenfire viewer. _Shows you a file you already have access to. The plugin does not see it._ |+| `theme.read` | `{ theme: 'light' \| 'dark' }`. Default `'dark'`. | No | See the app appearance. _Whether the desktop app is in light or dark mode._ |+| `notifications.notify` | `{ delivered: boolean, reason?: 'suppressed' \| 'unsupported' }`. | Yes | Send you notifications. _It will be able to get your attention while you work elsewhere._ |++### Parameters and limits per capability++- **No-parameter capabilities** (`identity.read`, `org.read`, `agents.read`,+ `contexts.read`, `mcp.read`, `theme.read`) return `invalid_request` if you+ pass any parameter.+- **`gfs.list`** accepts only `drive` (max 64 characters), `resourceId` (max 128) and `cursor` (max 512). Pass the previous `nextCursor` to get the next+ page.+- **`gfs.read`** requires `uri` (a `gfs://` link, max 2048 characters) and `as`+ (`'text'` or `'dataUrl'`).+ - `as: 'text'` refuses files over 2 MB (`payload_too_large`) and files that+ are not valid UTF-8 (`invalid_request`).+ - `as: 'dataUrl'` is for images only. It refuses files over 10 MB and checks+ the file's actual bytes, not its name: only PNG, JPEG, GIF, WebP and AVIF+ pass. SVG is refused on purpose; ship vector art in your own bundle.+- **`gfs.open`** requires a `gfs://` uri. A failure returns `opened: false`+ with no reason, so a missing file and a file the user cannot access look the+ same. An `<a href="gfs://…">` link in your UI does the same thing as+ `gfs.open` and shares its rate limit.+- **`notifications.notify`** requires `title` (max 120 characters); `body` (max 400) and `ref` (max 256) are optional. Control characters are replaced with+ spaces. The Desktop App always prefixes the title with your app's title+ (`<app title> — <title>`), so a notification cannot pose as Evenfire or as+ another plugin. It is not shown (`delivered: false, reason: 'suppressed'`)+ when the user is already looking at your app. When the user clicks it, the+ Desktop App comes to the front and your app gets a `notification.clicked`+ event carrying your `ref`.++## Events++`clerum.sdk.on(callback)` delivers these events to every mounted surface of+your plugin:++| Event | Payload | When |+| ---------------------- | -------------------------------------- | ------------------------------------------------------------------------------- |+| `theme.changed` | `{ type, theme: 'light' \| 'dark' }` | The Desktop App's theme changes. |+| `permission.changed` | `{ type, capability, granted: false }` | The user revokes a grant in Settings. Sent immediately, while your app is open. |+| `session.changed` | `{ type, authenticated: boolean }` | The user logs in or out of the Desktop App. |+| `notification.clicked` | `{ type, ref: string \| null }` | The user clicks a notification your app sent. |++## Consent++### The prompt++The consent prompt is drawn by the Desktop App, not by your app. While it is+open, the Desktop App hides your app's view, so a plugin cannot fake the prompt+or draw over it.++- The heading is **`<app title>` wants access to your information**. Every+ other word comes from the Desktop App's own capability list.+- Rows are sorted most sensitive first (personal data, then workspace data) and+ start checked. The user unchecks rows to grant only part of a request.+- **Allow** grants the checked rows. **Deny** or **Escape** denies all rows.+- A prompt nobody answers within 120 seconds counts as a denial.+- Only one prompt is shown at a time, across all plugins. The prompt waits until+ a Desktop window is visible and focused.++### Prompt limits++- A plugin can show at most **3 prompts per mount**. After that, every+ ungranted capability is denied until the user reopens the app.+- There are at least 10 seconds between two prompts from the same plugin.+- From the second prompt on, the prompt tells the user how many times this+ plugin has asked this session.+- A **denial** lasts for the current mount only: the plugin is not asked again+ for that capability until the user closes and reopens the app. A mis-click is+ not a permanent lockout.+- A **grant** lasts until the user revokes it.++### Where grants are stored++Grants are stored on the user's machine, in+`<userData>/plugin-consent/` (one JSON file per environment, file mode `0600`).+They are scoped to the environment (cluster), the user, the plugin id and the+capability. A grant on one cluster or for one user never applies to another.+Grants do not sync between devices.++If a capability's payload widens in a later Desktop release, the old grant no+longer covers it and the user is asked again.++### Revoking++Users manage grants in **Settings → Plugin permissions**:++- The **Permissions** tab lists each plugin, the permissions it holds and when+ they were last used. **Revoke all** removes every grant for a plugin. Expand+ a plugin to see each permission with the same sentence the prompt showed, and+ **Revoke** it on its own.+- The **Activity** tab lists what plugins requested and the result (Shared,+ Granted, Denied, Revoked, Revoked mid-request, Rate limited, Error).+ **Clear activity log** empties it. `theme.read` and `gfs.open` calls are left+ out of this view.++Revoking takes effect immediately, even while the plugin is open: the plugin+gets a `permission.changed` event, cached results for it are dropped, and a call+already in flight returns `permission_revoked` instead of data.++### Activity log++The Desktop App keeps a local activity log in `<userData>/plugin-audit/` (one+JSONL file per environment, mode `0600`, rotated at 5 MB or 90 days). It records+the **shape** of what a plugin received (field names, item counts, byte sizes),+never the content.++## Errors++| Code | Retryable | Meaning |+| ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------- |+| `unsupported_capability` | No | Unknown capability id. |+| `unsupported_version` | No | The request named a protocol version other than `1`. |+| `invalid_request` | No | Bad or unexpected parameters, a bad capability list, a non-UTF-8 text file, or a non-image `dataUrl` read. |+| `unauthenticated` | Yes | The user is not logged in to the Desktop App. |+| `permission_denied` | Yes | The user has not granted this capability (denied, prompt dismissed, timed out, or prompt budget spent). |+| `permission_revoked` | Yes | The user revoked the grant while the call was running. |+| `rate_limited` | Yes | Over a rate limit. The message says how many milliseconds to wait. |+| `not_found` | No | Not found. Also returned when the user cannot access the item, so the SDK never reveals what exists. |+| `payload_too_large` | No | The file or result is over the size limit. |+| `unavailable` | Yes | The Desktop App could not complete the request (for example, an upstream failure). |+| `internal` | No | The calling view is not a registered plugin surface. |++## Rate limits++The Desktop App enforces these limits per plugin, in memory. Budgets refill+continuously rather than resetting every minute, and they reset when the user+closes and reopens the app. A call over a limit returns `rate_limited`.++| Capability | Per minute | Per hour | Max response size |+| -------------------------------- | ---------- | -------- | ----------------- |+| `identity.read` | 10 | 60 | 4 KB |+| `org.read` | 10 | 60 | 4 KB |+| `agents.read` | 10 | 120 | 256 KB |+| `contexts.read` | 10 | 120 | 64 KB |+| `mcp.read` | 10 | 120 | 128 KB |+| `gfs.list` | 30 | 600 | 512 KB |+| `gfs.read` | 20 | 300 | 20 MB |+| `gfs.open` | 6 | 60 | 1 KB |+| `theme.read` | 60 | 600 | 1 KB |+| `notifications.notify` | 2 | 20 | 1 KB |+| **All capabilities, per plugin** | **120** | **2400** | — |++A result larger than the capability's maximum returns `payload_too_large`.++Some results are cached for a short time, so repeated calls return the same+data: `identity.read` and `org.read` for 60 seconds, `agents.read`,+`contexts.read` and `mcp.read` for 30 seconds. The cache is cleared on logout,+login and revocation. Cached calls still count against the rate limit.++## Security model++What a plugin UI **cannot** do:++- **Claim another identity.** The plugin id comes from the view that sent the+ call, never from the request.+- **Answer its own consent prompt.** The prompt runs in the Desktop App's+ trusted window, the plugin's view is hidden while it is open, and the answer+ channel accepts only the trusted window and a one-time prompt id.+- **See more than the user can.** Every call uses the user's own session and+ Control API permissions.+- **See infrastructure detail.** MCP server URLs and profile picture URLs are+ removed, and errors never include upstream response bodies.+- **Read a file through `gfs.open`**, or learn why it failed.+- **Reach other origins.** The embed's Content Security Policy is+ `default-src 'self'; script-src 'self'; connect-src 'self'; img-src 'self' data:`+ (plus related directives). Inline `<script>` blocks do not run; load your+ JavaScript from a file served by your UI. Fetches go only to your UI's own+ origin through `rpc-proxy`. A recipe's server-side workload reaches external+ services through `spec.ui.egress`.+- **Navigate away or open windows.** Navigation is pinned to the UI's own path.+ `http(s)` links and `window.open` open in the user's default browser. Other+ schemes are dropped, except `clerum://oauth?clientId=…` (starts an OAuth+ connect) and `gfs://…` (behaves like `gfs.open`).+- **Use device features or download files.** Camera, microphone, location,+ web notifications, USB, serial, HID, Bluetooth and MIDI are all denied; only+ fullscreen is allowed. Downloads are blocked.+- **Use Node.js or Electron APIs.** The view runs with `sandbox: true`,+ `contextIsolation: true` and `nodeIntegration: false`. `window.clerum` is a+ frozen object.++The SDK is meant to reduce what a plugin can see, not to make an untrusted+plugin safe. Only install plugins from publishers you trust.++## Example++Serve this as a file (for example `app.js`) from your UI workload and load it+with `<script src="app.js"></script>`; the CSP blocks inline scripts.++```js+const clerum = window.clerum++async function start() {+ if (!clerum || !clerum.sdk) {+ renderWithoutSdk()+ return+ }++ // Follow the Desktop theme. No consent needed.+ const theme = await clerum.theme.get()+ if (theme.ok) document.documentElement.dataset.theme = theme.data.theme++ // Check first, so a returning user sees no prompt.+ const wanted = ['identity.read', 'agents.read']+ const state = await clerum.sdk.permissions(wanted)+ const missing = state.ok ? wanted.filter(id => !state.data.granted[id]) : wanted+ if (missing.length > 0) {+ await clerum.sdk.requestPermissions(missing) // one prompt for both+ }++ const me = await clerum.identity.get()+ if (me.ok) {+ renderGreeting(me.data.name)+ } else if (me.error.code === 'permission_denied') {+ renderSignedOutView() // a partial grant is normal; keep working+ }++ const agents = await clerum.agents.list()+ if (agents.ok) renderAgents(agents.data.agents)++ clerum.sdk.on(event => {+ if (event.type === 'theme.changed') {+ document.documentElement.dataset.theme = event.theme+ }+ if (event.type === 'permission.changed' && !event.granted) {+ renderSignedOutView()+ }+ })+}++start()+```++## Plugin UI SDK vs. Plugin Workload SDK++This page covers the **browser-side** API that a plugin's UI uses inside the+Desktop App. The **Plugin Workload SDK** is a different, server-side feature: a+recipe's backend workloads declare `spec.pluginWorkloadSdk` to use+`promptBridge` (LLM calls) and `clientNotifications` through Control API, with+its own grants and its own platform rate limits. See+[WorkflowRecipe § Plugin Workload SDK](../crds/workflowrecipe.md#319-plugin-workload-sdk-specpluginworkloadsdk)+and the [Plugin Workload SDK upgrade runbook](../deploy/plugin-workload-sdk-upgrade.md).+Custom workflow coordinators are built with a third package,+[`@clerum/workflow-sdk`](../../packages/workflow-sdk/README.md) (with+`packages/workflow-runtime-core`). The rate limits on this page are enforced by+the Desktop App and are separate from the Control API limits in that runbook.++## Related++- [Use the Desktop App § Apps and Plugins](../how-to/use-the-desktop-app.md#apps-and-plugins)+- [Desktop App surface](../surfaces/desktop-app.md)+- [Connect an OAuth connector](../how-to/connect-oauth-connector.md)+- [Publish a plugin to the registry](../how-to/publish-plugin-to-registry.md)diff --git a/grok-llm-proxy/README.md b/grok-llm-proxy/README.mdnew file mode 100644index 000000000..e82fd5eb5--- /dev/null+++ b/grok-llm-proxy/README.md@@ -0,0 +1,138 @@+# Grok LLM Proxy++Internal broker for the `grok-subscription` provider: xAI Grok subscription+sign-ins used as an LLM. It streams model calls from an agent to the Grok+subscription endpoint. The OAuth tokens stay in control-api's database; the+proxy receives an access token for a single operation and does not store it.++Off by default: `GROK_LLM_PROXY_EXECUTION_ENABLED` is `"false"` in+`deploy/base`. To turn the feature on, follow+[Connect an LLM subscription](../docs/how-to/connect-llm-subscription.md).++## Where it runs++- Namespace `control-plane`, one replica.+- Manifest: [`deploy/base/control-plane/grok-llm-proxy.yaml`](../deploy/base/control-plane/grok-llm-proxy.yaml)+ (ServiceAccount without a token, ConfigMap `grok-llm-proxy-config`,+ Deployment, ClusterIP Service).+- Image: `clerum/grok-llm-proxy` (built from this directory, listed in+ [`deploy/images.json`](../deploy/images.json)).++## How it fits++1. `mcp-host` (or a recipe's workflow MCP host) asks control-api to authorize+ the attempt: `POST /api/v1/mcp-host/llm/provider-attempts/authorize`.+ control-api returns a short-lived, single-use execution ticket bound to the+ Host, model and request hash.+2. The caller sends the request and the ticket to the proxy, with a platform+ JWT as the bearer token.+3. The proxy verifies both, then redeems the ticket with control-api+ (`POST /internal/llm/grok/provider-attempts/redeem`) through+ `control-api-rpc-gateway`. The redeem returns the access token for this+ one operation.+4. The proxy calls the Grok subscription endpoint and streams the answer back as+ SSE. The model stream never passes through control-api.+5. When the stream ends, the proxy reports the outcome and token usage+ (`POST /internal/llm/grok/provider-attempts/finalize`).++control-api also calls the admin port to list a connection's model catalog+and to test a connection (`control-api/src/services/grokSubscriptionCatalog.ts`).++The wire format, limits and error codes are frozen in the+[Grok subscription transport contract](../docs/architecture/grok-subscription-transport-contract.md).+The shared types and limits live in+[`packages/grok-provider-attempt-contract`](../packages/grok-provider-attempt-contract/).++## Endpoints++The proxy runs three HTTP servers.++| Port | Name | Route | Caller | Auth |+| ---- | ------- | --------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |+| 8080 | runtime | `POST /internal/runtime/v1/grok/completions` | mcp-host, workflow MCP host | RS256 platform JWT (`scope` `workflow:approval:request`, `workflowControlScopes` has `llm:grok:execute`) plus execution ticket in the body |+| 8081 | admin | `POST /internal/admin/v1/grok/models` | control-api | `grok-admin-permit` JWT for `catalog_list` |+| 8081 | admin | `POST /internal/admin/v1/grok/test` | control-api | `grok-admin-permit` JWT for `connection_test` |+| 9090 | metrics | `GET /healthz`, `GET /readyz`, `GET /metrics` | kubelet probes, `monitoring` ns | none |++The runtime route refuses a platform JWT whose `hostRefs` contains `*` or does+not contain the ticket's Host. Admin permits are refused on the runtime port,+and execution tickets on the admin port. Errors are JSON `{"error": "<code>"}`.++Upstream origins are fixed in the contract package and re-exported by+`src/originPolicy.ts`: `https://cli-chat-proxy.grok.com/v1/responses` for+completions and `https://cli-chat-proxy.grok.com/v1/models` for the catalog.++Image (V2) requests are bounded by xAI API documentation, not by a measured+call to the subscription endpoint. The+[transport contract](../docs/architecture/grok-subscription-transport-contract.md#visual-requests-issue-784)+records this gap.++## Kill switch++`GROK_LLM_PROXY_EXECUTION_ENABLED` accepts only the exact string `true`. Any+other value, including the `"false"` in `deploy/base`, makes the completions+route and both admin routes answer `404 {"error":"disabled"}` after+authentication. Probes and metrics keep working. The minikube overlay sets it+to `"true"` (`deploy/overlays/minikube/configmaps/grok-llm-proxy-config.yaml`).+Restart the Deployment after changing it.++## Configuration++All configuration is read from environment variables in `src/config.ts`. The+proxy refuses to start when a value is invalid.++| Variable | Default | Purpose |+| ----------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `GROK_LLM_PROXY_RUNTIME_PORT` | `8080` | Runtime (completions) port |+| `GROK_LLM_PROXY_ADMIN_PORT` | `8081` | Admin (catalog, connection test) port |+| `GROK_LLM_PROXY_PROBE_PORT` | `9090` | Health and metrics port |+| `GROK_LLM_PROXY_MAX_BODY_BYTES` | `8404992` | Ordinary request cap: the contract's 8 MiB `maxRequestBodyBytes` plus the 16 KiB envelope allowance. Lower values are refused. `deploy/base` leaves it unset. |+| `GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES` | `36700160` | Cap for V2 requests with images. Must equal the contract's `maxVisualRequestBodyBytes` (35 MiB) and be above `GROK_LLM_PROXY_MAX_BODY_BYTES`. |+| `GROK_LLM_PROXY_MAX_STREAM_DURATION_MS` | `1800000` | Longest a completion stream may run |+| `GROK_LLM_PROXY_MAX_DEADLINE_MS` | `1800000` | Largest request deadline accepted |+| `GROK_LLM_PROXY_UPSTREAM_IDLE_TIMEOUT_MS` | `600000` | Abort when the upstream is silent this long. Can only lower the built-in 600000. |+| `GROK_LLM_PROXY_HEARTBEAT_INTERVAL_MS` | `15000` | SSE keepalive interval after a successful redeem. Values above `60000` are refused. |+| `GROK_LLM_PROXY_JWT_ISSUER` | `control-api` | Expected `iss` of platform JWTs, tickets and admin permits |+| `GROK_LLM_PROXY_JWT_PUBLIC_KEY` | — (required) | control-api's PEM public key. `deploy/base` reads it from ConfigMap `control-api-public-key`. |+| `GROK_LLM_PROXY_EXECUTION_ENABLED` | off | Kill switch, see above. Only `true` enables. |+| `GROK_LLM_PROXY_CONTROL_API_URL` | — (required) | Absolute http(s) base URL for redeem/finalize. `deploy/base`: `http://control-api-rpc-gateway.control-plane.svc.cluster.local:8090/api/v1` |+| `GROK_LLM_PROXY_CONTROL_API_SERVICE` | `grok-llm-proxy` | Service name sent to control-api with the inter-service token |+| `GROK_LLM_PROXY_CONTROL_API_TOKEN` | — (required) | Inter-service token. `deploy/base` reads it from Secret `grok-llm-proxy-secrets`, created by `deploy/scripts/apply-inter-service-tokens.sh`. |++`deploy/base` also sets `NODE_OPTIONS=--max-old-space-size=768` under a+`2048Mi` memory limit, and `terminationGracePeriodSeconds: 1935` so a rollout+lets admitted streams finish. The manifest comments explain both numbers.++## Network policy++`control-plane` is deny-all. The proxy's own policies are in+[`deploy/base/control-plane/networkpolicies.yaml`](../deploy/base/control-plane/networkpolicies.yaml):++- `grok-llm-proxy-ingress`: port 8080 from Host pods in `mcp-host`+ (`clerum.io/managed-by: host-context-controller`) and workflow MCP host pods+ in `sandbox-recipes` (`clerum.io/component: workflow-mcp-host`); port 8081+ from `control-api`; port 9090 from the `monitoring` namespace.+- `grok-llm-proxy-egress`: port 8090 to `control-api-rpc-gateway` and TCP 443+ to `0.0.0.0/0`. The private and special-use ranges in `except` are filled at+ build time by the replacements in+ [`deploy/base/kustomization.yaml`](../deploy/base/kustomization.yaml) from+ `public-egress-exceptions.yaml`. DNS comes from+ `allow-dns-egress-control-plane`.+- `control-api-to-grok-llm-proxy` and `control-api-rpc-gateway` open the+ matching control-api and gateway sides.++## Development++```bash+npm ci+npm run build # tsc -> dist/+npm test # typecheck tests, then vitest+npm run typecheck+npm start # node dist/main.js (needs the required env vars)+```++## Related++- [Connect an LLM subscription](../docs/how-to/connect-llm-subscription.md): enable flags, sign in, troubleshoot+- [Grok subscription transport contract](../docs/architecture/grok-subscription-transport-contract.md)+- [codex-llm-proxy](../codex-llm-proxy/README.md): the Codex siblingdiff --git a/host-context-controller/README.md b/host-context-controller/README.mdindex 0f28dce18..9f78c0ad8 100644--- a/host-context-controller/README.md+++ b/host-context-controller/README.md@@ -3,9 +3,10 @@The Host Context Controller is a Kubernetes operator and REST API service that sits at the heart of the Clerum platform. It performs these key roles:1. **McpServer Operator** — Watches `McpServer` CRDs and automatically manages Deployments and Services for each MCP server, including secret validation.-2. **Host Operator** — Watches `Host` CRDs and automatically manages one Deployment, one Service, and one PVC per host, including secret validation.+2. **Host Operator** — Watches `Host` CRDs and automatically manages one Deployment, one Service, and one PVC per host, including secret validation. Hosts that opt into `spec.lifecycle.stateless` can be suspended (scaled to 0) when idle and woken on demand.3. **NetworkPolicy Operator** — Watches `Context` and `McpServer` CRDs and generates a four-layer NetworkPolicy model (deny-all, infrastructure, context-allow, external-egress) plus recipe binding policies.-4. **REST API** — Exposes a curated API that `mcp-host` uses to discover available MCP servers, their status, and auth tokens.+4. **LlmHook Operator** — Watches `LlmHook` CRDs in `llm-hooks` and runs the guardrail hook workloads (`src/llmHookReconciler.ts`).+5. **REST API** — Exposes a curated API that `mcp-host` uses to discover available MCP servers, their status, and auth tokens.It also reconciles `GlobalFileSystem` (`src/gfsReconciler.ts`) and `SharedFileSystem` (`src/sharedFileSystemReconciler.ts`) CRDs.@@ -58,6 +59,14 @@ Before deploying an MCP server, the reconciler checks that:If the secret is missing or incomplete, the MCP server will **not** be deployed. Creating the secrets an `McpServer` references is not the host-context-controller's responsibility — for those it only validates their existence. (It does create its own Secrets elsewhere, e.g. the per-Host runtime-token Secret in `mcp-host`.)+### Credential rollout++Container env vars that come from `secretKeyRef` are read only when the container starts, so editing the Secret alone does not reach a running pod. HCC closes that gap with a pod-template annotation: secret validation returns a sha256 of the Secret it just read, and the reconciler stamps it as `clerum.io/credentials-revision` on the Deployment's pod template (`src/reconciler.ts`). A `SecretInformer` on the McpServer namespace re-enqueues the servers that reference a changed Secret, the hash changes, and Kubernetes rolls the pod.++The same annotation drives rollouts for per-Host channel-reader pods (a second informer on `channels`) and for LlmHook pods (a third informer on `llm-hooks`) (`src/main.ts`).++For setting and rotating connector credentials from the operator side, see [Connect an OAuth connector](../docs/how-to/connect-oauth-connector.md).+## NetworkPolicy OperatorThe host-context-controller enforces **deny-by-default** network isolation across all runtime namespaces and generates allow policies from `Context` and `McpServer` CRDs. The model has four layers, implemented in `src/networkPolicyReconciler.ts`, plus recipe-scoped binding policies in `src/bindingPolicyReconciler.ts`.@@ -126,6 +135,19 @@ McpServers carrying a `clerum.io/recipe-bindings` annotation (set for WorkflowRe- **Context ADDED/MODIFIED/DELETED** — Creates, updates, or removes the L2 policy set for that context.- **McpServer ADDED/MODIFIED/DELETED** — Reconciles L3 external egress (before the workload Deployment is created) and recipe binding policies.+### Resync and orphan sweep++Every NetworkPolicy `fullReconcile` (startup, event-driven, and timer) sweeps HCC-labeled `context-allow`, `rpc-proxy-egress` and `external-egress` policies whose Context or McpServer no longer exists. Each delete counts in `clerum_hcc_netpol_orphans_deleted_total{lane}`.++A mass-delete guard protects against a bad cache. If the orphan count is above `CONTEXT_MAPPER_NETPOL_ORPHAN_DELETE_CAP` (default `10`) or above `CONTEXT_MAPPER_NETPOL_ORPHAN_DELETE_CAP_PERCENT` of the listed fleet (default `20`), the pass deletes nothing, still certifies, and increments `clerum_hcc_netpol_orphan_sweep_capped_total`. Those orphans stay until an operator raises the cap.++Two periodic timers exist, both **off by default** (`0`):++- `CONTEXT_MAPPER_NETPOL_RESYNC_SEC` re-runs the full coordinated pass (sweep plus L0/L1 defaults). A tick that finds a pass in flight is skipped, not queued.+- `CONTEXT_MAPPER_NETPOL_DEFAULTS_RESYNC_SEC` re-applies only the L0/L1 defaults.++With both off, startup still converges once and watch events still reconcile. See the [NetworkPolicy env table](#networkpolicy) for the full rules.+### Cross-Namespace TargetingPolicies select peers with the built-in `kubernetes.io/metadata.name` namespace label combined with pod label selectors, e.g. the L2 ingress rule:@@ -156,6 +178,8 @@ When a `Host` CRD is created, modified, or deleted in the host namespace, the ho- `Secret/host-<host-name>-mcp-host-runtime-tokens` (runtime credentials, rotated by the reconciler)- `ServiceAccount/`, `Role/` and `RoleBinding/` scoping the pod to its own Host CRD and Secrets- `NetworkPolicy/allow-rpc-proxy-desktop-<host-name>` for desktop hosts+ - `NetworkPolicy/mcp-host-<host-name>-egress-codex-proxy` / `-egress-grok-proxy` for Hosts configured for a Codex or Grok subscription ([guide](../docs/how-to/connect-llm-subscription.md))+ - `NetworkPolicy/mcp-host-<host-name>-egress-llm-hooks` for Hosts that reference guardrail hooks (see [LlmHook Operator](#llmhook-operator))It also reconciles, in the channels namespace (`CONTEXT_MAPPER_CHANNELS_NAMESPACE`, default `channels`), a per-Host `Service/channel-reader-<host-name>`, `Deployment/channel-reader-<host-name>` and `NetworkPolicy/channel-reader-<host-name>-egress`.@@ -171,6 +195,56 @@ Generated resources are labeled for orphan cleanup:On startup, a full host reconciliation pass runs and deletes orphaned host runtime resources whose Host CRD no longer exists — including orphaned channel-reader resources in `channels` and orphaned per-Host NetworkPolicies (`sweepOrphanChannelReaderResources`, `sweepOrphanHostNetworkPolicies`).+The same full pass repeats every `CONTEXT_MAPPER_HOST_RESYNC_SEC` (default `300`). It runs at most `HCC_HOST_FULL_RECONCILE_CONCURRENCY` Hosts at a time (default `2`). Per-Host watch events (ADDED, MODIFIED, DELETED, wake) are admitted outside that budget. Each finite Kubernetes call on this path has its own deadline (`HCC_HOST_K8S_REQUEST_TIMEOUT_MS`, default `30000`).++**No-op writes are skipped.** Before replacing the per-Host Role, HCC compares the live rules and labels with the desired ones (`roleMatchesDesired` in `src/hostReconciler.ts`). When they match, no `replace()` is sent and `clerum_hcc_write_skips_total{kind="Role"}` increments. Other objects written through `replaceWithConflictRetry` follow the same pattern.++### Stateless lifecycle++A Host with `spec.lifecycle.stateless: true` can be suspended when idle. mcp-host keeps its session state on the workspace PVC, so HCC can scale the Deployment to 0 and bring it back later. Field reference: [Host CRD](../docs/crds/host.md). Design invariants: [stateless-invariants.md](../docs/architecture/stateless-invariants.md).++The durable state lives in `Host.status.lifecycle.state`: `active`, `draining` or `suspended`. HCC sets Deployment replicas from it on every reconcile (`0` when `suspended`), so a suspended Host stays suspended across HCC restarts.++HCC refuses stateless mode, keeps the Host `active`, and writes `StatelessEnableRejected=True` when any of these apply (`src/statelessLifecycleExecutor.ts`):++| Reason | Cause |+| ----------------------------- | ------------------------------------------------------------------------------- |+| `DesktopEnabled` | `spec.desktop` is set. |+| `ActiveCommunicationChannels` | A CommunicationChannel points at the Host. Channel-connected Hosts stay active. |+| `SfsColocationUnsatisfiable` | Two or more SharedFileSystem mounts are pinned to different nodes. |++**Idle and drain.** HCC does not receive heartbeats directly. mcp-host sends them to control-api, and HCC polls `GET /api/v1/auth/mcp-host/heartbeats` every `CONTEXT_MAPPER_HEARTBEAT_POLL_MS` (default 10 s) with its InternalControl JWT (`src/heartbeatPoller.ts`). A Host becomes drain-eligible when it reports no active work and its last activity is older than `max(CONTEXT_MAPPER_STATELESS_IDLE_MINUTES, CONTEXT_MAPPER_STATELESS_IDLE_FLOOR_MINUTES)`, which is 30 minutes with the defaults. A pod older than `CONTEXT_MAPPER_STATELESS_MAX_UPTIME_HOURS` (default 72) drains regardless of activity. HCC marks the Host `draining`; when the pod reports `drained`, HCC writes `suspended` (reason `idle`). If the pod acknowledged the drain (or went silent) but never reports `drained`, HCC suspends after `CONTEXT_MAPPER_STATELESS_DRAIN_GRACE_MS` (default 60 s). If the heartbeat feed itself is down, the grace re-arms instead.++When activity keeps a Host awake, HCC publishes the cause in `status.lifecycle.reason` as `SuspendBlocked: <condition>`, where the condition is one of `awaitingApproval`, `activeTask`, `pendingResults`, `activeCronSchedules`, `activeWork` or `recentActivity`.++**Wake.** control-api requests a wake by bumping the `clerum.io/wake-requested` annotation on the Host. When that generation is higher than `status.lifecycle.wakeHandledGeneration`, HCC treats the wake as pending and will not drain or suspend the Host. Its wake fast-path first writes `state: active` with `wakeHandledGeneration` set to the requested generation, then scales the Deployment back up. Writing the status first means the wake survives an HCC crash before the scale.++**Image pull policy.** `CONTEXT_MAPPER_STATELESS_IMAGE_PULL_POLICY` overrides the pull policy for stateless pods (empty means inherit `CONTEXT_MAPPER_HOST_IMAGE_PULL_POLICY`). If it resolves to `IfNotPresent` and the image is not pinned (`@sha256:` digest or a `sha-<gitsha>` tag), the pod still runs with `IfNotPresent`, and HCC writes `StatelessPullPolicyRejected=True` (reason `MutableImageReference`) to warn that a wake can start stale cached code.++## LlmHook Operator++`LlmHook` CRs are installed guardrail hooks in the `llm-hooks` namespace (`CONTEXT_MAPPER_LLM_HOOKS_NAMESPACE`). Field reference: [LlmHook CRD](../docs/crds/llmhook.md). Operator guide: [Configure guardrails](../docs/how-to/configure-guardrails.md).++What HCC does depends on `spec.target` (`src/llmHookReconciler.ts`):++| Target | What HCC creates |+| --------- | ---------------------------------------------------------------------------------------------------- |+| `image` | A shared `Deployment`, `Service` and `NetworkPolicy`, all named `llmhook-<podKey>`, in `llm-hooks`. |+| `service` | No workload. Only an ingress NetworkPolicy `llmhook-svc-<crName>` that admits the referencing Hosts. |+| `remote` | Nothing. Status only. |++**Shared pods (dedup).** Unlike other HCC reconcilers, many CRs can map to one workload. Image hooks that share a _pod key_ (a hash of image ref, port, `envSecret`, `egressBindings` and `addCapabilities`) run on one pod and are told apart by `spec.path`. The workload is reference-counted: HCC deletes it when the last member CR for that pod key is gone. Work is serialized per pod key, not per CR name.++**Network.** `llm-hooks` starts fully closed by the static `llm-hooks-static-default-deny` policy (`deploy/base/llm-hooks/networkpolicies.yaml`). The namespace is deliberately not in `CONTEXT_MAPPER_RUNTIME_NAMESPACES`, so it gets no namespace-wide DNS. HCC then opens only:++- ingress to a hook pod from the mcp-host pods whose Host lists that hook under `spec.guardrails.hooks`;+- egress from a hook pod to its declared `egressBindings` plus DNS to `kube-system`, only when it declares any (a hook with no bindings gets no egress at all);+- a per-Host `mcp-host-<host>-egress-llm-hooks` policy in `mcp-host` that lets each Host reach only the hooks it references (removed when it references none).++Host changes re-run these policies through a Host→LlmHook reverse index. Status reports `observedDigest`, `readyReplicas` and a `Ready` condition (reasons `NoWorkload`, `Deploying`, `Ready`, `DuplicatePath`, `SecretNotFound`, `InvalidEgress`, `ReconcileError`).++A full LlmHook pass runs at startup and every `CONTEXT_MAPPER_LLM_HOOK_RESYNC_SEC` (default `300`). It reconciles every pod key and every Host's hook egress, then deletes `llmhook-*` workloads whose pod key has no live member. Rotating a hook's `envSecret` rolls its pod through the [credentials-revision annotation](#credential-rollout).+## REST APIThe Host-facing MCP contract is authenticated and Host-scoped. HCC verifies the@@ -290,6 +364,80 @@ The legacy caller-selected routes`GET /api/v1/mcpservers/:name/auth` are tombstoned with a generic HTTP 410 atboth the gateway and HCC application layers; there is no v1 fallback.+## Metrics++`GET /metrics` serves Prometheus metrics from a dedicated registry (`src/metrics.ts`). Every series carries the default label `service="host-context-controller"`. Labels are low-cardinality by design: no Host, user, team, Secret or JWT values appear in them (the one exception is `clerum_hcc_mcpserver_missing_secret`, which names the McpServer and Secret).++For the create and existence-read counters, including PromQL examples, see [CREATE_OBSERVABILITY.md](CREATE_OBSERVABILITY.md).++**Inventory and reconcile results**++| Metric | Type | Labels | Meaning |+| ----------------------------------------------- | ------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `clerum_hcc_mcpservers_total` | gauge | `status` | McpServer CRDs tracked by HCC. |+| `clerum_hcc_networkpolicies_total` | gauge | `layer` | NetworkPolicies managed by HCC. |+| `clerum_hcc_context_reconciliations_total` | counter | `result` | Context reconciliations. |+| `clerum_hcc_binding_reconciliations_total` | counter | `result` | Recipe binding-policy reconciliations. |+| `clerum_hcc_context_metadata_only_events_total` | counter | — | Context MODIFIED events that did not change the desired state, so Host and SharedFileSystem fan-out was skipped. A rising rate means label churn is back. |+| `clerum_hcc_mcpserver_missing_secret` | gauge | `namespace`, `name`, `secret_name` | `1` while an McpServer references a Secret that does not exist. |+| `clerum_hcc_external_egress_retries_at_cap` | gauge | — | McpServers whose external-egress DNS retry is stuck at the maximum backoff. |++**Kubernetes writes**++| Metric | Type | Labels | Meaning |+| ---------------------------------- | ------- | ----------------- | ----------------------------------------------------------------------------------------- |+| `clerum_hcc_creates_total` | counter | `kind`, `outcome` | Create outcomes: `created`, `conflict`, `error`, `skipped`. See CREATE_OBSERVABILITY.md. |+| `clerum_hcc_existence_reads_total` | counter | `kind`, `outcome` | Existence GETs on create/converge paths: `found`, `absent`, `error`. |+| `clerum_hcc_writes_total` | counter | `kind` | Successful `replace()` calls made through `replaceWithConflictRetry`. |+| `clerum_hcc_write_skips_total` | counter | `kind` | Replaces skipped because the live object already matched (for example the per-Host Role). |++**NetworkPolicy convergence**++| Metric | Type | Labels | Meaning |+| --------------------------------------------------------------- | --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |+| `clerum_hcc_initial_convergence_retries_total` | counter | `lane` | Retries scheduled after a failed background convergence pass. |+| `clerum_hcc_initial_convergence_last_success_timestamp_seconds` | gauge | `lane` | Unix time of the last successful background convergence pass. |+| `clerum_hcc_initial_convergence_swallowed_total` | counter | `lane`, `sink` | Convergence requests that returned without certifying. |+| `clerum_hcc_initial_convergence_effects_dropped_total` | counter | `lane`, `kind` | Allow-policy writes dropped because the pass's inventory lease was retired. |+| `clerum_hcc_initial_convergence_pass_results_total` | counter | `lane`, `result` | Named outcomes of convergence passes. |+| `clerum_hcc_initial_convergence_pass_duration_seconds` | histogram | `lane`, `result` | Duration of a convergence pass. |+| `clerum_hcc_networkpolicy_safety_pass_duration_seconds` | histogram | `outcome` | Time until a safety pass has revoked stale allows. |+| `clerum_hcc_networkpolicy_safety_pass_policies_total` | counter | `operation` | Policies listed and revoked by safety passes. |+| `clerum_hcc_netpol_orphans_deleted_total` | counter | `lane` | Orphan NetworkPolicies deleted by a `fullReconcile` sweep. |+| `clerum_hcc_netpol_orphan_sweep_capped_total` | counter | `reason` | Sweeps that refused to delete because the orphan count hit the `absolute` or `percent` cap. |+| `clerum_hcc_netpol_resync_ticks_skipped_total` | counter | `reason` | Resync ticks skipped because a pass (`pass-in-flight`) or defaults tick (`defaults-only-in-flight`) was running. |+| `clerum_hcc_netpol_defaults_only_ticks_total` | counter | `result` | Defaults-only ticks by result (`success`, `error`). |+| `clerum_hcc_netpol_defaults_only_tick_duration_seconds` | histogram | `result` | Duration of a defaults-only tick. |++**Host reconciliation**++| Metric | Type | Labels | Meaning |+| -------------------------------------------------- | --------- | ------------------- | ----------------------------------------------------------------------------------------------- |+| `clerum_hcc_host_reconcile_queue_wait_seconds` | histogram | `lane`, `outcome` | Time a Host reconcile waited before its per-Host chain admitted it. |+| `clerum_hcc_host_reconcile_duration_seconds` | histogram | `source`, `outcome` | Time a Host reconcile body ran after admission. |+| `clerum_hcc_host_reconcile_in_flight` | gauge | `lane` | Host reconciles running now, by lane (`urgent`, `retry`, `fleet`). |+| `clerum_hcc_host_watch_recovery_seconds` | histogram | `phase`, `outcome` | Host watch LIST-to-WATCH recovery time (`list`, `watch`, `total`). |+| `clerum_hcc_host_fleet_requests_total` | counter | `result` | Fleet pass requests: `started`, `coalesced`, `trailing`, `failed`. |+| `clerum_hcc_host_fleet_benign_supersessions_total` | counter | `error` | Fleet workers withdrawn because a newer equivalent pass replaced them. |+| `clerum_hcc_host_fleet_lifecycle_catch_total` | counter | `decision` | Fleet catch-path decisions during a CommunicationChannel lifecycle change (`applied`, `retry`). |+| `clerum_hcc_host_cleanup_deferred_total` | counter | `reason` | Orphan Host cleanups deferred. |+| `clerum_hcc_host_delete_cleanup_total` | counter | `outcome` | Host deletion cleanup: `queued`, `confirmed`, `completed`, `retried`, `superseded`. |++**Secret watch, MCP API and reporters**++| Metric | Type | Labels | Meaning |+| ---------------------------------------------------- | ------- | ----------------------------- | ------------------------------------------------------------------------------------------------------- |+| `clerum_hcc_secret_informer_events_total` | counter | `type` | Secret informer events received. |+| `clerum_hcc_secret_informer_reconnects_total` | counter | — | Secret informer reconnect attempts. |+| `clerum_hcc_secret_informer_running` | gauge | — | `1` while the Secret watch is established. |+| `clerum_hcc_mcp_host_api_requests_total` | counter | `action`, `outcome`, `reason` | Host-scoped MCP API requests (inventory, credential). |+| `clerum_hcc_infrastructure_telemetry_enqueued_total` | counter | `telemetry_type` | Telemetry items accepted by the bounded reporter. |+| `clerum_hcc_infrastructure_telemetry_dropped_total` | counter | `telemetry_type`, `reason` | Telemetry items dropped. |+| `clerum_hcc_infrastructure_telemetry_flushes_total` | counter | `result` | Telemetry flush attempts. |+| `clerum_hcc_infrastructure_telemetry_retries_total` | counter | `telemetry_type` | Telemetry retries after a failed flush. |+| `clerum_hcc_infrastructure_telemetry_gaps_total` | counter | `telemetry_type`, `reason` | Gaps that leave trace or cost coverage incomplete. |+| `clerum_hcc_administrative_outcome_reporter_total` | counter | `result` | Administrative outcome reports: enqueued, deduplicated, accepted, conflict, rejected, or a drop reason. |+## Environment VariablesHCC reads environment variables from `src/config.ts`, `src/gfsConfig.ts`,@@ -307,6 +455,17 @@ a permissive policy — see the NetworkPolicy and GFS tables:`CONTEXT_MAPPER_K8S_API_CIDRS`, `CONTEXT_MAPPER_NODELOCAL_DNS_CIDR`, and`CONTEXT_MAPPER_GFSC_IMAGE_PULL_POLICY`.+**Newer numeric knobs are parsed strictly** and also fail startup on a bad value+instead of silently falling back: the `CONTEXT_MAPPER_NETPOL_*` and+`HCC_EXTERNAL_EGRESS_*` families, `HCC_HOST_FULL_RECONCILE_CONCURRENCY`,+`HCC_HOST_K8S_REQUEST_TIMEOUT_MS` and `CONTEXT_MAPPER_HEARTBEAT_POLL_MS`. Most of+them treat an empty string as unset. `HCC_HOST_K8S_REQUEST_TIMEOUT_MS` does not:+set to `""` it fails startup.++**Removed variable.** `CLERUM_STATELESS_COMMUNICATION_CHANNEL_POLICY` is no+longer supported. Any non-empty value fails startup; CommunicationChannel-connected+Hosts are always kept active.+### Core / server| Variable | Default | Description |@@ -326,41 +485,69 @@ a permissive policy — see the NetworkPolicy and GFS tables:| `CONTEXT_MAPPER_RPC_PROXY_NAMESPACE` | `rpc-proxy` | Where rpc-proxy runs (L2 egress policy generation). || `CONTEXT_MAPPER_CHANNELS_NAMESPACE` | `channels` | Per-Host channel-reader Deployments/Services. || `CONTEXT_MAPPER_SANDBOX_NAMESPACE` | `sandbox-recipes` | Workflow-recipe namespace. Read only by the GFS factory. |+| `CONTEXT_MAPPER_LLM_HOOKS_NAMESPACE` | `llm-hooks` | Where `LlmHook` CRDs are watched and image-hook workloads run. || `HCC_TARGET_NAMESPACE` | `mcp-host` | Namespace HCC names when asking control-api for caller-bound 1st-party mcp-host credentials. It must exactly equal `CONTEXT_MAPPER_HOST_NAMESPACE`; HCC exits 1 otherwise. |### MCP server provisioning-| Variable | Default | Description |-| -------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- |-| `CONTEXT_MAPPER_MCPSERVER_IMAGE_PULL_POLICY` | `IfNotPresent` | Pull policy for reconciled McpServer workloads. |-| `CONTEXT_MAPPER_EGRESS_PROXY_IMAGE` | `clerum/nginx-egress-proxy:0.1.0` | Per-server nginx egress proxy for **remote** MCP servers (`spec.remote`). |-| `CONTEXT_MAPPER_STDIO_BRIDGE_IMAGE` | (registry-qualified `stdio-bridge`) | stdio-bridge sidecar image for managed stdio MCP servers. Manifest pins `clerum/stdio-bridge:0.9.5`. |-| `CONTEXT_MAPPER_STDIO_BRIDGE_REQUEST_MEMORY` | `32Mi` | stdio-bridge sidecar memory request. |-| `CONTEXT_MAPPER_STDIO_BRIDGE_REQUEST_CPU` | `50m` | stdio-bridge sidecar CPU request. |-| `CONTEXT_MAPPER_STDIO_BRIDGE_LIMIT_MEMORY` | `128Mi` | stdio-bridge sidecar memory limit. |-| `CONTEXT_MAPPER_STDIO_BRIDGE_LIMIT_CPU` | `200m` | stdio-bridge sidecar CPU limit. |-| `HCC_EXTERNAL_EGRESS_RESYNC_SEC` | `300` | Periodic external-egress DNS resync interval (seconds). `0` disables periodic refresh; watch events still reconcile. |-| `HCC_EXTERNAL_EGRESS_DNS_TIMEOUT_MS` | `5000` | Per-hostname DNS lookup deadline in milliseconds. |+| Variable | Default | Description |+| -------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `CONTEXT_MAPPER_MCPSERVER_IMAGE_PULL_POLICY` | `IfNotPresent` | Pull policy for reconciled McpServer workloads. |+| `CONTEXT_MAPPER_EGRESS_PROXY_IMAGE` | `clerum/nginx-egress-proxy:0.1.0` | Per-server nginx egress proxy for **remote** MCP servers (`spec.remote`). |+| `CONTEXT_MAPPER_STDIO_BRIDGE_IMAGE` | (registry-qualified `stdio-bridge`) | stdio-bridge sidecar image for managed stdio MCP servers. Manifest pins `clerum/stdio-bridge:0.9.5`. |+| `CONTEXT_MAPPER_STDIO_BRIDGE_REQUEST_MEMORY` | `32Mi` | stdio-bridge sidecar memory request. |+| `CONTEXT_MAPPER_STDIO_BRIDGE_REQUEST_CPU` | `50m` | stdio-bridge sidecar CPU request. |+| `CONTEXT_MAPPER_STDIO_BRIDGE_LIMIT_MEMORY` | `128Mi` | stdio-bridge sidecar memory limit. |+| `CONTEXT_MAPPER_STDIO_BRIDGE_LIMIT_CPU` | `200m` | stdio-bridge sidecar CPU limit. |+| `HCC_EXTERNAL_EGRESS_RESYNC_SEC` | `60` | Periodic external-egress DNS resync interval (seconds). `0` disables periodic refresh; watch events still reconcile. When enabled it must be at least the refresh floor and at most half the overlap; max `3600`. Startup fails otherwise. |+| `HCC_EXTERNAL_EGRESS_DNS_TIMEOUT_MS` | `5000` | Per-hostname DNS lookup deadline in milliseconds. |+| `HCC_EXTERNAL_EGRESS_OVERLAP_SEC` | `300` | How long a resolved `/32` stays allowed after its DNS TTL, so a provider that rotates A records keeps working. 1–3600. |+| `HCC_EXTERNAL_EGRESS_REFRESH_FLOOR_SEC` | `5` | Minimum resync interval; guards against a hot loop. 1–3600. |+| `HCC_EXTERNAL_EGRESS_MAX_ENTRIES` | `128` | Accumulated IPs kept per hostname. On overflow the least recently seen IP is evicted. 1–1300. |### mcp-host provisioning-| Variable | Default | Description |-| --------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |-| `CONTEXT_MAPPER_HOST_IMAGE` | (registry-qualified `mcp-host`) | Image for reconciled Host Deployments. Manifest pins `clerum/mcp-host:0.9.5`. |-| `CONTEXT_MAPPER_HOST_IMAGE_PULL_POLICY` | `Always` | Pull policy. Minikube overlay sets `IfNotPresent`. |-| `CONTEXT_MAPPER_HOST_IMAGE_PULL_SECRET` | `clerum` | `imagePullSecrets` name. Minikube overlay sets `""` to disable (empty string overrides the default). |-| `CONTEXT_MAPPER_HOST_PORT` | `8080` | Container/service port for the host runtime. |-| `CONTEXT_MAPPER_HOST_CONFIGMAP_NAME` | `mcp-host-config` | ConfigMap loaded into host containers via `envFrom`. |-| `CONTEXT_MAPPER_HOST_SERVICE_ACCOUNT` | `mcp-host` | ServiceAccount used by Host Deployments. |-| `CONTEXT_MAPPER_HOST_WORKSPACE_STORAGE_CLASS` | `do-block-storage-retain` | StorageClass for per-host workspace PVCs. Minikube overlay sets `standard`. |-| `CONTEXT_MAPPER_HOST_WORKSPACE_SIZE` | `10Gi` | Requested per-host workspace PVC size. |-| `CONTEXT_MAPPER_HOST_WORKSPACE_PATH` | `/workspace` | Workspace mount path inside host containers. |-| `CONTEXT_MAPPER_HOST_RESOURCES_REQUEST_MEMORY` | `128Mi` | Host container memory request. |-| `CONTEXT_MAPPER_HOST_RESOURCES_REQUEST_CPU` | `100m` | Host container CPU request. |-| `CONTEXT_MAPPER_HOST_RESOURCES_LIMIT_MEMORY` | `512Mi` | Host container memory limit. |-| `CONTEXT_MAPPER_HOST_RESOURCES_LIMIT_CPU` | `500m` | Host container CPU limit. |-| `CONTEXT_MAPPER_HOST_RESYNC_SEC` | `300` | Periodic Host `fullReconcile` (seconds); guards against dropped watch events and drives auth-degraded self-heal. `0` disables. |-| `HCC_MCP_HOST_RUNTIME_BOOTSTRAP_REFRESH_BEFORE_SEC` | `900` | How long before expiry HCC refreshes the mcp-host bootstrap credential Secret. |+| Variable | Default | Description |+| --------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `CONTEXT_MAPPER_HOST_IMAGE` | (registry-qualified `mcp-host`) | Image for reconciled Host Deployments. Manifest pins `clerum/mcp-host:0.9.5`. |+| `CONTEXT_MAPPER_HOST_IMAGE_PULL_POLICY` | `Always` | Pull policy. Minikube overlay sets `IfNotPresent`. |+| `CONTEXT_MAPPER_HOST_IMAGE_PULL_SECRET` | `clerum` | `imagePullSecrets` name. Minikube overlay sets `""` to disable (empty string overrides the default). |+| `CONTEXT_MAPPER_HOST_PORT` | `8080` | Container/service port for the host runtime. |+| `CONTEXT_MAPPER_HOST_CONFIGMAP_NAME` | `mcp-host-config` | ConfigMap loaded into host containers via `envFrom`. |+| `CONTEXT_MAPPER_HOST_SERVICE_ACCOUNT` | `mcp-host` | ServiceAccount used by Host Deployments. |+| `CONTEXT_MAPPER_HOST_WORKSPACE_STORAGE_CLASS` | `do-block-storage-retain` | StorageClass for per-host workspace PVCs. Minikube overlay sets `standard`. |+| `CONTEXT_MAPPER_HOST_WORKSPACE_SIZE` | `10Gi` | Requested per-host workspace PVC size. |+| `CONTEXT_MAPPER_HOST_WORKSPACE_PATH` | `/workspace` | Workspace mount path inside host containers. |+| `CONTEXT_MAPPER_HOST_RESOURCES_REQUEST_MEMORY` | `128Mi` | Host container memory request. |+| `CONTEXT_MAPPER_HOST_RESOURCES_REQUEST_CPU` | `100m` | Host container CPU request. |+| `CONTEXT_MAPPER_HOST_RESOURCES_LIMIT_MEMORY` | `512Mi` | Host container memory limit. |+| `CONTEXT_MAPPER_HOST_RESOURCES_LIMIT_CPU` | `500m` | Host container CPU limit. |+| `CONTEXT_MAPPER_HOST_RESYNC_SEC` | `300` | Periodic Host `fullReconcile` (seconds); guards against dropped watch events and drives auth-degraded self-heal. `0` disables. |+| `HCC_MCP_HOST_RUNTIME_BOOTSTRAP_REFRESH_BEFORE_SEC` | `900` | How long before expiry HCC refreshes the mcp-host bootstrap credential Secret. |+| `CONTEXT_MAPPER_RUNTIME_TOKEN_ROTATE_BEFORE_S` | `86400` (24 h) | Rotate the bootstrap runtime-token Secret when the refresh token's real `exp` is closer than this. Capped at half the token's lifetime so short-lived tokens do not rotate on every reconcile. |+| `HCC_HOST_FULL_RECONCILE_CONCURRENCY` | `2` | Hosts reconciled in parallel during a full or lifecycle fleet pass. Integer 1–8; `1` is serial (diagnostic). Per-Host events are not counted against it. |+| `HCC_HOST_K8S_REQUEST_TIMEOUT_MS` | `30000` | Deadline for each finite Kubernetes request on the Host convergence path. Watches are not affected. Positive integer. |++### Stateless Hosts (Host CRD `spec.lifecycle.stateless`)++Only used for Hosts with `spec.lifecycle.stateless: true`. See [Stateless lifecycle](#stateless-lifecycle). `deploy/base` sets the first four to their code defaults.++| Variable | Default | Description |+| --------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |+| `CONTEXT_MAPPER_STATELESS_IDLE_MINUTES` | `30` | Idle time before a Host may drain. |+| `CONTEXT_MAPPER_STATELESS_IDLE_FLOOR_MINUTES` | `15` | Platform floor. The effective idle window is `max(idle, floor)`. |+| `CONTEXT_MAPPER_STATELESS_DRAIN_GRACE_MS` | `60000` | After a drain verdict, how long HCC waits for a `drained` report before suspending anyway (only if the pod acknowledged or went silent). |+| `CONTEXT_MAPPER_HEARTBEAT_POLL_MS` | `10000` | How often HCC polls control-api for heartbeats. Positive integer; anything else fails startup. |+| `CONTEXT_MAPPER_STATELESS_MAX_UPTIME_HOURS` | `72` | A pod older than this drains regardless of activity. |+| `CONTEXT_MAPPER_STATELESS_IMAGE_PULL_POLICY` | `` (empty) | Pull policy for stateless pods. Empty inherits `CONTEXT_MAPPER_HOST_IMAGE_PULL_POLICY`. |++### LlmHook++The namespace is `CONTEXT_MAPPER_LLM_HOOKS_NAMESPACE` (see [Namespaces](#namespaces)).++| Variable | Default | Description |+| ------------------------------------ | ------- | -------------------------------------------------------------------------------------------------- |+| `CONTEXT_MAPPER_LLM_HOOK_RESYNC_SEC` | `300` | Periodic LlmHook full pass (seconds): readiness, Host egress, orphan workload sweep. `0` disables. |### mcp-host API authorization@@ -433,6 +620,8 @@ Read by `src/gfsConfig.ts`. Invalid values **throw at startup** rather than sile| `CONTEXT_MAPPER_GFS_JWT_CONFIGMAP_KEY` | `jwt-public-key` | Key within that ConfigMap. || `CONTEXT_MAPPER_GFS_PG_SECRET` | `gfs-controller-db` | Secret holding the gfsc Postgres connection string. || `CONTEXT_MAPPER_GFS_PG_SECRET_KEY` | `connection-string` | Key within that Secret. |+| `CONTEXT_MAPPER_GFS_READER_PG_SECRET` | `gfs-controller-reader-db` | Secret holding the connection string for gfsc **reader** pods, so readers and the writer use separate least-privilege database roles. |+| `CONTEXT_MAPPER_GFS_READER_PG_SECRET_KEY` | `connection-string` | Key within that Secret. || `CONTEXT_MAPPER_GFS_DRIVE_NAME` | `main` | Default GFS drive name. || `CONTEXT_MAPPER_GFS_TOKEN_AUDIENCE` | `gfs-controller` | Expected `aud` claim on GFS access tokens. || `CONTEXT_MAPPER_GFS_RESYNC_SEC` | `60` | Periodic GlobalFileSystem `fullReconcile` (seconds); drives convergence to `Ready` and the root-directory seed. `0` disables. |@@ -446,6 +635,16 @@ recreated (`strategy: Recreate`), and readers return after the writer is availab(`src/gfsReconciler.ts`). Reads and writes through gfsc are unavailable for that window.The defaults equal gfsc's own (`gfs-controller/src/config.ts`), which a test pins.+**Pass-through gfsc limits.** HCC also forwards a set of gfsc tuning variables+unchanged into the gfsc pods (`gfscEnv` in `src/k8s/gfsFactory.ts`):+`GFS_SYNC_COPY_MAX_OBJECTS`, `GFS_SYNC_COPY_MAX_BYTES`, `GFS_SYNC_COPY_TIMEOUT_MS`,+`GFS_MAX_WRITE_BODY_BYTES`, and every `CONTEXT_MAPPER_GFSC_UPLOAD_*` variable+(written to the pod as the matching `GFS_UPLOAD_*` name;+`CONTEXT_MAPPER_GFSC_UPLOAD_V2_ENABLED` goes to the writer only). HCC sets no+default for these: an unset variable is not injected, and gfsc's own default+applies (`gfs-controller/src/config.ts`). `deploy/base` sets only+`GFS_MAX_WRITE_BODY_BYTES` (`25165824`, 24 MiB).+### NetworkPolicy| Variable | Default | Description |@@ -469,11 +668,12 @@ The defaults equal gfsc's own (`gfs-controller/src/config.ts`), which a test pin### Control-API integration-| Variable | Default | Description |-| -------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `CONTROL_API_BASE_URL` | `http://control-api.control-plane.svc.cluster.local:8090` | Cluster-internal control-api URL. HCC calls it directly to issue mcp-host runtime tokens for the pods it provisions. |-| `INTERNAL_CONTROL_JWT_HCC_HMAC_SECRET` | `` (empty) | HS256 secret for signing InternalControl JWTs. **Required whenever `CLERUM_DEV_MODE` is not `true`** — the process logs `[HCC] FATAL` and exits 1 if empty or still a `replace-with-…` placeholder. |-| `MCP_HOST_GATEWAY_URL` | `http://nginx-workflow-approval-gateway.control-plane.svc:8092` | The nginx allowlist proxy mediating mcp-host → control-api. HCC **injects this into the mcp-host pods it provisions**; it does not call it itself. |+| Variable | Default | Description |+| -------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `CONTROL_API_BASE_URL` | `http://control-api.control-plane.svc.cluster.local:8090` | Cluster-internal control-api URL. HCC calls it directly to issue mcp-host runtime tokens for the pods it provisions. |+| `INTERNAL_CONTROL_JWT_HCC_HMAC_SECRET` | `` (empty) | HS256 secret for signing InternalControl JWTs. **Required whenever `CLERUM_DEV_MODE` is not `true`** — the process logs `[HCC] FATAL` and exits 1 if empty or still a `replace-with-…` placeholder. |+| `MCP_HOST_GATEWAY_URL` | `http://nginx-workflow-approval-gateway.control-plane.svc.cluster.local:8092` | The nginx allowlist proxy mediating mcp-host → control-api. HCC **injects this into the mcp-host pods it provisions**; it does not call it itself. |+| `GOVERNED_TRACING_ENABLED` | `true` | Turns on HCC's infrastructure-telemetry and administrative-outcome reporters, which post to control-api. Both also need a non-empty `CONTROL_API_BASE_URL`. See [governed tracing](../docs/architecture/governed-tracing.md). |### Dev mode@@ -487,7 +687,7 @@ Parsed only when `CLERUM_DEV_MODE` is truthy. A JSON parse failure logs an error## Kubernetes RBAC-The shipped Roles and RoleBindings are the source of truth — see `deploy/base/<namespace>/rbac.yaml`. The controller's ServiceAccount lives in `control-plane` and is bound into `mcp-server`, `mcp-host`, `channels`, `rpc-proxy`, `sandbox-recipes`, `sandbox-ui` and `gfs`. The table below is an overview of the two main namespaces, not a complete Role definition — do not build a Role from it.+The shipped Roles and RoleBindings are the source of truth — see `deploy/base/<namespace>/rbac.yaml`. The controller's ServiceAccount lives in `control-plane` and is bound into `mcp-server`, `mcp-host`, `channels`, `rpc-proxy`, `sandbox-recipes`, `sandbox-ui`, `gfs` and `llm-hooks`. The table below is an overview of the two main namespaces, not a complete Role definition — do not build a Role from it.In `mcp-server` (`deploy/base/mcp-server/rbac.yaml`):@@ -506,12 +706,13 @@ In `mcp-host` (`deploy/base/mcp-host/rbac.yaml`), the controller additionally ma## Namespaces-| Component | Namespace | Purpose |-| ----------------------- | --------------- | -------------------------------------------------------------------- |-| host-context-controller | `control-plane` | Operator and API service |-| MCP server pods + CRDs | `mcp-server` | `McpServer` and `Context` source of truth + managed server workloads |-| mcp-host | `mcp-host` | Consumer of the REST API, target of NetworkPolicy `from` rules |-| channel-reader | `channels` | Communication layer |+| Component | Namespace | Purpose |+| ------------------------ | --------------- | -------------------------------------------------------------------- |+| host-context-controller | `control-plane` | Operator and API service |+| MCP server pods + CRDs | `mcp-server` | `McpServer` and `Context` source of truth + managed server workloads |+| mcp-host | `mcp-host` | Consumer of the REST API, target of NetworkPolicy `from` rules |+| channel-reader | `channels` | Communication layer |+| LlmHook CRDs + hook pods | `llm-hooks` | Guardrail hooks; static default-deny plus HCC-managed allow policies |## Local Development@@ -588,3 +789,5 @@ For a local minikube cluster, `scripts/minikube/build-images.sh` builds this ima> The component Makefile's `docker-build` / `docker-push` / `docker-push-cross` targets pass this directory as the build context, so the `COPY packages/...` layer cannot resolve and the build fails. Use the root-context commands above.The component Makefile does not deploy. The controller's ServiceAccount, Deployment and Service live in `deploy/base/control-plane/host-context-controller.yaml`; namespaces are in `deploy/base/namespaces.yaml` and RBAC in `deploy/base/<namespace>/rbac.yaml`. All are applied with kustomize from the repo root, e.g. `kubectl apply -k deploy/overlays/minikube`.++The controller Deployment runs `replicas: 1` with `strategy: Recreate`, because HCC assumes it is the only NetworkPolicy writer and has no leader election. Each rollout therefore has a short window with no HCC, and a new pod that never becomes Ready leaves `/ready` at `503`. `progressDeadlineSeconds: 1200` only detects that; rolling back (`kubectl rollout undo`) is up to your deploy pipeline. See [HCC readiness flows §5](../docs/architecture/hcc-readiness-flows.md#5-deploy-invariant--single-writer).diff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.jsonindex dabaeca28..ce2ef8678 100644--- a/host-context-controller/package-lock.json+++ b/host-context-controller/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-host-context-controller",- "version": "0.1.382",+ "version": "0.1.383","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-host-context-controller",- "version": "0.1.382",+ "version": "0.1.383","license": "SEE LICENSE IN LICENSE","dependencies": {"@clerum/codex-catalog-projection": "file:../packages/codex-catalog-projection",diff --git a/host-context-controller/package.json b/host-context-controller/package.jsonindex 4f0e9abfe..d6a0ec384 100644--- a/host-context-controller/package.json+++ b/host-context-controller/package.json@@ -1,6 +1,6 @@{"name": "clerum-host-context-controller",- "version": "0.1.382",+ "version": "0.1.383","description": "Host Context Controller - provides McpServer CRDs to mcp-host via REST API","main": "dist/main.js","engines": {diff --git a/mcp-host/README.md b/mcp-host/README.mdindex a19ee74fb..85f669311 100644--- a/mcp-host/README.md+++ b/mcp-host/README.md@@ -1,12 +1,12 @@# MCP Host-MCP Host is a Kubernetes-native service that reads Host CRD configuration and provides LLM access via OpenAI, Anthropic Claude, Z.AI, or Alibaba Bailian. It exposes an HTTP RPC endpoint for receiving messages from channel-reader and connects to MCP (Model Context Protocol) servers for tool capabilities.+MCP Host is a Kubernetes-native service that reads Host CRD configuration and provides LLM access through any of 24 provider ids (OpenAI, Anthropic Claude, Google Vertex AI and Gemini, Amazon Bedrock, Azure OpenAI, OpenAI-compatible APIs, and ChatGPT/Grok subscriptions). It exposes an HTTP RPC endpoint for receiving messages from channel-reader and connects to MCP (Model Context Protocol) servers for tool capabilities.## Features- Reads Host CRD from Kubernetes- Fetches API keys from referenced Kubernetes Secret-- Supports OpenAI, Anthropic Claude, Z.AI, and Bailian providers (see [Supported LLM Providers](#supported-llm-providers))+- Supports 24 LLM provider ids (see [Supported LLM Providers](#supported-llm-providers))- Watches for Host CRD changes and reloads configuration- HTTP RPC server for receiving messages from channel-reader- Connects to MCP servers via host-context-controller service for tool capabilities@@ -17,52 +17,274 @@ MCP Host is a Kubernetes-native service that reads Host CRD configuration and pr### Environment Variables-| Variable | Explanation | Canonical example |-| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `CLERUM_DEV_MODE` | Enables local/dev bootstrap mode that bypasses Host CRD discovery and reads host/runtime config from env. | `CLERUM_DEV_MODE=true` |-| `CLERUM_HOST_NAME` | Selects which Host CRD to load in production mode; in non-production fallback it defaults to `dev-host`. | `CLERUM_HOST_NAME=chatllm` |-| `CLERUM_NAMESPACE` | Sets the Kubernetes namespace used for Host and Secret lookup when running in cluster mode. | `CLERUM_NAMESPACE=mcp-host` |-| `CLERUM_SERVER_PORT` | Sets the HTTP listen port for the runtime API server. | `CLERUM_SERVER_PORT=8080` |-| `CLERUM_CONTEXT_MAPPER_URL` | Points to the host-context-controller endpoint used to resolve MCP servers for a context. | `CLERUM_CONTEXT_MAPPER_URL=http://host-context-controller-api-gateway.control-plane.svc.cluster.local:8081` |-| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | Controls polling interval (milliseconds) for MCP server config changes from context mapper. | `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL=30000` |-| `HCC_AUTHORITY_MAX_STALENESS_MS` | Maximum time a previously published MCP fleet may survive an unavailable HCC (default 180000 ms; hard-capped at 600000 ms). It must be greater than `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` in cluster mode; invalid combinations fail startup. Minikube pins 60000 ms for its deterministic staleness E2E. | `HCC_AUTHORITY_MAX_STALENESS_MS=180000` |-| `CLERUM_HOST_CONFIG` | Provides a full Host spec as JSON in dev mode, overriding provider/model context env composition. | `CLERUM_HOST_CONFIG={"host":"dev-host","contextRef":"dev-context","secretRef":"dev-secret","model":{"provider":"openai","name":"gpt-5.4-mini"}}` |-| `CLERUM_MODEL_PROVIDER` | Chooses the model provider in dev mode when `CLERUM_HOST_CONFIG` is not set. | `CLERUM_MODEL_PROVIDER=openai` |-| `CLERUM_MODEL_NAME` | Overrides the default provider model name in dev mode. Used only when `CLERUM_MODEL_PROVIDER` is also set; an auto-detected provider keeps its default model. | `CLERUM_MODEL_NAME=gpt-5.4-mini` |-| `CLERUM_MCP_SERVERS` | Supplies dev MCP server definitions as JSON so you can run without context mapper. Each entry needs `name`, `contextRef`, `transport`, `enabled`, and a `status` object — a server whose `status.ready` is not `true` is parsed but skipped as "not ready". | `CLERUM_MCP_SERVERS=[{"name":"filesystem","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://localhost:3101"},"enabled":true,"status":{"deployed":true,"ready":true}}]` |-| `CLERUM_MCP_TOOL_TIMEOUT_MS` | Per-call timeout passed to MCP SDK `Client.callTool(...)` requests. The effective timeout is still bounded by any caller workflow or snippet step budget. | `CLERUM_MCP_TOOL_TIMEOUT_MS=1500000` |-| `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS` | Maximum total MCP SDK tool-call budget used at the SDK request boundary. Operators may tune it up to the existing workflow step ceiling; invalid values fail closed at runtime. | `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS=1500000` |-| `OPENAI_API_KEY` | OpenAI API key used by dev mode when provider selection resolves to OpenAI. | `OPENAI_API_KEY=sk-xxxx` |-| `CLAUDE_API_KEY` | Anthropic API key used by dev mode when provider selection resolves to Claude. | `CLAUDE_API_KEY=sk-ant-xxxx` |-| `ZAI_API_KEY` | ZAI API key used by dev mode when provider selection resolves to ZAI. | `ZAI_API_KEY=zai-xxxx` |-| `BAILIAN_API_KEY` | Bailian API key used by dev mode when provider selection resolves to Bailian/Qwen. | `BAILIAN_API_KEY=ba-xxxx` |-| `CLERUM_AGENT_TASK_DELAY` | Minimum interval in milliseconds between task dispatches; does not delay individual tool iterations. | `CLERUM_AGENT_TASK_DELAY=3` |-| `CLERUM_AGENT_MAX_TASK_DURATION` | Maximum active task execution time in milliseconds (24 hours), accumulated across approval resumptions. Approval waiting is excluded. | `CLERUM_AGENT_MAX_TASK_DURATION=86400000` |-| `CLERUM_AGENT_MAX_TOOL_CALLS` | Maximum LLM/tool iterations per task; each iteration may call multiple tools. Configured per Host process. | `CLERUM_AGENT_MAX_TOOL_CALLS=1000` |-| `CLERUM_AGENT_MAX_QUEUE_SIZE` | Maximum pending queue size before new tasks are rejected/back-pressured. | `CLERUM_AGENT_MAX_QUEUE_SIZE=100` |-| `CLERUM_ENABLE_APPROVAL` | Enables the approval gate workflow for tool execution decisions. | `CLERUM_ENABLE_APPROVAL=true` |-| `CLERUM_APPROVAL_CONFIG` | JSON config for approval policy/channels when not sourced from Host CRD. | `CLERUM_APPROVAL_CONFIG={"defaultPolicy":"designated_approvers","channels":{"telegram":{"enabled":true,"approvers":["123456"]}}}` |-| `CLERUM_ENABLE_NUDGE` | Enables the nudge controller that pushes model/tool retry guidance when output is rejected. | `CLERUM_ENABLE_NUDGE=false` |-| `CLERUM_NUDGE_MAX_ITERATIONS` | Maximum number of nudge cycles allowed for a task. | `CLERUM_NUDGE_MAX_ITERATIONS=3` |-| `CLERUM_CONTEXT_MAX_TOKENS` | Token budget used by context compaction when the model's allowlist row carries no context window. `codex-subscription` and `grok-subscription` models use 256000 instead; the Host logs `context_window_resolved` with the window and its source. | `CLERUM_CONTEXT_MAX_TOKENS=100000` |-| `CLERUM_COMPACTION_PRE_PRUNE` | Master switch for pre-pruning the history (deduplication, one-lining, JSON truncation, media stripping). It runs only once the history reaches the compaction threshold (80% of the context window), before any compaction tier is chosen, and at history rehydration under the same threshold. On by default; set to `false` to disable every pass at once. | `CLERUM_COMPACTION_PRE_PRUNE=true` |-| `CLERUM_WORKSPACE_PATH` | Base workspace path used by native tools and workspace-aware operations. | `CLERUM_WORKSPACE_PATH=/workspace` |-| `CLERUM_SHELL_TIMEOUT` | Maximum execution time in milliseconds for shell native-tool commands. A value whose sum with the 6000 ms shell cleanup window exceeds 2^31-1 ms (the Node.js timer limit), that is any value above 2147477647, is rejected and the Host stops at startup. | `CLERUM_SHELL_TIMEOUT=1500000` |-| `CLERUM_TOOL_TIMEOUT` | Maximum execution time in milliseconds for native tool wrapper calls. This is separate from the MCP SDK request timeout controlled by `CLERUM_MCP_TOOL_TIMEOUT_MS`. Like `CLERUM_SHELL_TIMEOUT`, a value above 2147477647 (value + 6000 ms > 2^31-1 ms) is rejected and the Host stops at startup. | `CLERUM_TOOL_TIMEOUT=1500000` |-| `CLERUM_TOOL_PROGRESS_INTERVAL_MS` | Milliseconds between native-tool progress snapshots. Default 30000. Set 0 to disable periodic progress snapshots; any other value must be a whole decimal integer from 1000 to 2147483647 (inclusive). Any other explicit value, including an empty one, stops the Host at startup; values are never clamped or replaced by the default. | `CLERUM_TOOL_PROGRESS_INTERVAL_MS=30000` |-| `CLERUM_HTTP_ALLOWLIST` | Comma-separated allowlist of outbound hosts/URLs allowed for HTTP native tools. With an allowlist set, you can also skip per-call approval by adding `tools: { http_request: false }` under `Host.spec.approval` (see Host CRD). | `CLERUM_HTTP_ALLOWLIST=api.github.com,example.com` |-| `CLERUM_ENV_ALLOWLIST` | Comma-separated list of environment variables forwarded into native tool execution contexts. | `CLERUM_ENV_ALLOWLIST=PATH,HOME,USER,SHELL,LANG,TERM` |-| `CLERUM_MEMORY_MAX_SIZE` | Maximum bytes reserved for in-memory native tool buffers/state. | `CLERUM_MEMORY_MAX_SIZE=1048576` |-| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | Enables attachment passthrough in runtime responses when tools return supported media. | `CLERUM_ENABLE_RESPONSE_ATTACHMENTS=true` |-| `CLERUM_ATTACHMENT_MAX_COUNT` | Maximum number of attachments returned per response. | `CLERUM_ATTACHMENT_MAX_COUNT=3` |-| `CLERUM_ATTACHMENT_MAX_BYTES` | Maximum decoded size per attachment in bytes (oversized payloads are dropped). | `CLERUM_ATTACHMENT_MAX_BYTES=52428800` |-| `CLERUM_ATTACHMENT_FILE_MAX_BYTES` | Maximum decoded bytes per incoming `kind:'file'` attachment, default and ceiling 11 MiB (11,534,336 bytes). The chat body parser answers HTTP 413 for any larger file before admission; above a lower limit, up to 11 MiB, admission answers `FILE_ATTACHMENT_TOO_LARGE`. Files have a 16 MiB base64 quota; the message share is 6 MiB and the body 24 MiB. An invalid or above-ceiling setting stops the Host at startup. | `CLERUM_ATTACHMENT_FILE_MAX_BYTES=11534336` |-| `CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES` | Maximum bytes per native attachment text page, default 64 KiB (65,536 bytes), configurable up to 1 MiB (1,048,576 bytes). Truncated text continues from its byte offset. Native attachment pages remain inline and exempt from spillover. Byte size is independent of token cost; do not infer a fixed bytes-per-token ratio. An invalid or above-ceiling setting stops the Host at startup. | `CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES=65536` |-| `CLERUM_MEMORY_ENABLED` | Enables workspace memory persistence features. | `CLERUM_MEMORY_ENABLED=true` |-| `CLERUM_MEMORY_WORKSPACE_PATH` | Sets workspace directory path used when memory mode is enabled. | `CLERUM_MEMORY_WORKSPACE_PATH=/workspace` |-| `CLERUM_PERSONALIZATION_ENABLED` | Enables identity/personalization seeding behavior. | `CLERUM_PERSONALIZATION_ENABLED=true` |-| `CLERUM_IDENTITY_SEED` | JSON identity seed used to initialize personalization artifacts when enabled. | `CLERUM_IDENTITY_SEED={"displayName":"Clerum Agent","tone":"concise"}` |-| `NODE_ENV` | Influences production checks and defaults (for example strict host-name requirement in production). | `NODE_ENV=production` |+mcp-host reads its settings from the process environment. Most are read once at+startup (`src/config.ts`), so a change needs a pod restart. Unless a row says+otherwise, an unset variable takes the default shown.++**Source column.** A cluster-mode mcp-host gets its env from three places:++- **HCC**: set per Host by host-context-controller as container `env`+ (`host-context-controller/src/hostReconciler.ts`). These win over the+ ConfigMap.+- **CM**: the shared `mcp-host-config` ConfigMap, loaded with `envFrom` into+ every Host pod (name set by HCC's `CONTEXT_MAPPER_HOST_CONFIGMAP_NAME`).+ `deploy/base` does not ship this ConfigMap and the `envFrom` reference is not+ optional, so you must create it; the minikube overlay ships one in+ `deploy/overlays/minikube/configmaps/mcp-host-config.yaml`. Where the table+ gives a CM value, it is the minikube value.+- **WRC**: set by the workflow-recipe controller on recipe-bound mcp-host pods+ (`workflow-recipes/src/workflow/podFactory.ts`).++**dev** marks local dev-mode settings. A dash means no shipped manifest sets+it. Rows marked _no effect_ are parsed but nothing in the current code reads+the value.++Separately, the per-Host `host-<hostRef>-env` ConfigMap and+`host-<hostRef>-env-secret` Secret are watched at runtime and feed tool+subprocess env and capability checks, not the startup settings below.+Precedence there is host Secret > host ConfigMap > LLM Secret > process env.++#### Core runtime++| Variable | Default | Source | Description |+| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `CLERUM_HOST_NAME` | `dev-host` unless `NODE_ENV=production` | HCC (Host name); CM | Host CRD to load. With `NODE_ENV=production` and dev mode off, a missing value stops the Host at startup. |+| `CLERUM_NAMESPACE` | `default` | HCC (pod namespace) | Namespace for Host, Secret and ConfigMap lookups. |+| `NODE_ENV` | unset | - | `production` makes `CLERUM_HOST_NAME` required. |+| `CLERUM_SERVER_PORT` | `8080` | CM `8080` | Runtime API listen port. |+| `CLERUM_WORKSPACE_PATH` | process working directory | HCC | Root directory for native tools. HCC sets `/config/workspace` for desktop Hosts and its configured workspace path otherwise. |+| `CLERUM_LLM_SECRET_REF` | - | HCC (`spec.secretRef`) | _No effect_ in mcp-host; it is in the pod template so a `secretRef` change rolls the pod. mcp-host reads the Secret name from the Host CRD. |+| `CLERUM_CONTEXT_MAPPER_URL` | `http://host-context-controller-api-gateway.control-plane.svc.cluster.local:8081` (`http://localhost:8081` in dev mode) | CM | host-context-controller endpoint that resolves the Host's MCP servers. |+| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | `30000` | CM `30000` | Milliseconds between MCP server polls. In cluster mode it must be lower than `HCC_AUTHORITY_MAX_STALENESS_MS` or the Host stops at startup. |+| `HCC_AUTHORITY_MAX_STALENESS_MS` | `180000` (capped at `600000`) | CM `60000` | How long the last MCP fleet survives while HCC is unreachable (5xx or transport errors). Identity failures (401/403) revoke at once. An invalid value logs a warning and uses the default. Minikube pins 60000 for its staleness E2E. |+| `CLERUM_MCP_STATUS_HEARTBEAT_INTERVAL` | `30000` | - | Milliseconds between MCP status heartbeats. A set value that is not a positive integer stops the Host at startup. |+| `CLERUM_MCP_STATUS_HEARTBEAT_TIMEOUT_MS` | `25000` | - | Timeout for one MCP status heartbeat. Same validation as the interval. |+| `CLERUM_MAX_CONCURRENT_SESSIONS` | `3` | - | Sessions processed at the same time. |+| `CLERUM_ALLOWED_ORIGINS` | empty | - | Comma-separated CORS origins. Empty sends no `Access-Control-Allow-Origin` header. |+| `MCP_PROXY_ENABLED` | `false` | CM `false` | Send MCP traffic through mcp-proxy instead of connecting to each MCP server directly. |+| `MCP_PROXY_URL` | `http://mcp-proxy.mcp-server.svc.cluster.local:8083` (`http://localhost:8083` in dev mode) | CM | mcp-proxy address, used when `MCP_PROXY_ENABLED=true`. |+| `MCP_HOST_ACTIVITY_BUFFER_SIZE` | `1000` | - | Events kept in the Host activity buffer. |+| `MCP_HOST_ACTIVITY_MAX_EVENT_BYTES` | `2048` | - | Maximum size of one activity event. |++#### Auth and runtime tokens++| Variable | Default | Source | Description |+| ------------------------------------------------------ | ------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |+| `CLERUM_ENABLE_AUTH` | `true` | CM `true` | Verify RPC JWTs on runtime routes. |+| `CLERUM_AUTH_JWT_PUBLIC_KEY` | empty | CM; WRC | PEM public key for RPC JWTs. Literal `\n` sequences become newlines. Must pair with control-api's RPC signing key. |+| `CLERUM_AUTH_JWT_ISSUER` | `control-api` | CM; WRC | Expected `iss`. |+| `CLERUM_AUTH_JWT_AUDIENCE` | `rpc-proxy` | CM; WRC | Expected `aud`. control-api stamps `rpc-proxy` on every RPC token. |+| `WRC_PUBLIC_KEY_PEM` | empty | WRC | Public key for workflow-mode tokens (issuer `clerum-wrc`). |+| `MCP_HOST_RUNTIME_ACCESS_TOKEN` | empty | HCC (Secret); WRC | Runtime access token for platform calls (usage reporting, workflow approval gating, subscription proxies). Never logged or passed to tools. |+| `MCP_HOST_RUNTIME_REFRESH_TOKEN` | empty | HCC (Secret); WRC | Refresh token for the runtime access token. |+| `MCP_HOST_WORKFLOW_CONTROL_TOKEN` | empty | HCC (Secret) | Token for the workflow tools (`clerum__list_workflows`, `clerum__trigger_workflow`, ...). |+| `MCP_HOST_WORKFLOW_CONTROL_TOKEN_FILE` | empty | HCC; WRC | File holding the workflow control token. |+| `MCP_HOST_GATEWAY_URL` | empty | HCC; WRC | Gateway used for token refresh and workflow calls. |+| `MCP_HOST_RUNTIME_AUTH_STATE_DIR` | `/var/run/clerum/workflow-auth` | HCC; WRC | Directory that stores refreshed runtime tokens. |+| `CLERUM_WORKFLOW_AUTH_STATE_DIR` | - | - | Older name for the same directory; used only when `MCP_HOST_RUNTIME_AUTH_STATE_DIR` is unset. |+| `MCP_HOST_RUNTIME_AUTH_PROACTIVE_REFRESH_ENABLED` | `true` | - | Refresh runtime tokens before they expire. Only `false` turns it off. |+| `MCP_HOST_RUNTIME_AUTH_PROACTIVE_REFRESH_MARGIN_SEC` | `600` | - | Refresh this many seconds before the refresh token expires. |+| `MCP_HOST_RUNTIME_AUTH_PROACTIVE_REFRESH_MIN_SEC` | `60` | - | Minimum seconds between proactive refreshes. |+| `MCP_HOST_RUNTIME_AUTH_PROACTIVE_REFRESH_FALLBACK_SEC` | `1800` | - | Refresh interval when the token expiry cannot be read. |+| `MCP_HOST_RUNTIME_AUTH_DEGRADED_AFTER_FAILURES` | `3` | - | Consecutive recovery failures before the runtime-auth degraded gauge is set. |++#### LLM and models++| Variable | Default | Source | Description |+| --------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Provider credential env vars | - | dev | In dev mode, each provider's key is read from its env var (`OPENAI_API_KEY`, `CLAUDE_API_KEY`, `ZAI_API_KEY`, `BAILIAN_API_KEY`, ...; Bedrock needs `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`). In cluster mode keys come from the Secret in `Host.spec.secretRef`. Full list: [Supported LLM Providers](#supported-llm-providers). |+| `VERTEX_PROJECT_ID`, `VERTEX_LOCATION` | `VERTEX_LOCATION`: `us-central1` | - | Non-secret Vertex AI settings, read from the mcp-host process environment. `VERTEX_PROJECT_ID` falls back to the service account's `project_id`. |+| `AWS_REGION` | - | - | Region for Amazon Bedrock (required for Bedrock), read from the process environment. |+| `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_VERSION` | - | - | Azure OpenAI resource endpoint (required for Azure; must be `https`) and optional API version, read from the process environment. |+| `CLERUM_LLM_ALLOWED_MODELS_CM` | `clerum-llm-allowed-models` | - | Name of the LLM allowlist ConfigMap that control-api writes. A test/canary override only: pointing it at a ConfigMap control-api does not write leaves the Host with no allowed models. |+| `MCP_HOST_CODEX_SUBSCRIPTION_ENABLED` | `false` | CM `true`; WRC | Allow the `codex-subscription` provider. Only the exact value `true` enables it. See [Use a ChatGPT or Grok subscription](../docs/how-to/connect-llm-subscription.md). |+| `MCP_HOST_GROK_SUBSCRIPTION_ENABLED` | `false` | HCC (only when the Host is eligible for Grok); WRC | Allow the `grok-subscription` provider. HCC adds it only for Hosts whose Grok projection grants execution, so you do not set it in the ConfigMap. |+| `CODEX_LLM_PROXY_RUNTIME_URL` | `http://codex-llm-proxy.control-plane.svc.cluster.local:8080` | WRC | codex-llm-proxy address. |+| `GROK_LLM_PROXY_RUNTIME_URL` | `http://grok-llm-proxy.control-plane.svc.cluster.local:8080` | WRC | grok-llm-proxy address. |+| `CODEX_POLICY_REVISION`, `CODEX_POLICY_HASH` | `1`, empty | - | Test/dev override. Host chat computes the policy digest from the allowlist ConfigMap annotations; an empty hash is not a grant. |+| `GROK_POLICY_REVISION`, `GROK_POLICY_HASH` | `1`, empty | - | Same, for Grok. |+| `CLERUM_PROMPT_CACHE_ENABLED` | `true` | - | Build the system prompt in cacheable tiers; Anthropic receives `cache_control` markers. Set `false` to roll back. |+| `CLERUM_TOKENIZER_DRYRUN` | `true` | - | Compute both the heuristic and the real token count, but pick the compaction tier from the heuristic (metrics only). |+| `CLERUM_TOKENIZER_OFFLINE` | `true` | - | Skip the Anthropic token-count network call and use the heuristic upper bound. |+| `MCP_HOST_WORKFLOW_MAX_OUTPUT_TOKENS` | unset | - | Output-token cap for workflow steps, 1 to 65536. An invalid value throws. |++#### Agent loop, approvals and budgets++| Variable | Default | Source | Description |+| ----------------------------------- | ---------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `CLERUM_AGENT_TASK_DELAY` | `3` | CM `3` | Minimum milliseconds between task dispatches; does not delay tool iterations. `0` disables spacing. |+| `CLERUM_AGENT_MAX_TASK_DURATION` | `86400000` | CM `86400000` | Maximum active execution time per task in milliseconds (24 hours), summed across approval resumptions. Approval waiting is excluded. |+| `CLERUM_AGENT_MAX_TOOL_CALLS` | `1000` | CM `1000` | Maximum LLM/tool iterations per task; one iteration may call several tools. |+| `CLERUM_AGENT_MAX_QUEUE_SIZE` | `100` | CM `100` | Size of the message queue. |+| `CLERUM_ENABLE_APPROVAL` | `true` | - | Enable the tool approval gate. |+| `CLERUM_APPROVAL_CONFIG` | unset | CM | Approval policy as JSON. Used only when the Host has no `spec.approval`. Example: `{"defaultPolicy":"designated_approvers","channels":{"telegram":{"enabled":true,"approvers":["123456"]}}}`. See [Configure approvals](../docs/how-to/configure-approvals.md). |+| `CLERUM_APPROVAL_TIMEOUT` | `0` | CM `0` | Milliseconds before an unanswered approval is auto-denied. `0` disables the timeout. |+| `CLERUM_PENDING_APPROVAL_TTL_HOURS` | `168` | - | Lifetime of a stored pending approval (7 days). |+| `CLERUM_BUDGETS_ENABLED` | `false` | CM `true` | Enforce token budgets. See [Track usage and set token budgets](../docs/how-to/token-budgets-and-usage.md). |+| `CLERUM_ENABLE_NUDGE` | `false` | - | _No effect_ in the current code. |+| `CLERUM_NUDGE_MAX_ITERATIONS` | `3` | - | _No effect_ in the current code. |++#### Tools++| Variable | Default | Source | Description |+| ------------------------------------------ | -------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `CLERUM_SHELL_TIMEOUT` | `1500000` | CM `1500000` | Maximum milliseconds for a shell command. Any value above 2147477647 (value + 6000 ms cleanup > 2^31-1 ms) stops the Host at startup. |+| `CLERUM_TOOL_TIMEOUT` | `1500000` | CM `1500000` | Maximum milliseconds for a native tool call. Separate from the MCP timeout below. Same upper bound as `CLERUM_SHELL_TIMEOUT`. |+| `CLERUM_TOOL_PROGRESS_INTERVAL_MS` | `30000` | CM `5000` | Milliseconds between native-tool progress snapshots. `0` disables them; otherwise a whole number from 1000 to 2147483647. Any other explicit value, including an empty one, stops the Host at startup. |+| `CLERUM_MCP_TOOL_TIMEOUT_MS` | `1500000` | CM `1500000` | Per-call timeout for MCP tool requests, still bounded by any caller deadline. |+| `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS` | `1500000` | CM `1500000` | Total MCP request budget. Must be a positive integer up to 2147483647 and not lower than `CLERUM_MCP_TOOL_TIMEOUT_MS` (unless the caller passes a shorter timeout); otherwise the tool call fails. |+| `CLERUM_HTTP_ALLOWLIST` | empty | - | Comma-separated hosts or URLs the `http_request` tool may reach. With an allowlist set you can also skip per-call approval with `tools: { http_request: false }` under `Host.spec.approval`. |+| `CLERUM_ENV_ALLOWLIST` | `PATH,HOME,USER,SHELL,LANG,TERM` | - | Comma-separated env vars passed to native tool subprocesses. |+| `CLERUM_TOOL_SPILLOVER_ENABLED` | `true` | - | Store large tool results outside the conversation and keep a reference inline. `false` keeps full output inline. |+| `CLERUM_TOOL_SPILLOVER_THRESHOLD` | `8192` | - | Bytes above which a tool result spills over. An invalid value stops the Host at startup. |+| `CLERUM_SPILLOVER_TTL_HOURS` | `168` | - | Lifetime of spilled results. |+| `CLERUM_SPILLOVER_GC_INTERVAL_MINUTES` | `60` | - | Minutes between spillover clean-up sweeps. `0` disables the timer; the startup sweep still runs. |+| `CLERUM_NATIVE_TOOL_PRESENTATION` | `direct` | - | `direct` keeps every native tool in the tool list. `auto` moves native tools whose definition is larger than `CLERUM_NATIVE_TOOL_DISCOVERY_BYTES` behind search/describe/call. Other values stop the Host at startup. |+| `CLERUM_NATIVE_TOOL_DISCOVERY_BYTES` | `2048` | - | Size budget for one native tool definition in `auto` mode. Validated even in `direct` mode. |+| `CODEX_TOOL_PRESENTATION` | `direct` | - | Tool presentation when the provider chain includes `codex-subscription` or `grok-subscription`: `auto`, `direct` or `discovery`. Other values stop the Host at startup. |+| `CODEX_TOOL_DISCOVERY_BYTES` | `32768` | - | Discovery threshold for `CODEX_TOOL_PRESENTATION`. Must be a positive integer. |+| `CLERUM_DYNAMIC_TOOLS_ENABLED` | `false` | - | Put MCP tools behind search/describe/call for other providers. |+| `CLERUM_DYNAMIC_TOOLS_THRESHOLD` | `60` | - | Minimum MCP tool count before dynamic tools turn on. |+| `MCP_CATALOG_BOOTSTRAP_ENABLED` | `true` | - | Open OAuth-backed MCP connections eagerly at the start of a turn, using grant-existence probes. `false` returns to lazy admission. |+| `MCP_CATALOG_BOOTSTRAP_WAIT_BUDGET_MS` | `4000` | - | Total time a turn waits for probes. Must be larger than the probe timeout. |+| `MCP_CATALOG_BOOTSTRAP_PROBE_TIMEOUT_MS` | `2000` | - | Timeout for one probe. |+| `MCP_CATALOG_BOOTSTRAP_CONNECT_TIMEOUT_MS` | `8000` | - | Connect timeout for a probed server. |+| `MCP_CATALOG_BOOTSTRAP_NEGATIVE_TTL_MS` | `15000` | - | How long a "no grant" result is cached. |+| `MCP_CATALOG_BOOTSTRAP_FAILURE_TTL_MS` | `60000` | - | How long a failed probe is cached. |+| `MCP_CATALOG_BOOTSTRAP_PROBES_PER_MIN` | `20` | - | Probe rate limit. Must stay below 60, the control-api OAuth broker bucket, so probes cannot starve token issuance. |+| `MCP_CATALOG_BOOTSTRAP_BACKOFF_MS` | `30000` | - | Back-off after probe failures. All `MCP_CATALOG_BOOTSTRAP_*` numbers stop the Host at startup when invalid. |+| `CLERUM_DESKTOP_X11` | - | HCC (desktop) | `true` registers the X11 desktop tools. HCC sets it from `Host.spec.desktop.x11`. |+| `CLERUM_DESKTOP_BROWSER` | - | HCC (desktop) | `true` registers the browser tools. HCC sets it from `Host.spec.desktop.browser`. |+| `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` | unset | - | Chromium binary for the browser tools. |+| `CLERUM_MEMORY_MAX_SIZE` | `1048576` | - | _No effect_ in the current code. |++#### Attachments and files++| Variable | Default | Source | Description |+| ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | `true` | CM `true` | Pass tool-produced attachments back in responses. `false` disables it for non-workflow responses. |+| `CLERUM_ATTACHMENT_MAX_COUNT` | `3` | CM `3` | Maximum attachments per response. |+| `CLERUM_ATTACHMENT_MAX_BYTES` | `52428800` (50 MiB) | CM `52428800` | Maximum decoded size of one outgoing attachment; larger ones are dropped. Also caps workflow result attachments. |+| `CLERUM_ATTACHMENT_FILE_MAX_BYTES` | `11534336` (11 MiB, also the ceiling) | - | Maximum decoded bytes per incoming `kind:'file'` attachment. The chat body parser answers HTTP 413 for any larger file; above a lower limit, admission answers `FILE_ATTACHMENT_TOO_LARGE`. Files have a 16 MiB base64 quota; the message share is 6 MiB and the body 24 MiB. An invalid or above-ceiling value stops the Host at startup. |+| `CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES` | `65536` (64 KiB; up to 1 MiB) | - | Maximum bytes per text page returned by `clerum__attachment_read`. Truncated text continues from its byte offset. Pages stay inline and are exempt from spillover. Bytes are not tokens; do not assume a fixed ratio. An invalid or above-ceiling value stops the Host at startup. |+| `CLERUM_OUTPUT_DIR` | see description | - | Directory for generated files. Unset: `/output` in workflow mode, otherwise `<memory workspace>/outputs`. |+| `CLERUM_WORKFLOW_OUTPUT_QUOTA_MB` | `50` | - | Soft quota for generated files in the output directory. |+| `CLERUM_CONTEXT_FILES_MOUNTS` | - | HCC | JSON list of SharedFileSystem mounts for the Host's Context. The context-files tools are registered only when it lists at least one mount. |+| `CLERUM_CONTEXT_FILES_MAX_READ_BYTES` | `10485760` (10 MiB) | - | Maximum bytes one context-files read returns. |+| `CLERUM_CONTEXT_FILES_MAX_LIST_ENTRIES` | `1000` | - | Maximum entries one context-files listing returns. |+| `MCP_HOST_GFS_MAX_FILE_BYTES` | `16777216` (16 MiB; up to 200 MiB) | CM `16777216` | Maximum size of one GFS file transfer. |+| `MCP_HOST_GFS_DOWNLOAD_STORAGE_PERCENT` | `70` (up to 100) | CM `70` | Share of the workspace volume that retained GFS downloads may use. |+| `MCP_HOST_GFS_CALLER_DOWNLOAD_CONCURRENCY` | `1` (up to 2) | CM `1` | Active GFS downloads per caller. |+| `MCP_HOST_GFS_DOWNLOAD_TTL_HOURS` | `168` (up to 8760) | CM `168` | Retention of GFS downloads. All four `MCP_HOST_GFS_*` limits must be positive integers within their ceiling or the Host fails when it loads them. |+| `MCP_HOST_GFS_SCOPES` | empty | WRC | Comma-separated GFS scopes for workflow steps (`gfs.read`, `gfs.write`, `gfs.delete`, `gfs.manage_acl`, `gfs.share`). Any unknown scope empties the set. |+| `MCP_HOST_GFS_TOKEN`, `MCP_HOST_GFS_TOKEN_FILE` | file `/var/run/clerum/workflow-tokens/mcp-host-gfs-token` | - | GFS access token, given directly or as a file path. |+| `MCP_HOST_GFSC_BASE_URL` | `http://gfsc.gfs.svc.cluster.local:8087` | - | GFS reader endpoint. |+| `MCP_HOST_GFSC_WRITER_BASE_URL` | `http://gfsc-writer.gfs.svc.cluster.local:8087` | - | GFS writer endpoint. |+| `MCP_HOST_GFS_DOWNLOAD_STORAGE_BYTES`, `MCP_HOST_GFS_CALLER_DOWNLOAD_STORAGE_BYTES`, `MCP_HOST_GFS_CALLER_DOWNLOAD_MAX_FILES` | - | - | Removed. Ignored, with a warning; use `MCP_HOST_GFS_DOWNLOAD_STORAGE_PERCENT`. |++#### Sessions, stateless lifecycle and compaction++| Variable | Default | Source | Description |+| -------------------------------------------- | ---------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `CLERUM_SESSION_STORE` | `memory` | CM `sqlite`; HCC (stateless) | Conversation store: `memory` (no durability), `sqlite`, or `dual` (both, for parity checks). Unknown values log a warning and use `memory`. |+| `CLERUM_SESSION_DB_DIR` | empty | HCC (stateless) | Directory for `state.db`. Takes precedence over `CLERUM_SESSION_DB_PATH`. |+| `CLERUM_SESSION_DB_PATH` | empty | - | Explicit `state.db` path. Without either setting the store uses the workspace volume, or a temp file in dev. |+| `CLERUM_STATELESS_LIFECYCLE` | `false` | HCC (stateless) | Run as a stateless Host: the pod can be suspended and woken by HCC. |+| `CLERUM_STATELESS_HEARTBEAT_INTERVAL_MS` | `30000` | - | Heartbeat cadence HCC uses for suspend decisions. A set value that is not a positive integer stops the Host at startup. |+| `CLERUM_POD_UID` | empty | HCC (stateless) | Pod UID, so HCC can ignore heartbeats from old pods. |+| `CLERUM_STATELESS_ALLOW_CRON_MANAGE` | `false` | - | Allow `cron_manage` schedules on a stateless Host. Requires `CLERUM_ENABLE_APPROVAL=true` or the Host stops at startup. |+| `CLERUM_DB_BARRIER_MODE` | empty | - | `full` turns on the fsync barrier for always-on Hosts (stateless Hosts always use it). Empty or `normal` leaves it off; other values stop the Host at startup. |+| `CLERUM_CONVERSATION_CACHE_SIZE` | `200` | - | Conversations kept in memory by the SQLite store. |+| `CLERUM_DB_WORKER_HEARTBEAT_MS` | `5000` | - | SQLite worker heartbeat. |+| `CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS` | `2000` | - | Timeout for a synchronous persist. |+| `CLERUM_DB_PERSIST_ASYNC_TIMEOUT_MS` | `5000` | - | Timeout for an asynchronous persist. |+| `CLERUM_DB_CHECKPOINT_EVERY_WRITES` | `100` | - | WAL checkpoint frequency, in writes. |+| `CLERUM_DB_WAL_SIZE_ALARM_BYTES` | `52428800` | - | _No effect_ in the current code. |+| `CLERUM_SESSION_TTL_DAYS` | `90` | CM `90` | _No effect_ in the current code. |+| `CLERUM_SESSION_SEARCH_ENABLED` | `false` | CM `true` | Enable the `clerum__session_search` tool and REST route. Has effect only when a SQLite-backed store is active. |+| `CLERUM_SEARCH_RETENTION_DAYS` | `90` | CM `90` | Retention for the search index, applied by a sweep at startup. |+| `CLERUM_CONTEXT_MAX_TOKENS` | `100000` | CM `100000` | Token budget for compaction when the model's allowlist row has no context window. `codex-subscription` and `grok-subscription` use 256000 instead; the Host logs `context_window_resolved` with the window and its source. A value that is not a positive integer stops the Host at startup. |+| `CLERUM_COMPACTION_PRE_PRUNE` | `true` | - | Master switch for pre-pruning (deduplication, one-lining, JSON truncation, media stripping). It runs once the history reaches the compaction threshold (80% of the context window), before a compaction tier is chosen, and at rehydration under the same threshold. `false` disables every pass. |+| `CLERUM_COMPACTION_PRE_PRUNE_DEDUP` | `true` | - | Deduplication pass. |+| `CLERUM_COMPACTION_PRE_PRUNE_ONE_LINE` | `true` | - | One-line summary pass. |+| `CLERUM_COMPACTION_PRE_PRUNE_JSON_TRUNC` | `true` | - | JSON truncation pass. |+| `CLERUM_COMPACTION_PRE_PRUNE_STRIP_MEDIA` | `true` | - | Media stripping pass. |+| `CLERUM_COMPACTION_PRE_PRUNE_TRUNCATE_BYTES` | `4096` | - | Maximum tool-argument bytes kept by JSON truncation. |+| `CLERUM_COMPACTION_PRE_PRUNE_SUMMARY_TOKENS` | `200` | - | Token size of one-line summaries. |+| `CLERUM_COMPACTION_PROTECTED_TAIL_TURNS` | `3` | - | Most recent turns that pre-pruning never touches. |+| `CLERUM_COMPACTION_INEFFECTIVE_RATIO` | `0.9` | - | A compaction that keeps more than this share of tokens counts as ineffective. |+| `CLERUM_COMPACTION_INEFFECTIVE_MAX_RUN` | `2` | - | Consecutive ineffective compactions before compaction stops for the rest of the task. |+| `CLERUM_COMPACTION_STRUCTURED_SUMMARY` | `false` | - | Use the structured summary template. |++#### Memory and personalization++| Variable | Default | Source | Description |+| -------------------------------- | ---------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |+| `CLERUM_MEMORY_ENABLED` | `false` | CM `true` | Enable workspace memory. Used when the Host has no `spec.memory`. |+| `CLERUM_MEMORY_WORKSPACE_PATH` | `/workspace` (`./workspace` in dev mode) | - | Memory workspace directory, used when the Host has no `spec.memory.workspacePath`. |+| `CLERUM_MEMORY_MD_MAX_BYTES` | `8192` | - | Size cap for `MEMORY.md`. |+| `CLERUM_MEMORY_SCAN_ENABLED` | `true` | - | Reject memory writes that match prompt-injection, exfiltration, invisible-Unicode or sensitive-path patterns. Only `false` turns it off. |+| `CLERUM_PERSONALIZATION_ENABLED` | `false` | CM `false` | Enable identity/personalization seeding. |+| `CLERUM_IDENTITY_SEED` | unset | - | JSON seed with optional `identity`, `soul`, `agents` and `user` strings (contents for `IDENTITY.md`, `SOUL.md`, `AGENTS.md`, `USER.md`). |++#### Guardrails++| Variable | Default | Source | Description |+| ---------------------------- | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `CLERUM_GUARDRAILS_CONFIG` | unset | - | JSON form of `Host.spec.guardrails`, used only when the Host has no `spec.guardrails` (typically dev mode). See [Configure guardrails](../docs/how-to/configure-guardrails.md). |+| `CLERUM_LLM_HOOKS_NAMESPACE` | `llm-hooks` | - | Namespace where installed LlmHook Services live; guardrail hook endpoints resolve against it. |++#### Workflow and Plugin Workload SDK++These apply to recipe-bound mcp-host pods that WRC creates.++| Variable | Default | Source | Description |+| ---------------------------------------------------------------------------- | ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `CLERUM_WORKFLOW_ENABLED` | `false` | WRC | Run in workflow mode. |+| `CLERUM_WORKFLOW_RECIPE`, `CLERUM_WORKFLOW_NAMESPACE` | empty | WRC | Recipe this pod is bound to; workflow requests for another recipe are rejected. |+| `CLERUM_WORKFLOW_APPROVAL_RECIPE` | empty | WRC | Recipe that handles user approval requests. |+| `CLERUM_WORKFLOW_APPROVAL_RECIPE_NAMESPACE` | `mcp-host` | WRC | _No effect_ in mcp-host's current code. |+| `CLERUM_WORKFLOW_MAX_ITERATIONS` | `50` | - | LLM/tool rounds per workflow step before forced wrap-up. A step's `maxIterations` overrides it. |+| `CLERUM_MAX_STEP_TIMEOUT_SECONDS` | `5400` | - | Ceiling for a step's `timeoutSeconds` (larger values are clamped). Must be 60 to 604800; an invalid value logs a warning and uses the default. |+| `CLERUM_WORKFLOW_RESULT_ARTIFACT_POLL_ATTEMPTS` | `180` | - | Polls a chat Host makes for a triggered workflow's result artifacts. |+| `CLERUM_WORKFLOW_RESULT_ARTIFACT_POLL_INTERVAL_MS` | `1000` | - | Milliseconds between those polls. |+| `CLERUM_WRC_URL` | empty | WRC | WRC endpoint, used as the SDK credential broker. |+| `PLUGIN_WORKLOAD_SDK_ENABLED` | `false` | WRC | Enable the Plugin Workload SDK server. |+| `PLUGIN_WORKLOAD_SDK_RUNTIME_MODE` | unset | WRC | `workflow` or `sdk-only`. `workflow` requires `CLERUM_WORKFLOW_ENABLED=true`; `sdk-only` requires it `false` and `PLUGIN_WORKLOAD_SDK_ENABLED=true`. Contradictions stop the Host at startup. |+| `PLUGIN_WORKLOAD_SDK_CAPABILITIES` | empty | WRC | Comma-separated route families: `promptBridge`, `clientNotifications`. Empty exposes none; an unknown value stops the Host at startup. |+| `PLUGIN_WORKLOAD_SDK_WORKLOAD_TOKENS_DIR` | empty | WRC | Directory of per-caller workload token files. |+| `PLUGIN_WORKLOAD_SDK_WORKLOAD_TOKEN`, `PLUGIN_WORKLOAD_SDK_BOUND_CALLER_REF` | empty | dev | Dev-only single workload token and the caller it binds to. |+| `MCP_HOST_PLUGIN_SDK_PORT` | `8099` | - | SDK server port. |+| `MCP_HOST_POD_NAMESPACE` | empty | WRC | Namespace of the recipe pod. |+| `CONTROL_API_GATEWAY_URL` | empty | - | Gateway the SDK calls. |+| `PLUGIN_WORKLOAD_SDK_PROMPT_TIMEOUT_SECONDS` | `120` | - | Timeout for one SDK prompt. |+| `PLUGIN_WORKLOAD_SDK_MAX_CONNECTIONS` | `100` | - | Total SDK connections. |+| `PLUGIN_WORKLOAD_SDK_MAX_CONNECTIONS_PER_WORKLOAD` | `10` | - | SDK connections per workload. |+| `PLUGIN_WORKLOAD_SDK_MAX_RPM_PER_WORKLOAD` | `100` | - | Requests per minute per workload. |+| `PLUGIN_WORKLOAD_SDK_MAX_LLM_RESPONSE_BYTES` | `1048576` | - | Maximum LLM response size returned through the SDK. |++`PLUGIN_WORKLOAD_SDK_TOKEN` is not read as a setting. mcp-host only lists it,+with the runtime tokens above and every provider key, as a reserved secret name+that never reaches tool subprocesses or capability output.++#### Observability++| Variable | Default | Source | Description |+| ------------------------------------------- | ------- | ---------- | ------------------------------------------------------------------------------------ |+| `LOG_LEVEL` | `info` | - | `debug`, `info`, `warn`, `error` or `silent`. |+| `GOVERNED_TRACING_ENABLED` | `true` | - | Report governed run traces. |+| `TRACING_APPROVAL_PROMPT_HISTORY_ENABLED` | `false` | CM `false` | Capture prompt history with approval traces. Only the exact value `true` enables it. |+| `TRACING_APPROVAL_PROMPT_HISTORY_MAX_BYTES` | `16384` | CM `16384` | Size of captured prompt history, 1024 to 32768. |++#### Dev mode++| Variable | Default | Source | Description |+| ----------------------- | ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `CLERUM_DEV_MODE` | `false` | dev | Run without Host CRD discovery; host and model come from env. |+| `CLERUM_HOST_CONFIG` | unset | dev | Full Host spec as JSON, e.g. `{"host":"dev-host","contextRef":"dev-context","secretRef":"dev-secret","model":{"provider":"openai","name":"gpt-5.4-mini"}}`. Takes precedence over the two variables below. |+| `CLERUM_MODEL_PROVIDER` | unset | dev | Provider id when `CLERUM_HOST_CONFIG` is not set. An unknown id stops the Host; unset falls back to the first provider whose API key is present. |+| `CLERUM_MODEL_NAME` | provider default | dev | Model name. Used only together with `CLERUM_MODEL_PROVIDER`; an auto-detected provider keeps its default model. |+| `CLERUM_MCP_SERVERS` | unset | dev | MCP server definitions as JSON, so you can run without host-context-controller. Each entry needs `name`, `contextRef`, `transport`, `enabled` and a `status` object; a server whose `status.ready` is not `true` is skipped. Example: `[{"name":"filesystem","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://localhost:3101"},"enabled":true,"status":{"deployed":true,"ready":true}}]`. |### Host CRD@@ -79,7 +301,7 @@ spec:contextRef: context1secretRef: mcp-host-keys # Reference to Secret containing API keysmodel:- provider: openai # or "claude", "zai", "bailian"+ provider: openai # any of the 24 provider ids belowname: gpt-5.4-mini # Model namechannels:- telegram-channel@@ -89,14 +311,46 @@ spec:### Supported LLM ProvidersConfigured via the Host CRD `spec.model.provider` field (or-`CLERUM_MODEL_PROVIDER` in dev mode):--| Provider | `provider` value | Default Model | API |-| ------------------------------------ | ---------------- | ------------------- | ----------------------- |-| OpenAI | `openai` | `gpt-5.4-mini` | OpenAI Chat Completions |-| Anthropic Claude | `claude` | `claude-sonnet-4-6` | Anthropic Messages |-| ZAI (z.ai) | `zai` | `glm-5.1` | OpenAI-compatible |-| Alibaba Cloud Model Studio (Bailian) | `bailian` | `qwen3-coder-plus` | OpenAI-compatible |+`CLERUM_MODEL_PROVIDER` in dev mode). There are 24 provider ids, defined in+[`packages/llm-providers/index.cjs`](../packages/llm-providers/index.cjs). The+default model is used when no model name is given. In dev mode the key is read+from the env var shown; in a cluster it comes from the Secret named by+`Host.spec.secretRef`, under the matching lowercase key (for example+`openai-api-key`).++| `provider` value | Provider | Default model | Dev-mode credential env |+| -------------------- | ------------------------- | --------------------------------------------------- | --------------------------------------------- |+| `openai` | OpenAI | `gpt-5.4-mini` | `OPENAI_API_KEY` |+| `claude` | Anthropic | `claude-sonnet-4-6` | `CLAUDE_API_KEY` |+| `zai` | Z.AI | `glm-5.1` | `ZAI_API_KEY` |+| `bailian` | Bailian | `qwen3-coder-plus` | `BAILIAN_API_KEY` |+| `vertex` | Google Vertex AI | `gemini-2.5-pro` | `VERTEX_SERVICE_ACCOUNT_JSON` |+| `bedrock` | Amazon Bedrock | `anthropic.claude-sonnet-4-6-v1:0` | `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` |+| `openrouter` | OpenRouter | `anthropic/claude-sonnet-latest` | `OPENROUTER_API_KEY` |+| `gemini` | Google Gemini | `gemini-2.5-flash` | `GEMINI_API_KEY` |+| `deepseek` | DeepSeek | `deepseek-v4-flash` | `DEEPSEEK_API_KEY` |+| `groq` | Groq | `llama-3.3-70b-versatile` | `GROQ_API_KEY` |+| `together` | Together AI | `meta-llama/Llama-3.3-70B-Instruct-Turbo` | `TOGETHER_API_KEY` |+| `fireworks` | Fireworks AI | `accounts/fireworks/models/llama-v3p3-70b-instruct` | `FIREWORKS_API_KEY` |+| `mistral` | Mistral AI | `mistral-medium-latest` | `MISTRAL_API_KEY` |+| `xai` | xAI (Grok) | `grok-4.3` | `XAI_API_KEY` |+| `cerebras` | Cerebras | `gpt-oss-120b` | `CEREBRAS_API_KEY` |+| `deepinfra` | DeepInfra | `deepseek-ai/DeepSeek-V3.2` | `DEEPINFRA_API_KEY` |+| `perplexity` | Perplexity | `sonar-pro` | `PERPLEXITY_API_KEY` |+| `moonshot` | Moonshot (Kimi) | `kimi-k2.6` | `MOONSHOT_API_KEY` |+| `nebius` | Nebius | `Qwen/Qwen3-235B-A22B-Instruct-2507` | `NEBIUS_API_KEY` |+| `novita` | Novita AI | `deepseek/deepseek-v3.2` | `NOVITA_API_KEY` |+| `minimax` | MiniMax | `MiniMax-M2` | `MINIMAX_API_KEY` |+| `azure` | Azure OpenAI | `gpt-4.1` (your deployment name) | `AZURE_OPENAI_API_KEY` |+| `codex-subscription` | OpenAI Codex subscription | none; set a model | none (OAuth sign-in) |+| `grok-subscription` | xAI Grok subscription | none; set a model | none (OAuth sign-in) |++Vertex AI, Bedrock and Azure also need the non-secret settings listed under+[LLM and models](#llm-and-models). The two subscription providers are off unless+their `MCP_HOST_*_SUBSCRIPTION_ENABLED` flag is set; see+[Use a ChatGPT or Grok subscription](../docs/how-to/connect-llm-subscription.md).+Which providers work in which runtime, and how the model allowlist applies, is+in [LLM providers](../docs/llm-providers/README.md).Providers are defined data-first in `src/llm/registryCore.ts` — OpenAI-compatibleproviders are pure data entries (adding one requires a descriptor, not new code).diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex d589c42bd..1928bc87d 100644--- a/mcp-host/package-lock.json+++ b/mcp-host/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-mcp-host",- "version": "0.1.556",+ "version": "0.1.557","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-mcp-host",- "version": "0.1.556",+ "version": "0.1.557","license": "SEE LICENSE IN LICENSE","dependencies": {"@anthropic-ai/sdk": "^0.32.0",diff --git a/mcp-host/package.json b/mcp-host/package.jsonindex 4ea1e8ea3..2e9f5111a 100644--- a/mcp-host/package.json+++ b/mcp-host/package.json@@ -1,6 +1,6 @@{"name": "clerum-mcp-host",- "version": "0.1.556",+ "version": "0.1.557","description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude","main": "dist/main.js","engines": {