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 correctness sweep

Jose Gabriel Ramirez Encinas5dd8b0b1dc81
diff --git a/.env.example b/.env.example
index 6d9a413a9..f7a429aa1 100644
--- a/.env.example
+++ b/.env.example
@@ -32,8 +32,9 @@ ZAI_API_KEY=
BAILIAN_API_KEY=
# Setup auto-selects the agent's provider from the first of the four keys above.
-# Every other supported provider is read too (and written to the LLM Secret),
-# but needs CLERUM_MODEL_PROVIDER + CLERUM_MODEL_NAME below to be selected:
+# Other supported providers need CLERUM_MODEL_PROVIDER + CLERUM_MODEL_NAME below,
+# and their key reaches the cluster only when you run `make minikube-apply-secrets`
+# after `make minikube-setup` (setup itself writes only the four keys above):
# OPENROUTER_API_KEY GEMINI_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY
# TOGETHER_API_KEY FIREWORKS_API_KEY MISTRAL_API_KEY XAI_API_KEY
# CEREBRAS_API_KEY DEEPINFRA_API_KEY PERPLEXITY_API_KEY MOONSHOT_API_KEY
diff --git a/control-ui/README.md b/control-ui/README.md
index 00be5964e..f39addd7d 100644
--- a/control-ui/README.md
+++ b/control-ui/README.md
@@ -38,7 +38,7 @@ Sidebar destinations map to the public routes in `app/constants/routes.ts` (`com
| Cost & Usage | `/cost-and-usage/usage`, `/cost-and-usage/llm-prices`, `/cost-and-usage/token-budgets` | Token usage dashboard, model prices, token budgets |
| Settings | `/settings/ui` | Control settings panel |
-Routes not in the sidebar: `/users-and-teams/admins/new` (invite a control admin; `/control-admins/new` redirects there), `/plugin-workload-sdk` (SDK grants and invocation search), `/traces/*` (hidden Traces section), and the public token flows listed above. Legacy paths such as `/cost/*`, `/registry`, `/publisher/*`, `/mcp-servers`, `/hosts` and `/contexts` redirect to their current locations (`next.config.js`, `components/LegacyContextRedirect`).
+Routes not in the sidebar: `/users-and-teams/admins/new` (invite a control admin; `/control-admins/new` redirects there), `/plugins/sdk` (SDK grants and invocation search), `/traces/*` (hidden Traces section), and the public token flows listed above. Legacy paths such as `/cost/*`, `/registry`, `/publisher/*`, `/mcp-servers`, `/hosts` and `/contexts` redirect to their current locations (`next.config.js`, `components/LegacyContextRedirect`).
## Notable Features
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index 89df19642..191082cb1 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.729",
+ "version": "0.1.730",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.729",
+ "version": "0.1.730",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/frontend-components": "file:../packages/frontend-components",
diff --git a/control-ui/package.json b/control-ui/package.json
index a23f3ab42..86b2a5f69 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.729",
+ "version": "0.1.730",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",
diff --git a/docs/crds/host.md b/docs/crds/host.md
index 23877a459..2475cbc9b 100644
--- a/docs/crds/host.md
+++ b/docs/crds/host.md
@@ -49,7 +49,6 @@ represents a single LLM agent instance (an "agent" in Control UI and the Desktop
| `spec.personalization.soul` | string | no | Content of `SOUL.md` (system-prompt section "## Core Values"). |
| `spec.personalization.agents` | string | no | Content of `AGENTS.md` (system-prompt section "## Agent Instructions"). |
| `spec.personalization.user` | string | no | Content of `USER.md` (system-prompt section "## User Context"). |
-
| `spec.guardrails` | object | no | Opt-in guardrail policy. A Host without it runs no rules or hooks. See [Guardrails](#guardrails). |
### Guardrails
diff --git a/docs/crds/llmhook.md b/docs/crds/llmhook.md
index 1450066f5..3ea4d4d5a 100644
--- a/docs/crds/llmhook.md
+++ b/docs/crds/llmhook.md
@@ -29,37 +29,38 @@ install stamps a platform-assigned `clerum.io/trust-level` annotation (`low`,
## Spec Fields
-| Field | Type | Required | Description |
-| -------------------------------------------- | ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `spec.target` | object | yes | Exactly one of `image`, `service`, `remote`. |
-| `spec.target.image.ref` | string | yes (image) | Container image. Validated against the image allowlist and digest-pinned at install. |
-| `spec.target.image.port` | int | yes (image) | Port the hook HTTP server listens on (1–65535). |
-| `spec.target.image.imagePullSecrets` | string[] | no | Pull secret names in `llm-hooks`. |
-| `spec.target.image.envSecret` | string | no | The hook's own credential Secret in `llm-hooks`. It can never reference a Host or LLM-key Secret. |
-| `spec.target.image.egressBindings[]` | object[] | no | Allowed external egress: `toFQDN` or `cidr`, plus `ports`. Looser than McpServer egress: no private-range hardening yet. |
-| `spec.target.image.security.addCapabilities` | string[] | no | Subset of `CHOWN`, `FOWNER`, `DAC_OVERRIDE`, `NET_BIND_SERVICE`. |
-| `spec.target.service` | object | yes (service) | Existing in-cluster Service: `name`, `namespace`, `port`. |
-| `spec.target.remote.baseUrl` | string | yes (remote) | External endpoint mcp-host dials directly. Must be `https://`; SSRF-validated at dial time. |
-| `spec.target.remote.authHeadersSecret` | string | no | Secret supplying auth headers for the remote endpoint. |
-| `spec.path` | string | no (default `/`) | Calls go to `{endpoint}{path}/v1/{point}`. Co-located image hooks must use distinct paths. |
-| `spec.lifecyclePoints` | string[] | yes (1–6) | LLM lane: `preCall`, `moderate`, `postCallSuccess`, `onError`. Tool lane: `preToolUse`, `postToolUse`. |
-| `spec.contentAccess` | `metadata` \| `content` | no | What the hook receives. **Omitting it means `content`.** Only a `preCall`-only hook may declare `metadata` (model, params and usage, no message bodies). |
-| `spec.order` | int | no (default 100) | Order within a phase; lower runs first. |
-| `spec.failMode` | `open` \| `closed` | no (default `closed`) | Behaviour when the hook is unavailable. A hook with `may_deny` must fail closed. |
-| `spec.timeoutMs` | int | no (default 5000) | Per-call timeout. |
-| `spec.onUnavailable` | object | no | Circuit breaker: `mode` (`strict` \| `breaker`, default `strict`), `failureThreshold` (default 5), `cooldownMs` (default 30000). |
-| `spec.capabilities` | string[] | no | Admin-granted: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. Must fall within the Host's `guardrails.capabilityCeiling`, and is re-checked on every hook response. |
-| `spec.config` | object | no | Opaque hook settings. Never used as a trust input. |
-
-### Admission rules
+| Field | Type | Required | Description |
+| -------------------------------------------- | ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `spec.target` | object | yes | Exactly one of `image`, `service`, `remote`. |
+| `spec.target.image.ref` | string | yes (image) | Container image. Validated against the image allowlist and digest-pinned at install. |
+| `spec.target.image.port` | int | yes (image) | Port the hook HTTP server listens on (1–65535). |
+| `spec.target.image.imagePullSecrets` | string[] | no | Pull secret names in `llm-hooks`. |
+| `spec.target.image.envSecret` | string | no | The hook's own credential Secret in `llm-hooks`. It can never reference a Host or LLM-key Secret. |
+| `spec.target.image.egressBindings[]` | object[] | no | Allowed external egress: `toFQDN` or `cidr`, plus `ports`. host-context-controller rejects private, metadata, link-local and reserved destinations at reconcile (condition `InvalidEgress`) and fails the hook pod closed; unlike McpServer, this is not checked at admission. |
+| `spec.target.image.security.addCapabilities` | string[] | no | Subset of `CHOWN`, `FOWNER`, `DAC_OVERRIDE`, `NET_BIND_SERVICE`. |
+| `spec.target.service` | object | yes (service) | Existing in-cluster Service: `name`, `namespace`, `port`. |
+| `spec.target.remote.baseUrl` | string | yes (remote) | External endpoint mcp-host dials directly. Must be `https://`; SSRF-validated at dial time. |
+| `spec.target.remote.authHeadersSecret` | string | no | Secret supplying auth headers for the remote endpoint. |
+| `spec.path` | string | no (default `/`) | Calls go to `{endpoint}{path}/v1/{point}`. Co-located image hooks must use distinct paths. |
+| `spec.lifecyclePoints` | string[] | yes (1–6) | LLM lane: `preCall`, `moderate`, `postCallSuccess`, `onError`. Tool lane: `preToolUse`, `postToolUse`. |
+| `spec.contentAccess` | `metadata` \| `content` | no | What the hook receives. **Omitting it means `content`.** Only a `preCall`-only hook may declare `metadata` (model, params and usage, no message bodies). |
+| `spec.order` | int | no (default 100) | Order within a phase; lower runs first. |
+| `spec.failMode` | `open` \| `closed` | no (default `closed`) | Behaviour when the hook is unavailable. A hook with `may_deny` must fail closed. |
+| `spec.timeoutMs` | int | no (default 5000) | Per-call timeout. |
+| `spec.onUnavailable` | object | no | Circuit breaker: `mode` (`strict` \| `breaker`, default `strict`), `failureThreshold` (default 5), `cooldownMs` (default 30000). |
+| `spec.capabilities` | string[] | no | Admin-granted: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. Must fall within the Host's `guardrails.capabilityCeiling`, and is re-checked on every hook response. |
+| `spec.config` | object | no | Opaque hook settings. Never used as a trust input. |
+
+### Admission and install rules
- `remote.baseUrl` must start with `https://`.
- A hook granted `may_deny` must use `failMode: closed`.
- `contentAccess: metadata` is rejected for `moderate`, `postCallSuccess`,
`onError`, `preToolUse` and `postToolUse`, which are inherently
content-bearing.
-- A content-bearing hook that has `egressBindings` or a `remote` target can
- only be installed at trust level `high`.
+- At install time (not CRD admission), a content-bearing hook that has
+ `egressBindings` or a `remote` target is accepted only at trust level
+ `high`.
## Status Fields
diff --git a/docs/crds/mcpserver.md b/docs/crds/mcpserver.md
index 73b38b4f2..e80de7292 100644
--- a/docs/crds/mcpserver.md
+++ b/docs/crds/mcpserver.md
@@ -55,7 +55,8 @@ time and are **never mounted into the connector pod**.
> in `deploy/base` (the minikube overlay turns it on). While it is off,
> OAuth connectors keep asking for consent and never get a token. Also set
> `CONTROL_API_OAUTH_CALLBACK_BASE_URL` to the browser-reachable control-api
-> origin; otherwise callbacks fall back to an internal hostname.
+> origin; otherwise registry OAuth installs are refused, and other callbacks
+> fall back to the request host (an internal hostname behind the proxy chain).
There are three configuration styles, chosen by `source`, which can't change
after creation:
diff --git a/docs/get-started/minikube.md b/docs/get-started/minikube.md
index dcd6bd181..9b1be1bb3 100644
--- a/docs/get-started/minikube.md
+++ b/docs/get-started/minikube.md
@@ -7,7 +7,8 @@ service, deny-all NetworkPolicies, the JWT chain, and a seeded agent named
from the registry when you want more. Setup infers the provider from the first of
`OPENAI_API_KEY`, `CLAUDE_API_KEY`, `ZAI_API_KEY`, `BAILIAN_API_KEY` set in
`.env`; for any other provider also set `CLERUM_MODEL_PROVIDER` and
-`CLERUM_MODEL_NAME`.
+`CLERUM_MODEL_NAME`, then run `make minikube-apply-secrets` after setup (setup
+itself writes only those four keys).
## Prerequisites
diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md
index 4cd0e11cf..89ed4da70 100644
--- a/docs/get-started/quickstart.md
+++ b/docs/get-started/quickstart.md
@@ -24,8 +24,11 @@ named `chatllm` you can message immediately.
Mistral, … see [the full list](../llm-providers/README.md)) put its key in
`.env` **and** set `CLERUM_MODEL_PROVIDER` and `CLERUM_MODEL_NAME`. The pair
must be enabled in the model allowlist, or setup stops with
- `HOST_MODEL_UNKNOWN`. Without any key, setup still boots, but the agent
- can't reply until you add one.
+ `HOST_MODEL_UNKNOWN`. Setup only writes the four keys above to the cluster,
+ so after `make minikube-setup` run `make minikube-apply-secrets` and then
+ `kubectl rollout restart deployment/chatllm -n mcp-host --context clerum-test`.
+ Without any key, setup still boots, but the agent can't reply until you add
+ one.
## 1. Configure