Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs: address second-round review on configuration and reference docs

Jose Gabriel Ramirez Encinas243b664f3304
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index 07b0ce9d9..c0d591802 100644
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -897,7 +897,9 @@ host-context-controller/
> `deploy/base/control-plane/host-context-controller.yaml`.
The controller reconciles six CRDs: `McpServer`, `Context`, `Host`,
-`SharedFileSystem`, `GlobalFileSystem`, and `LlmHook`.
+`SharedFileSystem`, `GlobalFileSystem`, and `LlmHook`. It also watches
+`CommunicationChannel` resources in the `channels` namespace to size each
+Host's channel-reader Deployment.
### Operator Reconciliation
@@ -1229,7 +1231,7 @@ For comprehensive testing documentation, see [mcp-servers/README.md §Testing](.
### Namespace Layout & NetworkPolicy Strategy
-Scoped to the four namespaces on the message path — for the full deny-all model across all 12 namespaces, see [platform-topology.md §2](platform-topology.md#2-security-architecture-deny-all-by-default).
+Scoped to the four namespaces on the message path — for the full deny-all model across all 13 namespaces, see [platform-topology.md §2](platform-topology.md#2-security-architecture-deny-all-by-default).
```mermaid
%%{init: {'theme':'base', 'themeVariables': {'fontSize':'12px'}}}%%
@@ -1251,7 +1253,7 @@ flowchart LR
class HCC ctrl
```
-`deploy/base/namespaces.yaml` declares ten namespaces: `channels`, `control-plane`, `mcp-host`, `mcp-server`, `profiles`, `rpc-proxy`, `sandbox-recipes`, `sandbox-ui`, `webhook-ingress`, `gfs`. The core four for the message path are:
+`deploy/base/namespaces.yaml` declares eleven namespaces: `channels`, `control-plane`, `mcp-host`, `mcp-server`, `llm-hooks`, `profiles`, `rpc-proxy`, `sandbox-recipes`, `sandbox-ui`, `webhook-ingress`, `gfs` (the opt-in `ingress` namespace from `deploy/base/ingress/` and the minikube-only `registry` namespace bring the platform total to 13). The core four for the message path are:
- `channels` - channel-reader (no inbound traffic needed)
- `mcp-host` - mcp-host service (receives HTTP from channel-reader)
@@ -1457,29 +1459,27 @@ Default: `your-registry.example.com/evenfire/`
### Full Production Deployment Sequence
+See [Production deployment](../deploy/production.md) for the full rollout order.
+
```bash
# 1. Install CRDs
helm install clerum-crds ./charts/clerum-crds
-# 2. Deploy host-context-controller (operator must run first)
-cd host-context-controller && make deploy
+# 2. Apply the platform manifests (namespaces, host-context-controller,
+# mcp-host, channel-reader, ...). The services have no per-service
+# `make deploy`; build your own kustomize overlay on deploy/base.
+kubectl apply -k <your-overlay>
-# 3. Deploy MCP server secrets and CRDs
-cd mcp-servers && make deploy-all
+# 3. Deploy the example MCP server secrets and McpServer CRDs
+make -C mcp-servers deploy-all
# 4. Create Context CRD (defines which servers are accessible)
kubectl apply -f charts/clerum-crds/examples/context1.yaml
-# 5. Deploy mcp-host
-cd mcp-host && make deploy
-
-# 6. Create Host CRD with API keys secret
+# 5. Create Host CRD with API keys secret
kubectl apply -f charts/clerum-crds/examples/host-chatllm.yaml
-# 7. Deploy channel-reader
-cd channel-reader && make deploy
-
-# 8. Create CommunicationChannel CRD
+# 6. Create CommunicationChannel CRD
kubectl apply -f charts/clerum-crds/examples/channels.yaml
```
diff --git a/docs/architecture/platform-topology.md b/docs/architecture/platform-topology.md
index bf4b93137..ee7b8a60d 100644
--- a/docs/architecture/platform-topology.md
+++ b/docs/architecture/platform-topology.md
@@ -4,7 +4,7 @@
> All other specification documents reference this document for architectural decisions.
> When the architecture changes, update THIS document first, then propagate to specs.
>
-> **Security-First Architecture**: This document defines the 12-namespace architecture,
+> **Security-First Architecture**: This document defines the 13-namespace architecture,
> the controller architecture (HCC + WRC), the Sandbox Recipes Namespace, the RPC Proxy Namespace,
> and the **deny-all by default** security posture across all runtime namespaces.
diff --git a/docs/crds/context.md b/docs/crds/context.md
index be92bea3e..18ceac5f2 100644
--- a/docs/crds/context.md
+++ b/docs/crds/context.md
@@ -22,7 +22,7 @@ inject SharedFileSystem volume mounts into the mcp-host pod.
| `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`). |
+| `spec.gfs.mounts` | object[] | no | Optional Global File System mount intents. Defined in the schema, but host-context-controller does not read it in this release: an entry wires no mount and grants no access. (The CRD description's scope check lives in `host-context-controller/src/contextGfsMount.ts`, which has no production caller yet.) 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
diff --git a/docs/crds/workflowrecipe.md b/docs/crds/workflowrecipe.md
index 2b1c68b81..ccb217b46 100644
--- a/docs/crds/workflowrecipe.md
+++ b/docs/crds/workflowrecipe.md
@@ -3104,18 +3104,20 @@ rolling-back --> rollback-failed (rollback itself fails)
- `failed` --> `active` (must go through `candidate` for retry)
- `rollback-failed` --> any state (terminal; manual cleanup required)
-**Recovery from `failed` state**: Unlike `rollback-failed` (which is terminal), the `failed` state supports a retry path via `failed` --> `candidate`. The operator triggers this transition by annotating the WorkflowRecipe with `clerum.io/retry: "true"`. The controller:
+**Recovery from `failed` state**: Unlike `rollback-failed` (which is terminal), the `failed` state supports a retry path via `failed` --> `candidate`. The operator triggers this transition with the control-api admin endpoint `POST /api/v1/admin/recipes/<name>/retry` (`control-api/src/routes/admin/recipes.ts`). No annotation triggers a retry. The endpoint:
-1. Resets `status.workloads[].phase` to `pending` for all workloads
-2. Preserves existing PVCs and Secrets (does not recreate)
-3. Transitions to `candidate`, re-entering the approval flow
+1. Returns `409 invalid_transition` unless `status.phase` is `failed`
+2. Patches only the status subresource to `phase: candidate`, `message: "Manual retry requested by operator"`; the spec and existing resources are not touched
+3. Leaves the rest to WRC: the next reconcile evaluates WorkflowRecipePolicies again and reconciles the workloads, and the phase settles from their readiness
+
+A recipe that failed a policy check (`message` starting `Policy violation:`) needs this retry after the spec or policy is fixed; editing the spec alone does not re-run enforcement (see [WorkflowRecipePolicy](workflowrecipepolicy.md)).
Retry counting is controller-internal. There is **no** `status.retryCount`
property in the CRD status schema (§12.2) — the status object is structural with
no `x-kubernetes-preserve-unknown-fields`, so such a key would be pruned — and
there is no `WorkflowRecipePolicy.governance.maxRetries` field.
-This avoids the overhead of deleting and recreating the entire recipe (which loses status history and correlation ID) while still requiring re-approval for safety.
+This avoids deleting and recreating the entire recipe, which loses status history and correlation ID.
#### 12.1.1 Simplified Visible States (CLI/Dashboard Layer)
diff --git a/docs/crds/workflowrecipepolicy.md b/docs/crds/workflowrecipepolicy.md
index 810029328..96a77ff1a 100644
--- a/docs/crds/workflowrecipepolicy.md
+++ b/docs/crds/workflowrecipepolicy.md
@@ -24,8 +24,13 @@ Things to know before you write 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.
+ self-heal a policy failure, and editing the spec does not clear it: while
+ the recipe is `failed` with a `Policy violation:` message, WRC skips policy
+ evaluation and the recipe stays `failed`. After you fix the recipe spec (or
+ the policy), call the control-api admin endpoint
+ `POST /api/v1/admin/recipes/<name>/retry`. It moves the recipe to
+ `candidate`, and the next reconcile evaluates the policies again. Deleting
+ and re-creating the recipe also starts it from `candidate`.
- **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.
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index 28f7f6e17..4153bbeed 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -14,8 +14,9 @@ Full per-service variable lists live in each service's README (see
> you create it. Only the minikube overlay ships one
> (`deploy/overlays/minikube/configmaps/mcp-host-config.yaml`); copy it and
> review each value (see [Production deployment](../deploy/production.md)).
-> Variables you leave out take mcp-host's code defaults, so the mcp-host rows
-> below are off unless your ConfigMap sets them.
+> Variables you leave out take mcp-host's code defaults: the mcp-host rows in
+> the two "Off" tables below stay off unless your ConfigMap sets them, and the
+> mcp-host rows under [On by default](#on-by-default) stay on.
Set boolean switches to the lowercase string `true`. Some services also accept
`1` or other casings, but `true` works everywhere.
@@ -36,7 +37,7 @@ Set boolean switches to the lowercase string `true`. Some services also accept
| `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) |
+| `PLUGIN_WORKLOAD_SDK_ENABLED` | workflow-recipes (Deployment env) | The Plugin Workload SDK; WRC passes it to the mcp-host pods of recipes that declare it | [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) |
@@ -45,25 +46,25 @@ Set boolean switches to the lowercase string `true`. Some services also accept
## 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 |
+| Switch | Service | What it turns on |
+| ----------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------ |
+| `CONTROL_API_ENFORCE_IMAGE_ALLOWLIST` | control-api | Reject connector images that are not on the allowlist (off: no image check at all) |
+| `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, mcp-host | Keep prompt history in approval traces |
+| `CLERUM_PERSONALIZATION_ENABLED` | mcp-host | Identity files from `CLERUM_IDENTITY_SEED` at startup when the Host has no 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 |
+| 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, mcp-host | 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
diff --git a/host-context-controller/README.md b/host-context-controller/README.md
index 9f78c0ad8..8298d7ff4 100644
--- a/host-context-controller/README.md
+++ b/host-context-controller/README.md
@@ -642,7 +642,8 @@ unchanged into the gfsc pods (`gfscEnv` in `src/k8s/gfsFactory.ts`):
(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
+applies (`gfs-controller/src/config.ts`; for `GFS_MAX_WRITE_BODY_BYTES`, 16 MiB
+in `gfs-controller/src/api/serve.ts`). `deploy/base` sets only
`GFS_MAX_WRITE_BODY_BYTES` (`25165824`, 24 MiB).
### NetworkPolicy
diff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.json
index ce2ef8678..ff63c4035 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.383",
+ "version": "0.1.384",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-host-context-controller",
- "version": "0.1.383",
+ "version": "0.1.384",
"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.json
index d6a0ec384..eefa0f2ba 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.383",
+ "version": "0.1.384",
"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.md
index 853cb5eae..9f0fdeded 100644
--- a/mcp-host/README.md
+++ b/mcp-host/README.md
@@ -220,11 +220,11 @@ Precedence there is host Secret > host ConfigMap > LLM Secret > process env.
| 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_ENABLED` | `false` | CM `true` | Enable workspace memory. The Host CRD has no memory field, so this variable is the only switch. |
+| `CLERUM_MEMORY_WORKSPACE_PATH` | `/workspace` (`./workspace` in dev mode) | - | Memory workspace directory. |
| `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_PERSONALIZATION_ENABLED` | `false` | CM `false` | Seed identity files from `CLERUM_IDENTITY_SEED` at startup when the Host has no `spec.personalization`. Requires memory to be enabled. |
| `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
@@ -382,7 +382,7 @@ Get your Coding Plan API key at: https://modelstudio.console.alibabacloud.com/
### Per-Tool Approval Overrides
-`Host.spec.approval.tools` is an optional map that overrides each native tool's hard-coded `requiresApproval()` default. Use it to skip per-call approval for tools whose risk you mitigate via a different gate (e.g. `http_request` paired with `CLERUM_HTTP_ALLOWLIST`).
+`Host.spec.approval.tools` is an optional map that overrides each native tool's hard-coded `requiresApproval()` default. Use it to skip per-call approval for tools whose risk you mitigate via a different gate (e.g. `http_request` paired with `CLERUM_HTTP_ALLOWLIST`). `CLERUM_HTTP_ALLOWLIST` is empty by default, and an empty list filters no domains, so set it before you turn off approval for `http_request`.
```yaml
spec:
@@ -391,7 +391,7 @@ spec:
channels:
telegram: { enabled: true }
tools:
- http_request: false # skip approval — relies on CLERUM_HTTP_ALLOWLIST as the gate
+ http_request: false # skip approval — only safe with a non-empty CLERUM_HTTP_ALLOWLIST
shell_exec: true # explicit (matches code default; documents intent)
```
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 0e6daaf99..f0dd480d9 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.558",
+ "version": "0.1.559",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.558",
+ "version": "0.1.559",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 17bcdd016..c02498c8d 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.558",
+ "version": "0.1.559",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {