Skip to content

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.md
index 149f757e6..7eb392f9b 100644
--- a/docs/how-to/configure-guardrails.md
+++ b/docs/how-to/configure-guardrails.md
@@ -87,6 +87,9 @@ spec:
action: allow
match: { 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-endpoint
action: deny
reasonCode: 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 deny
without `may_deny`, the deny is downgraded to no decision. A rewrite
without `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 is
unavailable (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 by
guardrail 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. The
are implemented for LLM-lane hooks only. Tool-lane hooks are dialed
without 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 calls
evade 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. |
## Related
diff --git a/docs/how-to/connect-llm-subscription.md b/docs/how-to/connect-llm-subscription.md
index 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 Host
controller (HCC) loads it into every Host's `mcp-host` container with
`envFrom`, so your overlay must provide it. The minikube overlay does
diff --git a/docs/how-to/connect-oauth-connector.md b/docs/how-to/connect-oauth-connector.md
index 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 generic
providers) shows the redirect URI using
`NEXT_PUBLIC_CONTROL_API_OAUTH_CALLBACK_BASE_URL`. Next.js compiles this value
into the Control UI bundle at build time. The shipped Dockerfile and the
minikube 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 the
variable, 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.md
index 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 anything
that 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, the
limit 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 open
it 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 a
plugin asks to read your information, you'll see