Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs: address review findings on the feature guides
Jose Gabriel Ramirez Encinasb8d8b075ecc5
diff --git a/docs/how-to/configure-guardrails.md b/docs/how-to/configure-guardrails.mdindex 149f757e6..7eb392f9b 100644--- a/docs/how-to/configure-guardrails.md+++ b/docs/how-to/configure-guardrails.md@@ -87,6 +87,9 @@ spec:action: allowmatch: { tool: { provenance: mcp } }# Strictest wins: this deny beats allow-native.+ # Defence in depth only: http_request already refuses private and+ # metadata IPs. URL predicates are lexical, and URLs with credentials+ # never match.- id: no-metadata-endpointaction: denyreasonCode: metadata_blocked@@ -129,8 +132,10 @@ predicate has a `type`, a JSON Pointer into the arguments, an `op` and a| `json` | `exists`, `equals`, `one_of`, `contains` | Canonical key order |The CRD does not validate rule shape. mcp-host compiles the rules when a task-starts, and a malformed set (missing provenance, duplicate id, unknown op,-bad pointer) makes the task fail rather than run with part of the rules.+starts, and a malformed set (missing provenance, duplicate id, invalid action+or predicate type, bad pointer) makes the task fail rather than run with part+of the rules. An unknown `op` is not caught at start: it throws when a call+matching the rule's tool filter is evaluated, and the task fails then.**Built-ins** run in-process on the main model lane only, sorted by `order`(default 100). For each item, mcp-host reads only `type`, `order` and@@ -168,8 +173,8 @@ the pod.validated;- checks the agent: the hook's trust level must meet the agent's floor,and the capabilities you selected must fall within the agent's ceiling;- - requires a digest-pinned image, and checks the image allowlist when- enforcement is on;+ - for image hooks, requires a digest-pinned image and checks the image+ allowlist when enforcement is on;- creates the `LlmHook` in `llm-hooks`, stamped with a platform-assigned`clerum.io/trust-level` annotation;- adds a reference to the agent under **every** lifecycle point the hook@@ -206,7 +211,7 @@ the fields it does not edit when it saves.- **Capabilities are enforced on the response.** If a hook returns a denywithout `may_deny`, the deny is downgraded to no decision. A rewritewithout `may_rewrite` is dropped, and so is a substitute without- `may_substitute_result`. `may_add_context` is **not** enforced today.+ `may_substitute_result`. `may_add_context` has no effect today: mcp-host does not apply context that a hook returns, whether or not the capability is granted.Installed hooks can never change the system prompt.- **`failMode` only bites with the matching capability.** If a hook isunavailable (timeout, 5xx, a malformed or oversized reply, or an SSRF@@ -219,8 +224,9 @@ the fields it does not edit when it saves.the model output;- in every other case the hook contributes nothing.- The CRD defaults to `closed`, but the install route and form default to- `open` unless **May deny** is selected.+ The CRD defaults to `closed`. The install route defaults to `open` unless+ `may_deny` is requested; the form preselects the hook author's suggested+ fail mode (or `open`), and **May deny** forces `closed`.- **Timeouts.** The per-call deadline is the Host's`limits.maxHookTimeoutMs`, default 5000 ms, on both lanes. mcp-host does@@ -294,7 +300,8 @@ install-time trust-floor and ceiling checks (see Limits).3. For rules, trigger a matching tool call and look for the `Blocked byguardrail policy` result or a pending approval. The`clerum_mcp_host_guardrail_decisions_total` metric counts decisions by- lane, source, outcome and reason.+ `lane`, `decision`, `source`, `execution_mode`, `phase`, `outcome` and+ `reason_code`.## Limits@@ -313,27 +320,27 @@ guardrail policy` result or a pending approval. Theare implemented for LLM-lane hooks only. Tool-lane hooks are dialedwithout them.- **Doom-loop guard.** It is active whenever tool-lane rules or hooks exist:- three consecutive identical calls are denied (`repeated_identical_call`).+ the third consecutive identical call is denied (`repeated_identical_call`).It is a runaway guard, not a security control, because alternating callsevade it.- **Scope.** The aux/compaction model lane runs no guardrails.## Troubleshooting-| Symptom | Cause / fix |-| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `spec.guardrails` vanishes after apply | The CRD is older than the field and pruned it. Apply `charts/clerum-crds` first, then re-apply the Host. |-| Every tool call now asks for approval | Rules exist and nothing matched (`unmatched_ask`). Add catch-all `allow` rules per provenance. |-| Cron or workflow tasks fail with "approval required but no approver is available" | A guardrail `ask` in an unattended run. Add a rule that resolves the call to `allow` or `deny`. |-| Tasks fail right after you edit rules | The rule set is malformed and rejected as a whole. Check mcp-host logs for the rule id. |-| Refusal "a required safety check is unavailable" | A `may_deny` hook with `failMode: closed` is unreachable, timing out, or quarantined. Check the hook's pod and the Host `digest` against `status.observedDigest`. |-| mcp-host logs `digest mismatch ... quarantining` | The hook image changed without the Host pin. Use upgrade-hook, or update the `digest` to `status.observedDigest`. |-| Install: `capability_exceeds_ceiling`, or no capability can be ticked | The Host has no `capabilityCeiling`, or the ceiling is too narrow. Set it on the Host. |-| Install: `hook_below_trust_floor` | The hook's resolved trust is below `minInstalledHookTrustLevel`. |-| Install: `content_egress_requires_high_trust` | The hook sees content and has egress or a remote target, so it needs `high` trust, which non-curated orgs never reach. Add the org to `CONTROL_API_CURATED_HOOK_ORGS` or use a hook without egress. |-| Install: `content_access_conflict` | The entry declares `contentAccess: metadata` on a content-bearing point. The publisher must fix `hook_meta` and republish. |-| Install: `hook_requires_org_scope` / `image_ref_not_digest_pinned` | Only org-owned entries with `@sha256:` image refs can be installed. |-| Hook installed, but it never runs | Check that a Host references the hook's id, and that the CR is not `Ready=False/DuplicatePath`. A hook that returns a deny without `may_deny` is ignored. |+| Symptom | Cause / fix |+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `spec.guardrails` vanishes after apply | The CRD is older than the field and pruned it. Apply `charts/clerum-crds` first, then re-apply the Host. |+| Every tool call now asks for approval | Rules exist and nothing matched (`unmatched_ask`). Add catch-all `allow` rules per provenance. |+| Cron or workflow tasks fail with "approval required but no approver is available" | A guardrail `ask` in an unattended run. Add a rule that resolves the call to `allow` or `deny`. |+| Tasks fail right after you edit rules | The rule set is malformed and rejected as a whole. Check mcp-host logs for the rule id. |+| Refusal "a required safety check is unavailable" | A `may_deny` hook with `failMode: closed` is unreachable, timing out, or quarantined. Check the hook's pod and the Host `digest` against `status.observedDigest`. |+| mcp-host logs `digest mismatch ... quarantining` | The hook image changed without the Host pin. Use upgrade-hook, or update the `digest` to `status.observedDigest`. |+| Install: `capability_exceeds_ceiling`, or no capability can be ticked | The Host has no `capabilityCeiling`, or the ceiling is too narrow. Set it on the Host. |+| Install: `hook_below_trust_floor` | The hook's resolved trust is below `minInstalledHookTrustLevel`. |+| Install: `content_egress_requires_high_trust` | The hook sees content and has egress or a remote target, so it needs `high` trust, which non-curated orgs never reach under the default `mid` cap. Add the org to `CONTROL_API_CURATED_HOOK_ORGS` or use a hook without egress. |+| Install: `content_access_conflict` | The entry declares `contentAccess: metadata` on a content-bearing point. The publisher must fix `hook_meta` and republish. |+| Install: `hook_requires_org_scope` / `image_ref_not_digest_pinned` | Only org-owned entries can be installed, and an image-target hook must use an `@sha256:` image ref. |+| Hook installed, but it never runs | Check that a Host references the hook's id, and that the CR is not `Ready=False/DuplicatePath`. A hook that returns a deny without `may_deny` is ignored. |## Relateddiff --git a/docs/how-to/connect-llm-subscription.md b/docs/how-to/connect-llm-subscription.mdindex be9ce631a..81f58796a 100644--- a/docs/how-to/connect-llm-subscription.md+++ b/docs/how-to/connect-llm-subscription.md@@ -52,8 +52,9 @@ control-api first, then the Host and recipe switches.Notes:-- The flags accept only the exact string `true`. Any other value keeps the- feature off.+- The control-api, proxy and mcp-host flags accept only the exact string+ `true`; `WRC_GROK_SUBSCRIPTION_ENABLED` also accepts `1` and any case of+ `true`. Any other value keeps the feature off.- `deploy/base` does not ship an `mcp-host-config` ConfigMap. The Hostcontroller (HCC) loads it into every Host's `mcp-host` container with`envFrom`, so your overlay must provide it. The minikube overlay doesdiff --git a/docs/how-to/connect-oauth-connector.md b/docs/how-to/connect-oauth-connector.mdindex c9e3e7c72..824064113 100644--- a/docs/how-to/connect-oauth-connector.md+++ b/docs/how-to/connect-oauth-connector.md@@ -28,19 +28,19 @@ also rejects an OAuth server that pins a static `Authorization` header.## Prerequisites-| Setting (control-api) | Default | What happens if it is wrong |-| ------------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `MCP_OAUTH_BROKER_ENABLED` | **Off** in `deploy/base`, `true` in the minikube overlay | The token broker answers `404`, mcp-host reads that as "no grant", and the agent asks for consent forever, even after the user authorizes. Accepts only `true` or `false`. |-| `CONTROL_API_OAUTH_CALLBACK_BASE_URL` | Unset in base, `http://127.0.0.1:8090` in minikube | Must be the bare, browser-reachable origin that routes `/api/v1/oauth-callback/` to control-api. When unset, control-api builds the redirect URI from the request Host, which is usually an internal hostname. Built-in, generic, and CIMD installs are rejected while it is unset. |-| `CONTROL_API_OAUTH_STATE_HMAC_SECRET`, `CONTROL_API_OAUTH_ENCRYPTION_KEY` | Dev defaults; read from the control-api Secret in base | Generate real values (`deploy/scripts/gen-jwt-keys.sh` does this). The encryption key protects stored grants. |-| `OAUTH_PROACTIVE_REFRESH_CRON_ENABLED` | **Off**, including in minikube | Remote-server tokens are only refreshed when someone uses them. See [Refresh and background use](#refresh-and-background-use). |+| Setting (control-api) | Default | What happens if it is wrong |+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `MCP_OAUTH_BROKER_ENABLED` | **Off** in `deploy/base`, `true` in the minikube overlay | The token broker answers `404`, mcp-host reads that as "no grant", and the agent asks for consent forever, even after the user authorizes. Accepts only `true` or `false`. |+| `CONTROL_API_OAUTH_CALLBACK_BASE_URL` | Unset in base, `http://127.0.0.1:8090` in minikube | Must be the bare, browser-reachable origin that routes `/api/v1/oauth-callback/` to control-api. When unset, control-api builds the redirect URI from the request Host, which is usually an internal hostname. Marketplace built-in and generic installs, and remote installs that use CIMD, DCR, or a per-server callback (no RFC 9207), are rejected while it is unset. |+| `CONTROL_API_OAUTH_STATE_HMAC_SECRET`, `CONTROL_API_OAUTH_ENCRYPTION_KEY` | Built-in dev values only when `NODE_ENV` is not `production` (production refuses to start without them); read from the control-api Secret in base | Generate real values (`deploy/scripts/gen-jwt-keys.sh` does this). The encryption key protects stored grants. |+| `OAUTH_PROACTIVE_REFRESH_CRON_ENABLED` | **Off**, including in minikube | Remote-server tokens are only refreshed when someone uses them. See [Refresh and background use](#refresh-and-background-use). |The Control UI **Marketplace** OAuth install form (built-in and genericproviders) shows the redirect URI using`NEXT_PUBLIC_CONTROL_API_OAUTH_CALLBACK_BASE_URL`. Next.js compiles this valueinto the Control UI bundle at build time. The shipped Dockerfile and theminikube image build do not set it. Without it, the form shows "not configured"-and keeps **Install** disabled. The remote-server wizard is not affected,+and keeps **Install connector** disabled. The remote-server wizard is not affected,because control-api computes its redirect URI. If your build does not set thevariable, install built-in and generic connectors with YAML (below).@@ -246,7 +246,7 @@ out too, but the screen only tracks the current one.| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- || Agent keeps asking to **Connect** after the user authorized | `MCP_OAUTH_BROKER_ENABLED` is not `true` | Set it on control-api and restart || Provider says `redirect_uri` mismatch | Callback base is unset or wrong, or the registered URI differs from the one shown | Set `CONTROL_API_OAUTH_CALLBACK_BASE_URL` to the public origin. Register the exact URI the wizard shows. |-| Remote install returns `callback_base_url_unconfigured` | CIMD, or a server without RFC 9207, needs the public callback origin | Set `CONTROL_API_OAUTH_CALLBACK_BASE_URL` |+| Remote install returns `callback_base_url_unconfigured` | CIMD, DCR, or a server without RFC 9207 needs the public callback origin | Set `CONTROL_API_OAUTH_CALLBACK_BASE_URL` || **Detect** stops with an unreachable transport (`transport_unreachable` on install) | The URL is not the MCP endpoint | Use the URL the wizard suggests, or the server's documented MCP path || Marketplace OAuth form says the callback URL is not configured | `NEXT_PUBLIC_CONTROL_API_OAUTH_CALLBACK_BASE_URL` was not set when Control UI was built | Rebuild Control UI with it, or install with YAML || `503 integration_not_configured` | The client ID or secret Secret, or one of its keys, is missing | Create the Secret the hint names |diff --git a/docs/how-to/use-the-desktop-app.md b/docs/how-to/use-the-desktop-app.mdindex beffe3184..e99a11afa 100644--- a/docs/how-to/use-the-desktop-app.md+++ b/docs/how-to/use-the-desktop-app.md@@ -108,13 +108,13 @@ The **+** button (**Add context**) in the composer opens a menu with:The composer checks each message before sending it and explains anythingthat won't fit:-| Limit | Value |-| --------------------------------------------------- | ------------------------------------------- |-| Attachments per message (images and files together) | 20 |-| Size of each file | 11 MiB |-| Size of all files in one message, once encoded | 16 MiB |-| Image formats | JPEG and PNG |-| Size of each image (most models) | 3 MB, with up to 8 MB of images per message |+| Limit | Value |+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------- |+| Attachments per message (images and files together) | 20 |+| Size of each file | 11 MiB |+| Size of all files in one message, once encoded | 16 MiB |+| Image formats | JPEG and PNG |+| Size of each image (most models) | 3 MB, with up to 8 MB of images per message (measured after encoding, about 6 MB of image data) |Some models accept larger images. For Codex and Grok subscription models, thelimit is 16 MiB per image and 16 MiB in total, and Codex images can be at@@ -196,8 +196,8 @@ agent's own Connectors tab. For the full sign-in flow, see## Apps and Plugins-**Apps** lists the apps that your plugins provide, with the heading-**Discover and launch tools to help you work smarter**. Click an app to open+**Apps** lists the apps that your plugins provide (_Discover and launch tools to+help you work smarter_). Click an app to openit in a tab inside the app window. While an app is open, the title bar has**Refresh app content** and **Copy current app link**. The first time aplugin asks to read your information, you'll see