Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs: add guides for guardrails, OAuth connectors, LLM subscriptions, and the Desktop App
Jose Gabriel Ramirez Encinasff49e6aef8a7
diff --git a/docs/README.md b/docs/README.mdindex 046330182..ccf1fbcb2 100644--- a/docs/README.md+++ b/docs/README.md@@ -46,27 +46,31 @@ minikube overlays ship; features that are off by default say so.## How-to guides-| Doc | Description |-| ----------------------------------------------------------------------------- | -------------------------------------------------------------- |-| [Connect Telegram](how-to/connect-telegram.md) | Minikube env or CRD channel path |-| [Connect Slack](how-to/connect-slack.md) | Slack app scopes, request URL, conversation verification |-| [Connect Microsoft Teams](how-to/connect-teams.md) | Teams CLI bot registration, endpoint, conversation verify |-| [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 |-| [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 |-| [Publish a plugin](how-to/publish-plugin-to-registry.md) | Publish under your org with an `efrk_` key |-| [Shared & global files](how-to/shared-and-global-files.md) | Team workspaces (SFS) and the brokered drive (EvenDrive / GFS) |+| Doc | Description |+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- |+| [Connect Telegram](how-to/connect-telegram.md) | Minikube env or CRD channel path |+| [Connect Slack](how-to/connect-slack.md) | Slack app scopes, request URL, conversation verification |+| [Connect Microsoft Teams](how-to/connect-teams.md) | Teams CLI bot registration, endpoint, conversation verify |+| [Use the Desktop App](how-to/use-the-desktop-app.md) | Daily use: chat, attachments, approvals, EvenDrive, shortcuts, deep links |+| [Configure guardrails](how-to/configure-guardrails.md) | Tool-call rules, installed guardrail hooks, built-ins |+| [Connect an OAuth connector](how-to/connect-oauth-connector.md) | Remote and OAuth MCP servers, user authorization, connector credentials |+| [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 |+| [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 |+| [Publish a plugin](how-to/publish-plugin-to-registry.md) | Publish under your org with an `efrk_` key |+| [Shared & global files](how-to/shared-and-global-files.md) | Team workspaces (SFS) and the brokered drive (EvenDrive / GFS) |## LLM providers-| Doc | Description |-| --------------------------------------------------------- | ---------------------------------------------------------------------- |-| [LLM providers overview](llm-providers/README.md) | The 24 providers, mental model, support matrix, request flow, fallback |-| [Configure LLM providers](deploy/llm-providers.md) | Operator guide: credentials, Vertex/Bedrock/Azure, allowlist, selector |-| [Add an LLM provider](llm-providers/adding-a-provider.md) | Data-only vs driver-based integration paths |+| Doc | Description |+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------- |+| [LLM providers overview](llm-providers/README.md) | The 24 providers, mental model, support matrix, request flow, fallback |+| [Configure LLM providers](deploy/llm-providers.md) | Operator guide: credentials, Vertex/Bedrock/Azure, allowlist, selector |+| [Use a ChatGPT or Grok subscription](how-to/connect-llm-subscription.md) | Sign in with a subscription instead of an API key (off by default) |+| [Add an LLM provider](llm-providers/adding-a-provider.md) | Data-only vs driver-based integration paths |## Deploy & operatediff --git a/docs/crds/host.md b/docs/crds/host.mdindex 23877a459..7043e7822 100644--- a/docs/crds/host.md+++ b/docs/crds/host.md@@ -56,13 +56,13 @@ represents a single LLM agent instance (an "agent" in Control UI and the Desktop| Field | Description ||-------|-------------|-| `guardrails.rules[]` | Ordered tool-lane rules evaluated top-down: `{id, action: allow\|ask\|deny, reasonCode, match: {tool, arguments[]}}`. |-| `guardrails.hooks.<phase>[]` | Installed [LlmHook](llmhook.md) references `{id, digest}` per phase: `preToolUse`, `postToolUse`, `preCall`, `moderate`, `postCallSuccess`, `onError`. |+| `guardrails.rules[]` | Tool-lane rules `{id, action: allow\|ask\|deny, reasonCode, match: {tool, arguments[]}}`. Every matching rule contributes and the strictest decision wins; array order is not precedence. Once any rule exists, a call that matches none resolves to `ask`. |+| `guardrails.hooks.<phase>[]` | Installed [LlmHook](llmhook.md) references `{id, digest}` per phase: `preToolUse`, `postToolUse`, `preCall`, `moderate`, `postCallSuccess`, `onError`. A referenced hook runs at every point in its own `lifecyclePoints`. || `guardrails.builtins[]` | First-party hooks compiled into mcp-host (e.g. `prompt-shaping`, `token-trim`). |-| `guardrails.minInstalledHookTrustLevel` | `low` \| `mid` \| `high`: minimum platform-assigned trust level an installed hook needs to run on this Host. |-| `guardrails.capabilityCeiling[]` | Upper bound on hook capabilities: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. |-| `guardrails.approvalPolicies[]` | Approval policies available to `ask` decisions: `cli_only`, `channel_users`, `designated_approvers`. |-| `guardrails.limits` | `maxRules` (100), `maxHooksPerPhase` (8), `maxHookTimeoutMs` (5000), `maxHookOutputBytes` (65536). |+| `guardrails.minInstalledHookTrustLevel` | `low` \| `mid` \| `high`: minimum trust level for hooks installed onto this Host. Checked by control-api when a hook is installed or upgraded, not at runtime. |+| `guardrails.capabilityCeiling[]` | Upper bound on the capabilities an install may grant: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. Checked at install/upgrade, not at runtime, so a hand-edited LlmHook is not re-validated against it. |+| `guardrails.approvalPolicies[]` | Accepted by the schema (`cli_only`, `channel_users`, `designated_approvers`) but not read by mcp-host today; `ask` decisions use `spec.approval`. |+| `guardrails.limits` | `maxRules` (100) and `maxHookTimeoutMs` (5000, the deadline for every hook call) are enforced. `maxHookOutputBytes` (65536 when a `limits` object is present; otherwise mcp-host allows 1 MiB, and 5 MiB for `preCall` rewrites) applies to LLM-lane hooks. `maxHooksPerPhase` is accepted but not enforced. |Apply the CRD before any component writes `spec.guardrails`: the API serversilently prunes fields an older CRD does not know.diff --git a/docs/crds/llmhook.md b/docs/crds/llmhook.mdindex 1450066f5..0ea3e60a6 100644--- a/docs/crds/llmhook.md+++ b/docs/crds/llmhook.md@@ -25,31 +25,34 @@ A Host opts in by listing hooks under `Host.spec.guardrails.hooks.<phase>[]`Control UI installs hooks from the registry (**Installed Guardrails**). Theinstall stamps a platform-assigned `clerum.io/trust-level` annotation (`low`,`mid` or `high`) that hook authors cannot set. The Host's-`guardrails.minInstalledHookTrustLevel` is checked against that annotation.+`guardrails.minInstalledHookTrustLevel` is checked against that annotation+(and granted capabilities against `guardrails.capabilityCeiling`) by+control-api when a hook is installed or upgraded; mcp-host does not re-check+either at runtime.## 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. |+| 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 (CRD default `closed`) | Behaviour when the hook is unavailable. A hook with `may_deny` must fail closed. The Control UI install form defaults to `open` unless `may_deny` is granted. |+| `spec.timeoutMs` | int | no (default 5000) | Accepted but not used today; the deadline is the Host's `guardrails.limits.maxHookTimeoutMs` (default 5000). |+| `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`. Checked against the Host's `guardrails.capabilityCeiling` at install time; mcp-host ignores response actions the hook was not granted. |+| `spec.config` | object | no | Opaque hook settings. Never used as a trust input. |### Admission rules@@ -63,12 +66,12 @@ install stamps a platform-assigned `clerum.io/trust-level` annotation (`low`,## Status Fields-| Field | Description |-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `status.observedDigest` | Image digest actually running. mcp-host binds `Host.spec.guardrails.hooks[].digest` against this, and fails closed (or skips with an alert) on mismatch. |-| `status.readyReplicas` | Ready replicas (image targets only). |-| `status.lastReconciled` | Timestamp of the last successful reconcile. |-| `status.conditions[]` | Standard conditions (`Deployed`, `Ready`) with `observedGeneration`. |+| Field | Description |+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `status.observedDigest` | Image digest actually running. mcp-host compares it with `Host.spec.guardrails.hooks[].digest`. On a mismatch the hook is quarantined: calls are treated as unavailable, so a `may_deny` hook denies and an advisory hook contributes nothing (LLM-lane points). |+| `status.readyReplicas` | Ready replicas (image targets only). |+| `status.lastReconciled` | Timestamp of the last successful reconcile. |+| `status.conditions[]` | Standard conditions (`Deployed`, `Ready`) with `observedGeneration`. |`kubectl get llmhooks -n llm-hooks` shows Path, Order, FailMode, Digest, and Ready.@@ -109,5 +112,6 @@ A zero-dependency reference implementation of the `/v1` protocol lives in## Related+- [Configure guardrails](../how-to/configure-guardrails.md): the how-to guide- [Host CRD](host.md): `spec.guardrails`- [CRD Index](README.md)diff --git a/docs/crds/mcpserver.md b/docs/crds/mcpserver.mdindex 73b38b4f2..349b754df 100644--- a/docs/crds/mcpserver.md+++ b/docs/crds/mcpserver.md@@ -71,7 +71,7 @@ after creation:|-------|-----------|-------------|| `oauth.id` | all | Stable client identifier; also the callback path segment. Immutable. || `oauth.provider` | built-in | `salesforce`, `slack`, `notion`, `microsoft-graph`, `google`, `monday`, `clickup`, `vercel`. Immutable. |-| `oauth.clientIdRef` / `oauth.clientSecretRef` | all | `{name, key}` of Secrets in the `mcp-servers` namespace holding the client id / secret. |+| `oauth.clientIdRef` / `oauth.clientSecretRef` | all | `{name, key}` of Secrets in the `mcp-server` namespace holding the client id / secret. || `oauth.scopes[]` | all | Scopes to request. Include the provider's offline/refresh scope when `backgroundAccess` is true. || `oauth.backgroundAccess` | all | Allow use by a workload with no live human session. || `oauth.grantScope` | all | `user` (default): every user authorizes their own grant. `context`: one shared identity per Context, which one member bootstraps and others inherit. Immutable. |@@ -91,7 +91,9 @@ after creation:With dynamic registration, the install id is appended and registeredautomatically.-The Control UI wizard shows the exact URI.+The remote-connector wizard in Control UI shows the exact URI. See+[Connect an OAuth connector](../how-to/connect-oauth-connector.md) for the+full walkthrough.### Server Configurationdiff --git a/docs/how-to/add-mcp-server.md b/docs/how-to/add-mcp-server.mdindex 501884093..c331a868b 100644--- a/docs/how-to/add-mcp-server.md+++ b/docs/how-to/add-mcp-server.md@@ -116,5 +116,6 @@ See [stdio-bridge README](../../stdio-bridge/README.md) and## Related+- [Connect an OAuth connector](connect-oauth-connector.md): remote MCP servers, OAuth sign-in, and updating connector credentials- [CRD index](../crds/README.md)- [Architecture overview](../architecture/overview.md)diff --git a/docs/how-to/configure-approvals.md b/docs/how-to/configure-approvals.mdindex b73c0482d..f0bf37619 100644--- a/docs/how-to/configure-approvals.md+++ b/docs/how-to/configure-approvals.md@@ -118,6 +118,7 @@ Cluster E2E coverage: [E2E guide](../testing/e2e-guide.md).## Related+- [Configure guardrails](configure-guardrails.md): rules whose `ask` decision uses this approval flow- Root [Security model](../../README.md#security-model)- [Host CRD](../crds/host.md)- [Connect Telegram](connect-telegram.md)diff --git a/docs/how-to/configure-guardrails.md b/docs/how-to/configure-guardrails.mdnew file mode 100644index 000000000..149f757e6--- /dev/null+++ b/docs/how-to/configure-guardrails.md@@ -0,0 +1,344 @@+# How to: add guardrails to an agent++Guardrails are an **opt-in** policy block on a Host (`spec.guardrails`). A+Host without one behaves exactly as before. No guardrails block and no+`LlmHook` ship in `deploy/base` or the minikube overlays. The base only+creates the `llm-hooks` namespace, its RBAC, and a default-deny+NetworkPolicy, so there is no flag to flip: you turn guardrails on by+writing the block.++Guardrails are a policy layer inside mcp-host. They are **not a sandbox**.+Argument predicates are lexical, so path and URL checks are not TOCTOU-safe.+A guardrail `allow` never bypasses the approval gate, the input validators,+or workload isolation.++## Mental model++There are two lanes, and both use the same `allow` / `ask` / `deny`+decisions:++| Lane | What runs | Where it acts |+| ------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |+| **Tool lane** | `rules[]`, installed hooks at `preToolUse` / `postToolUse`, a doom-loop check | Before a tool call (decide), after it (redact the result) |+| **LLM lane** | Built-ins (`prompt-shaping`, `token-trim`), then installed hooks at `preCall`, `moderate`, `postCallSuccess`, `onError` | Around the main model call |++How a tool call is decided:++1. Every rule that matches the call contributes its action, and so does+ every `preToolUse` hook that returns a decision.+2. **The strictest contribution wins:** `deny` > `ask` > `allow`. The order+ of the rules does **not** matter. A broad `allow` cannot override a+ narrower `deny`.+3. If the Host has at least one rule and **nothing matched**, the result is+ `ask` (reason `unmatched_ask`). If the Host has no rules, the result is+ `no_decision` and the call follows the normal path.+4. The result is applied:+ - `deny` returns `Blocked by guardrail policy (<reason>)` to the model.+ - `ask` suspends the call for approval.+ - `allow` and `no_decision` go on to the normal [approval gate](configure-approvals.md).++Because of step 3, adding a single `deny` rule turns **every other** tool+call into an `ask`. Pair specific rules with a catch-all `allow` per+provenance (see the example below).++### How `ask` interacts with approvals++- In an **interactive** run, a guardrail `ask` creates a pending approval+ scoped to that exact invocation. Its description reads+ `Guardrail requires approval (<reason>)`. You approve it on the usual+ surfaces. Once it is approved, the call runs without a second prompt from+ `spec.approval`.+- Tasks started by a person's message (Desktop App chat or a messaging+ channel; task source `channel`) are interactive. `cron` and `internal`+ tasks are **unattended**. In an unattended run an `ask` becomes+ a deny ("approval required but no approver is available"), so the task+ does not hang.+- `allow` does not skip approvals. MCP tools and the five risky native tools+ still require approval under `spec.approval`.++## Option A — mcp-host dev mode++Set `CLERUM_GUARDRAILS_CONFIG` to the JSON form of the `spec.guardrails`+block. mcp-host uses it only when no Host CR supplies one. For dev and E2E,+you can also list hooks inline as `hookDescriptors` to point at a local hook+server without the reconciler.++## Option B — Host CRD++Apply the current `charts/clerum-crds` first. The API server **silently+prunes** fields that an older CRD does not know, so a `guardrails` block+written against a stale CRD simply disappears.++```yaml+apiVersion: clerum.io/v1alpha1+kind: Host+metadata:+ name: chatllm+ namespace: mcp-host+spec:+ # ...existing fields...+ guardrails:+ rules:+ # Catch-alls so unmatched calls don't fall to `ask`.+ - id: allow-native+ action: allow+ match: { tool: { provenance: native } }+ - id: allow-mcp+ action: allow+ match: { tool: { provenance: mcp } }+ # Strictest wins: this deny beats allow-native.+ - id: no-metadata-endpoint+ action: deny+ reasonCode: metadata_blocked+ match:+ tool: { provenance: native, name: http_request }+ arguments:+ - { type: url, pointer: /url, op: host_in, value: ['169.254.169.254'] }+ - id: ask-github-writes+ action: ask+ match: { tool: { provenance: mcp, server: github, name: '*create*' } }+ builtins:+ - type: token-trim+ order: 10+ config: { maxInputTokens: 60000 }+ capabilityCeiling: [may_deny, may_substitute_result]+ hooks:+ postCallSuccess:+ - id: pii-redactor+ digest: sha256:<digest>+```++**Rule fields.** Each rule needs:++- `id`: unique within the Host.+- `action`: `allow`, `ask` or `deny`.+- `match.tool.provenance`: `native` or `mcp`. Provenance comes from the tool+ registry, never from the tool's name.++`server` and `name` are optional. They support only `*` and `?` wildcards,+anchored to the whole value. If you omit them, the rule matches every tool of+that provenance. A rule's `arguments[]` predicates must **all** match. Each+predicate has a `type`, a JSON Pointer into the arguments, an `op` and a+`value`:++| `type` | `op` values | Notes |+| --------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------- |+| `path` | `equals`, `under`, `outside` | Lexical normalisation; no symlink resolution |+| `url` | `scheme_in`, `host_in`, `port_in`, `path_under` | URLs with credentials never match |+| `command` | `executable_is`, `argv_prefix` | Argument must be `[exe, ...args]` or `{executable, args}`; a shell **string never matches** |+| `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.++**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+`config`.++- `prompt-shaping` forces `temperature`, `maxTokens` and `toolChoice`.+- `token-trim` reuses the pre-prune passes. It accepts `maxInputTokens`,+ `protectedTailTurns`, `summaryThresholdTokens`, `maxArgsBytes` and per-pass+ toggles. When `maxInputTokens` is set and the request is already under it,+ the request is left unchanged.++**Hooks** reference installed [LlmHook](../crds/llmhook.md) CRs as `{id,+digest}`. The full field list is in [Host CRD → Guardrails](../crds/host.md#guardrails).++mcp-host picks up Host and LlmHook changes live; you do not need to restart+the pod.++## Option C — the Control UI++### Install a hook from the Marketplace++1. In the sidebar, open **Installed Guardrails** (`/guardrails`). The page+ lists every `LlmHook` with its lifecycle, order, fail mode and status.+2. Click **Install Guardrail**. This opens the org Marketplace entries,+ filtered to guardrail hooks (`/marketplace/org/entries?type=llm-hook`).+ Pick an entry and choose **Install**.+3. In the install form (**Configure** → **Install**):+ - **Agent**: the Host to bind to. It defaults to the first agent in the+ list, so check it.+ - **Credentials**: shown only if the hook declares a credential schema.+ - **Advanced details**: the capabilities to grant, **Order** (default+ 100), and **Fail mode**. Ticking **May deny** forces fail closed.+4. **Install** calls `POST /admin/registry/install-hook`. That call:+ - checks the entry: it must be org-scoped, and its admission rules are+ 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;+ - 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+ declares. For image hooks, the reference includes the image digest.++ If the agent update fails, the install rolls back.++**Before you install, set `capabilityCeiling` on the Host.** A missing+ceiling counts as the empty set, so no capability can be granted. The UI has+no editor for the ceiling.++**Trust levels** (`low` < `mid` < `high`) come from the registry. They are+taken at face value only for curated orgs: your cluster's own org,+`@clerum`/`@evenfire`, and any org listed in `CONTROL_API_CURATED_HOOK_ORGS`.+Every other org is capped at `CONTROL_API_DEFAULT_HOOK_TRUST_CAP` (default+`mid`).++### See and remove hooks on an agent++Open **Agents** → the agent → **Advanced** → **Hooks**. The table lists each+`{hook, phase}` reference. Row actions are **View details** and+**Remove from \<phase\>**. Removing a reference leaves the hook installed. To+remove it from the cluster, uninstall it on **Installed Guardrails**. That+strips the reference from every Host first, then deletes the CR. **Add+hook** goes to the same Marketplace list.++The UI edits hook references only. It has no editor for rules, built-ins,+trust floor, ceiling or limits, and it cannot attach an already-installed+hook to a second agent. Use the CRD (Option B) for those. The UI preserves+the fields it does not edit when it saves.++## Hook behaviour you should know++- **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.+ 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+ refusal):+ - a `failMode: closed` hook with `may_deny` contributes a deny+ (`hook_unavailable`);+ - a closed `postToolUse` redactor with `may_rewrite` withholds the tool+ result;+ - a closed `postCallSuccess` hook with `may_substitute_result` withholds+ 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.++- **Timeouts.** The per-call deadline is the Host's+ `limits.maxHookTimeoutMs`, default 5000 ms, on both lanes. mcp-host does+ not read `LlmHook.spec.timeoutMs`.+- **Circuit breaker.** `onUnavailable.mode: breaker` (threshold 5, cooldown+ 30000 ms by default) short-circuits a down hook without dialing it. It+ applies only to LLM-lane hooks **without** `may_deny`. A deny-capable hook+ is always dialed.+- **Digest binding.** For image hooks, mcp-host compares the Host's `digest`+ with `LlmHook.status.observedDigest`. On a mismatch it quarantines the+ hook: every call reports unavailable, so the fail-mode rules above apply.+ The same happens to a co-located hook that lost a `DuplicatePath`+ collision. Upgrade with `POST /admin/registry/upgrade-hook`, which bumps+ the CR and every Host's digest together.+- **The Host phase key does not filter.** mcp-host collects hook ids from+ all phases. The `LlmHook`'s own `lifecyclePoints` decide where it runs.++## Try the reference hook++[`hooks/reference-guardrail-hook/`](../../hooks/reference-guardrail-hook/) is+a zero-dependency Node server. It implements the **LLM-lane** points only:++- `pre_call` rejects jailbreak phrases;+- `moderate` returns 422 on disallowed content;+- `post_call` redacts card, SSN and email patterns;+- `on_error` returns a text fallback.++It has no tool-lane endpoints. To try it:++```bash+docker build -t reference-guardrail-hook:dev hooks/reference-guardrail-hook+minikube -p <profile> image load reference-guardrail-hook:dev+kubectl apply -f hooks/reference-guardrail-hook/deploy.yaml+```++Then point an `LlmHook` at the Service and reference it from a Host. Use+`kubectl`, because control-api only allows hooks to be created through+`install-hook`:++```yaml+apiVersion: clerum.io/v1alpha1+kind: LlmHook+metadata: { name: reference-hook, namespace: llm-hooks }+spec:+ target:+ service: { name: reference-guardrail-hook, namespace: llm-hooks, port: 8080 }+ lifecyclePoints: [preCall, moderate, postCallSuccess]+ capabilities: [may_deny, may_substitute_result]+ failMode: closed+---+# On the Host (service targets have no digest to pin):+spec:+ guardrails:+ capabilityCeiling: [may_deny, may_substitute_result]+ hooks:+ preCall: [{ id: reference-hook }]+```++host-context-controller marks a service-target hook `Ready=True` with reason+`NoWorkload`. It also creates `llmhook-svc-reference-hook`, which admits+ingress from the referencing Hosts only. A hand-applied CR skips the+install-time trust-floor and ceiling checks (see Limits).++## Verify++1. Run `kubectl get llmhooks -n llm-hooks` and check that the hook is Ready+ and that its digest matches the Host reference.+2. Send a prompt the hook should block. You should get a canned refusal+ (for example _"I can't comply with that request."_), not the model's+ answer.+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.++## Limits++- **Install-time checks only.** `minInstalledHookTrustLevel` and+ `capabilityCeiling` are checked by control-api at install and upgrade.+ mcp-host does not re-check them at runtime, so a reference added by+ editing the Host bypasses both.+- **No runtime reader.** `approvalPolicies` and `limits.maxHooksPerPhase`+ are accepted by the CRD, but nothing reads them today. Approver routing+ stays in `spec.approval`.+- **Response size caps.** `limits.maxHookOutputBytes` caps LLM-lane hook+ responses. The CRD default (65536) applies only when a `limits` object is+ present; otherwise mcp-host uses 1 MiB, and `preCall` rewrites get 5 MiB.+ Tool-lane hooks are not capped by this field.+- **LLM-lane only.** Quarantine on digest mismatch and the circuit breaker+ 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`).+ 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. |++## Related++- [LlmHook CRD](../crds/llmhook.md)+- [Host CRD → Guardrails](../crds/host.md#guardrails)+- [Configure approvals](configure-approvals.md)+- [Control UI](../surfaces/control-ui.md)+- [Claims guardrails](../meta/claims-guardrails.md)diff --git a/docs/how-to/connect-llm-subscription.md b/docs/how-to/connect-llm-subscription.mdnew file mode 100644index 000000000..be9ce631a--- /dev/null+++ b/docs/how-to/connect-llm-subscription.md@@ -0,0 +1,293 @@+# How to: use a ChatGPT (Codex) or Grok subscription instead of an API key++evenfire has two LLM providers that sign in with a subscription account rather+than an API key:++| Provider id | Control UI label | Sign-in |+| -------------------- | ----------------------- | ----------------------- |+| `codex-subscription` | "ChatGPT Subscription" | ChatGPT account (Codex) |+| `grok-subscription` | "xAI Grok Subscription" | xAI account (SuperGrok) |++An admin signs in once from Control UI. Agents (Hosts) and workflow recipes+then pick that sign-in, and the account's subscription entitlement pays for the+calls instead of metered API billing. Both providers are **off in+`deploy/base`** and switched on in the minikube overlay.++This page covers the operator workflow. For the wire format, limits and error+taxonomy, see the [Codex transport contract](../architecture/codex-subscription-transport-contract.md)+and the [Grok transport contract](../architecture/grok-subscription-transport-contract.md).++## How it works++1. **control-api holds the credential.** The OAuth tokens are stored+ encrypted in control-api's database. There is no Kubernetes Secret and no+ `secretRef` slot for these providers.+2. **A Host or recipe names a connection.** Each sign-in is a named+ _connection_ (also called a _grant_). A Host picks one with+ `spec.model.connectionRef`.+3. **Traffic goes through a broker in `control-plane`.** For every model call,+ `mcp-host` asks control-api to authorize the attempt and gets a single-use+ ticket. It then streams to `codex-llm-proxy` or `grok-llm-proxy`, which+ redeems the ticket, holds the access token only for that operation, and+ calls the vendor's subscription endpoint. The model stream never passes+ through control-api.+4. **Models come from the account.** Each connection has its own model+ catalog, read from the vendor at sign-in. There is no built-in default+ model, and nothing falls back to an API key.++## Enable on your cluster++Every switch below defaults to off. Set them in this order: proxies and+control-api first, then the Host and recipe switches.++| Key | Where it lives | Codex | Grok |+| ---------------------------------------- | ---------------------------------------------------------------- | -------- | ------------------------- |+| `CONTROL_API_CODEX_SUBSCRIPTION_ENABLED` | ConfigMap `control-api-config` (ns `control-plane`) | `"true"` | — |+| `CONTROL_API_GROK_SUBSCRIPTION_ENABLED` | ConfigMap `control-api-config` (ns `control-plane`) | — | `"true"` |+| `CODEX_LLM_PROXY_EXECUTION_ENABLED` | ConfigMap `codex-llm-proxy-config` (ns `control-plane`) | `"true"` | — |+| `GROK_LLM_PROXY_EXECUTION_ENABLED` | ConfigMap `grok-llm-proxy-config` (ns `control-plane`) | — | `"true"` |+| `MCP_HOST_CODEX_SUBSCRIPTION_ENABLED` | ConfigMap `mcp-host-config` (ns `mcp-host`) | `"true"` | — |+| `WRC_GROK_SUBSCRIPTION_ENABLED` | `env` on the `workflow-recipes` Deployment (not a ConfigMap key) | — | `"true"` for Grok recipes |+| `MCP_HOST_GROK_SUBSCRIPTION_ENABLED` | **Do not set.** HCC injects it per Host | — | automatic |++Notes:++- The flags accept only the exact string `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+ (`deploy/overlays/minikube/configmaps/mcp-host-config.yaml`).+- `MCP_HOST_GROK_SUBSCRIPTION_ENABLED` is added by HCC only to Hosts that are+ actually configured for Grok, once control-api has Grok on. Do not put it in+ `mcp-host-config`.+- Each proxy needs its inter-service token in `codex-llm-proxy-secrets` or+ `grok-llm-proxy-secrets`. `deploy/scripts/apply-inter-service-tokens.sh`+ creates both.+- Optional: `SUBSCRIPTION_CATALOG_SYNC_CRON_ENABLED` in `control-api-config`+ turns on periodic catalog refresh (see [Models and catalog sync](#models-and-catalog-sync)).+- The minikube overlay sets everything in the table under+ `deploy/overlays/minikube/` (`configmaps/*` and+ `patches/workflow-recipes-grok.yaml`).++Restart the affected Deployments after you change a ConfigMap. For upgrade+order on a live cluster, see the Grok contract's+[Rollout order](../architecture/grok-subscription-transport-contract.md#rollout-order).++To check what control-api thinks is on, call+`GET /api/v1/admin/llm/providers/capabilities`. It returns+`{ "providers": { "codex-subscription": { "enabled": … }, "grok-subscription": { "enabled": … } } }`.++## Connect a subscription++1. In Control UI, open **Secrets → LLM Subscriptions**+ (`/secrets/llm/subscriptions`).+2. Create a subscription. Pick the **Provider** (ChatGPT or Grok; only+ enabled providers are offered) and give it a **Name** of up to 64+ characters. Agents see this name when they pick a subscription.+3. Click **Sign in with ChatGPT** or **Sign in with Grok**. Control UI opens+ the vendor's verification page in a new tab and shows a one-time code.+ Sign in there with the subscription account and enter the code.+4. When the sign-in completes, control-api reads the account's model catalog.+ You see "Connected — catalog synced".+5. Under **Enabled models**, turn models on or off. Under **Primary model**,+ choose the default model. It must be one of the enabled models.++For Grok, the sign-in panel shows a notice about how evenfire authenticates to+xAI. Read it before you connect.++### Device code vs browser sign-in++Control UI always uses the **device-code** flow for both providers. It works+with the public CLI client ids that control-api ships as defaults.++control-api also has a **browser OAuth** flow for Codex only+(`POST /api/v1/admin/llm/providers/codex-subscription/connections/:key/browser/start`).+Control UI does not call it. It is refused with `browser_oauth_unregistered`+unless `CONTROL_API_CODEX_OAUTH_CLIENT_ID` is set to an OpenAI client that you+registered for this callback URL:++```text+<control-ui origin>/control-api/api/v1/auth/codex-subscription/callback+```++The origin comes from `CONTROL_API_CONTROL_UI_BASE_URL`. Grok has no browser+flow.++### Multiple named connections++You can create as many connections as you need, for example one per team+account. Each one has its own tokens, catalog and enabled models.++- Keys are generated as `codex-<hex>` or `grok-<hex>`. Through the API you+ can supply your own key instead: lowercase letters, digits and `-`, up to+ 63 characters.+- One vendor account can back only one live connection per provider. A second+ sign-in with the same account fails with `fingerprint_in_use`.+- `unassigned` is reserved for both providers.++### The `deployment-default` connection++`deployment-default` is a reserved Codex key from the original single-grant+design. The un-keyed Codex admin routes (for example+`GET …/codex-subscription/connection`) act on it. If it exists, a Host uses it+only when its `connectionRef` names it explicitly. An empty `connectionRef` is+never treated as `deployment-default`.++Grok does not accept `deployment-default` at all. Every Grok connection uses+a named key.++## Assign a subscription to an agent++### In Control UI++1. Open the agent, then the **Models & creds** tab (`/agents/<name>/model`).+2. Edit the model configuration and choose provider **ChatGPT Subscription**+ or **xAI Grok Subscription**. The new-agent wizard offers the same options.+3. In **Credential**, choose one of the subscriptions created under Secrets.+ Agents only choose a subscription. Creating one happens under Secrets.+4. Pick a model from that connection's enabled models and save.++Saving without a subscription fails with "Choose a ChatGPT subscription+before saving." (or the Grok version).++### In the Host CRD++```yaml+apiVersion: clerum.io/v1alpha1+kind: Host+metadata:+ name: chatllm+ namespace: mcp-host+spec:+ host: chatLLM+ contextRef: context1+ model:+ provider: codex-subscription # or grok-subscription+ name: <a model enabled on this connection>+ connectionRef: codex-0123456789abcdef+```++The CRD enforces these rules:++- `spec.secretRef` may be omitted only when the primary and every+ `llmPolicy.fallbacks[]` entry use the same subscription provider. With an+ API-key fallback you still need `secretRef`.+- `credentialSlot` is not allowed on a subscription fallback.+- A Host may use at most one subscription provider across `model`,+ `llmPolicy.fallbacks` and `allowedModels`. You cannot mix Codex and Grok.++See [Host CRD](../crds/host.md) for the full schema.++### What "unassigned" means++A subscription Host with no `connectionRef` is **unassigned**. It is never+given the execute permission, so it makes no model calls. It does not fall+back to `deployment-default` or to an API key. Model calls fail with+`unassigned_connection` ("Host has no coding-plan subscription assigned").++### Admin API++The admin API can also list Hosts and assign them without the agent page.+Every route is under `/api/v1/admin/llm/providers/<provider-id>/`:++| Route | Purpose |+| --------------------------------------------- | --------------------------------------------------------------- |+| `GET connections` | Connections with their assigned Hosts, plus `assignableHosts` |+| `GET assignable-hosts` | Every Host with its provider, model and current `connectionRef` |+| `POST connections/:key/hosts/:hostRef/bind` | Point a Host at this connection and seed a model |+| `POST connections/:key/hosts/:hostRef/unbind` | Set the Host back to `unassigned` |++## Models and catalog sync++A connection's catalog is read at sign-in and **is not refreshed on its own**.+A model the vendor publishes later does not appear until you sync:++- In Control UI, open the subscription and click **Sync catalog**.+- Or call `POST /api/v1/admin/llm/providers/<provider-id>/connections/:key/catalog/sync`.+- `GET …/connections/:key/models` lists the catalog, and+ `PATCH …/connections/:key/models/:model` with `{ "enabled": true|false }`+ turns one model on or off.++For periodic sync, set `SUBSCRIPTION_CATALOG_SYNC_CRON_ENABLED: "true"` in+`control-api-config`. The interval is `SUBSCRIPTION_CATALOG_SYNC_INTERVAL_MS`:+6 hours by default, and control-api refuses to start below 15 minutes. It is+off by default on purpose. Each tick calls the vendor once per connection,+and a Grok token refresh during a tick rotates the refresh token.++## Use a subscription in a workflow recipe++Both providers are valid for `spec.agent.provider` and step agents in a+`WorkflowRecipe`, with these rules:++- A recipe may use at most one subscription provider.+- `spec.agent.secretRef` is not allowed for a subscription provider.+- The recipe picks a connection with an annotation, not a spec field. In the+ recipe editor's confirm step, choose a **ChatGPT grant** or **Grok grant**.+ Codex recipes store it in `clerum.io/codex-connection-ref` and+ `clerum.io/subscription-connection-ref`. Grok recipes store it in+ `clerum.io/subscription-connection-ref` only.+- Grok recipes also need `WRC_GROK_SUBSCRIPTION_ENABLED=true` on+ `workflow-recipes`. That switch controls the recipe's Grok permission,+ egress policy and pod environment.++## Refresh, reconnect and revoke++- **Access-token refresh is automatic.** control-api refreshes the access+ token when it authorizes a call. `POST …/connections/:key/refresh` forces+ a refresh.+- **Reconnect.** If the vendor rejects the saved refresh token, the+ connection moves to `reauth_required` and Control UI shows+ **Reconnect ChatGPT** / **Reconnect Grok**. This runs the same device-code+ sign-in.+- **Delete (revoke).** **Delete** in the subscription list revokes the+ connection. control-api marks it revoked, cancels pending sign-ins, and asks+ the vendor to revoke the refresh token. Agents assigned to it keep the reference but can no longer+ authorize. Reassign them to another subscription.+- **Grok revoke is permanent per key.** A revoked Grok key cannot be+ reconnected. Create a new subscription instead. Access tokens issued+ before the revoke stay valid until they expire.++## Limits to know++- **Output ceiling on Codex SDK grants.** A Plugin Workload SDK grant's+ per-grant output ceiling (`maxOutputTokens`) becomes `max_tokens` on API-key+ providers. The ChatGPT subscription endpoint cannot take that field, so for+ `codex-subscription` only the transport contract's fixed limit applies.+- **Image input.** Both providers accept PNG and JPEG image parts. The Grok+ image limits are based on xAI's public API documentation. They have not been+ measured against the Grok subscription endpoint. See+ [Visual requests](../architecture/grok-subscription-transport-contract.md#visual-requests-issue-784).+- **One subscription provider per Host or recipe** (see above).+- **Requests are capped.** Message, tool and body-size caps are listed under+ _Limits_ in each transport contract.++## Troubleshooting++| Symptom / error | Cause | Fix |+| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |+| No **LLM Subscriptions** content, or API `404 {"error":"disabled"}` | `CONTROL_API_*_SUBSCRIPTION_ENABLED` is not `true` | Set the flag in `control-api-config` and restart control-api |+| Calls fail although sign-in worked; proxy answers `404 disabled` | `*_LLM_PROXY_EXECUTION_ENABLED` is off | Set it in the proxy's ConfigMap and restart the proxy |+| Codex Host cannot build its provider | `MCP_HOST_CODEX_SUBSCRIPTION_ENABLED` missing from `mcp-host-config` | Add it, then let HCC roll the Host |+| Grok recipe is refused or cannot reach the proxy | `WRC_GROK_SUBSCRIPTION_ENABLED` is off | Set it on the `workflow-recipes` Deployment |+| `browser_oauth_unregistered` | Browser OAuth with the default public client | Use device code, or register an OpenAI client and set `CONTROL_API_CODEX_OAUTH_CLIENT_ID` |+| "… sign-in expired / denied / timed out" | Device code was not confirmed in time | Click **Sign in** again |+| `fingerprint_in_use` | That account already backs a live connection | Use the existing connection |+| `connection_key_taken` | Key already exists (for Grok, possibly a revoked key) | Choose another key |+| `reauth_required` / "Reconnect" shown | Vendor rejected the refresh token | Click **Reconnect**, then **Sync catalog** |+| New vendor model missing | Catalog is only read at sign-in | **Sync catalog**, or enable the cron |+| `default_model_not_offered` | Default model is not an enabled model on that connection | Enable the model first |+| `unassigned_connection` | Host has no `connectionRef` | Assign a subscription on **Models & creds** |+| `spec.secretRef is required unless every LLM target is the same oauth-broker provider` | Mixed subscription + API-key chain without a Secret | Add `secretRef` for the API-key targets |+| `a Host may declare at most one oauth-broker provider` | Codex and Grok on one Host | Use one subscription provider per Host |+| `hosts_unavailable` (503) | control-api cannot read Host objects | Check control-api's Kubernetes access |++## Related++- [LLM providers](../llm-providers/README.md) (Group D: subscription sign-in)+- [Codex subscription transport contract](../architecture/codex-subscription-transport-contract.md)+- [Grok subscription transport contract](../architecture/grok-subscription-transport-contract.md)+- [Grok subscription validation](../testing/grok-subscription-validation.md)+- [Host CRD](../crds/host.md)+- [Control UI](../surfaces/control-ui.md)+- [Track usage and set token budgets](token-budgets-and-usage.md)diff --git a/docs/how-to/connect-oauth-connector.md b/docs/how-to/connect-oauth-connector.mdnew file mode 100644index 000000000..c9e3e7c72--- /dev/null+++ b/docs/how-to/connect-oauth-connector.md@@ -0,0 +1,263 @@+# How to: connect an OAuth connector and manage connector credentials++Some connectors (MCP servers) authenticate with OAuth instead of a static API+key. For these, an operator installs the connector once, and each user (or one+member of a Context) authorizes it in the browser. control-api keeps the+tokens. This page covers that flow, then the second half of the topic:+setting and rotating credentials for connectors that use a static Secret.++Field-by-field reference: [McpServer CRD, OAuth (`spec.oauth`)](../crds/mcpserver.md#oauth-specoauth).++## Mental model++1. An operator installs an `McpServer` with `spec.auth.type: oauth` and a+ `spec.oauth` block. No token is stored on the resource.+2. A user authorizes it in the Desktop app. The provider redirects back to+ control-api's OAuth callback, and control-api stores the grant encrypted+ (AES-256-GCM, access and refresh tokens).+3. When an agent calls a tool on that server, mcp-host asks control-api's+ broker for a token for that connection and sends it as an+ `Authorization: Bearer` header on the request.+4. If no grant exists, the task pauses and the chat shows a **Connect** prompt+ instead of Approve/Deny.++Tokens are never mounted into the connector pod. host-context-controller only+hashes and mounts the static `spec.envSecret`. For remote servers, the egress+proxy it generates passes the per-request `Authorization` header through. It+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). |++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,+because control-api computes its redirect URI. If your build does not set the+variable, install built-in and generic connectors with YAML (below).++The desktop app opens the provider's authorize URL only if it uses `https:`.++## Three ways to configure OAuth++| Style | `spec.oauth.source` | How you install it | Redirect URI to register |+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |+| Built-in provider adapter | absent; `provider` is one of `salesforce`, `slack`, `notion`, `microsoft-graph`, `google`, `monday`, `clickup`, `vercel` | YAML, or the Marketplace OAuth form | `<CALLBACK_BASE>/api/v1/oauth-callback/<oauth.id>` |+| Remote MCP server (discovery) | `remote` | Control UI **Add remote server** wizard | `/api/v1/oauth-callback/remote` if the authorization server supports RFC 9207 `iss`; otherwise `/api/v1/oauth-callback/remote/<serverName>` |+| Generic, operator-configured client | `generic` | YAML, or the Marketplace OAuth form (adds an **Endpoints** step) | `<CALLBACK_BASE>/api/v1/oauth-callback/<oauth.id>` |++Endpoints for `remote` and `generic` must use `https` and a public host. Hosts+that resolve to private, metadata, link-local, or reserved addresses are+rejected.++`source`, `provider`, `oauth.id`, and `grantScope` cannot be changed after+creation. To change one, delete the connector and install it again.+Reinstalling invalidates existing grants: grants are bound to the McpServer's+UID, so users must authorize again.++### Who holds the grant: `grantScope`++- **`user`** (default; shown as **Per user**): each user authorizes their own+ account. One grant per user covers every agent of theirs that uses this+ connector.+- **`context`** (shown as **Per context** / **Shared (context)**): one shared+ grant per Context. Any member authorizes it, and every agent in that Context+ then acts with that identity. Desktop asks the user to confirm before+ connecting or disconnecting a shared grant.++Users can only authorize or disconnect servers whose `spec.contextRef` is a+Context they belong to. Otherwise the request fails with+`context_membership_denied`.++## Operator: add a remote MCP server (Control UI)++1. Open **Connectors** (`/connectors`) and click **Add remote server**+ (`/connectors/remote/new`).+2. **Identify**: enter the **Remote server URL** (for example+ `https://mcp.example.com/mcp`), a **Server name** (a Kubernetes name), and+ the **Context** to attach the server to. Click **Detect**.+ control-api runs RFC 9728/8414 discovery and probes the MCP endpoint. If the+ endpoint is unreachable, the wizard stays on this step and may suggest the+ correct URL.+3. **Configure**: review the detected issuer, endpoints, scopes, and+ **Registration mode**. The mode is picked in this order:+ - **Client ID Metadata Document (public client)**: no credentials. Offered+ only when the server supports RFC 9207 `iss`. The client ID is a URL on+ your callback origin+ (`<CALLBACK_BASE>/api/v1/.well-known/evenfire-mcp-client`), so the+ authorization server must be able to fetch it.+ - **Dynamic Client Registration**: control-api registers a client and stores+ its credentials encrypted. You do not supply any.+ - **Pre-registered client required**: register an OAuth app at the provider+ with the **Redirect URI** the wizard shows, then paste its **Client ID**+ and **Client secret**.++ Choose the **Grant scope**: **Per user** (recommended) or **Per context**.++4. **Confirm**: review the summary and click **Install remote server**. If the+ mode is pre-registered, the wizard shows the final redirect URI again.+ Register exactly that URI. If the authorization server changed since+ detection, the wizard warns that the URI is different.++The install creates the client Secret (pre-registered only), the McpServer, and+the Context attachment, and rolls back if a step fails. The resulting+McpServer runs the platform egress proxy image (`clerum/nginx-egress-proxy`)+with an exact-host egress binding to port 443 of the remote host. API+equivalents: `POST /api/v1/admin/mcp-servers/remote/discover` (dry run) and+`POST /api/v1/admin/mcp-servers/remote`.++## Operator: built-in or generic provider (YAML)++Create an OAuth app at the provider, register the redirect URI, and store the+client credentials in a Secret in the MCP server namespace:++```yaml+apiVersion: clerum.io/v1alpha1+kind: McpServer+metadata:+ name: notion+ namespace: mcp-server+spec:+ contextRef: context1+ # image, transport, egress: see the CRD reference+ auth:+ type: oauth # forbids auth.secretRef / auth.secretKey+ oauth:+ id: notion-mcp # callback path segment, immutable+ provider: notion+ clientIdRef: { name: notion-oauth-client, key: client_id }+ clientSecretRef: { name: notion-oauth-client, key: client_secret }+ scopes: [...] # provider-specific+ grantScope: user+```++Redirect URI for this example:+`<CONTROL_API_OAUTH_CALLBACK_BASE_URL>/api/v1/oauth-callback/notion-mcp`.+For `generic`, set `source: generic` and add the endpoint and wire fields+listed in the [CRD reference](../crds/mcpserver.md#oauth-specoauth).++If the client Secret or one of its keys is missing, authorization fails with+`503 integration_not_configured`, and the error message names the missing+Secret.++## End user: authorize, use, disconnect++**Ahead of time:** in the Desktop app, open **Connectors**. There is one row+per connector and agent, and each row shows **Authorized**, **Requires setup**,+or **No OAuth**. Click **Authorize** to open the provider's consent page in your+system browser. A connector you already authorized shows **Disconnect**.+Connectors with static credentials (**No OAuth**) have no button.++**In chat:** if an agent calls a tool on an OAuth connector you have not+authorized, the task pauses and the progress card shows+**Connect \<server\> to continue**. Clicking **Connect \<server\>** opens the+same browser consent. When the browser hands control back to the app+(`clerum://oauth-completed`), the paused task continues. The pause survives an+mcp-host restart.++## Refresh and background use++- **Refresh on use:** when a stored access token is within 60 seconds of+ expiry, control-api refreshes it before returning it. If there is no refresh+ token, or a remote or generic server was installed with+ `supportsRefresh: false`, the user is asked to connect again.+- **Proactive refresh** of remote-server grants runs only when+ `OAUTH_PROACTIVE_REFRESH_CRON_ENABLED=true`. It is off by default.+- **`backgroundAccess`** is a field on the spec (see the CRD reference). The+ broker path agents use today requests tokens as a live session, so do not+ count on unattended access without testing it in your environment. If you+ need refresh, request the provider's offline or refresh scope.++## Disconnect and revoke++- **User:** **Disconnect** on the Desktop Connectors page. Desktop asks for+ confirmation, then calls `DELETE /api/v1/mcp-oauth/<server>/grant` through+ rpc-proxy, which deletes the stored grant. For a **Per context** connector,+ this removes access for everyone in the Context.+- **Admin (API only, no Control UI screen):**+ `GET /api/v1/admin/mcp-servers/<name>/oauth/user-grants` lists users with a+ grant. `DELETE /api/v1/admin/mcp-servers/<name>/oauth/user-grants/<userId>`+ with body `{ "oauthClientId": "..." }` force-revokes one user's grant.+- **Limits:** revocation deletes evenfire's copy of the grant. It does not call+ the provider's revocation endpoint, so revoke the app at the provider too if+ you need that. Sessions that are already running may keep a cached token+ for a while. Desktop warns that "active sessions end on the next revocation+ sweep."++## Part 2: credentials for static-credential connectors++Connectors that use API keys read them from the Secret named in+`spec.envSecret` (in the MCP server namespace). OAuth connectors do not use+this flow. Their **Credentials** tab shows the client configuration read-only,+and rotating an OAuth client secret is not available in Control UI.++### Install now, add credentials later++When you install a connector from the **Marketplace**, leave every credential+field empty to install it without credentials. A partly filled form is+rejected. host-context-controller then sets the condition+`SecretResolved=False` (reason `SecretNotFound`) and does not deploy the+connector. **Connectors** shows the badge **Missing Secret**.++```bash+kubectl get mcpserver <name> -n mcp-server \+ -o jsonpath='{.status.conditions[?(@.type=="SecretResolved")]}'+```++### Set or rotate credentials++Open the connector, click **Edit connector**, and select the **Credentials**+tab (`/connectors/<name>/edit`). The tab lists each Secret key and its+environment variable. Stored values are never shown.++- **Secret missing** (`SecretNotFound`): the section is **Set credentials**.+ Fill every key, click **Set credentials**, then confirm with **Set & start**.+ This creates the Secret, and the connector starts.+- **Secret exists** (including `SecretMissingKey`): the section is+ **Update credentials**. Fill only the keys you want to change; blank fields+ keep their current value. Click **Rotate credentials**, then confirm with+ **Rotate & restart**.++Rotation calls `PUT /api/v1/admin/mcp-secrets/<name>` with `{ "data": { ... } }`.+This is a server-side merge patch: the keys you send are added or replaced, and+every other key stays. Empty values are rejected, and the response never echoes+values. It also returns `affectedConnectors`: every McpServer whose+`spec.envSecret` uses this Secret. Secrets owned by a WorkflowRecipe are+refused (`409`).++control-api does not restart anything itself. host-context-controller watches+Secrets, recomputes a SHA-256 of the Secret data, and writes it to the pod+template annotation `clerum.io/credentials-revision`. Every affected Deployment+then rolls out. The Control UI waits up to 180 seconds for this connector's+Deployment to become ready again. Other connectors that share the Secret roll+out too, but the screen only tracks the current one.++## Troubleshooting++| Symptom | Likely cause | Fix |+| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |+| 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` |+| **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 |+| `403 context_membership_denied` | The user is not a member of the server's Context | Add the user to the Context |+| Users must authorize again after a reinstall | Grants are bound to the old McpServer UID | Expected |+| Connector shows **Missing Secret** | `SecretResolved=False` | Use **Set credentials** on the **Credentials** tab |+| Rotation restarted other connectors | They share the same `envSecret` | Expected. Check `affectedConnectors`. |++## Related++- [McpServer CRD: OAuth and status conditions](../crds/mcpserver.md#oauth-specoauth)+- [Add an MCP server](add-mcp-server.md)+- [Configure approvals](configure-approvals.md)+- [Control UI](../surfaces/control-ui.md) and [Desktop app](../surfaces/desktop-app.md)diff --git a/docs/how-to/desktop-setup-and-updates.md b/docs/how-to/desktop-setup-and-updates.mdindex 213b2c4ad..694aa8d92 100644--- a/docs/how-to/desktop-setup-and-updates.md+++ b/docs/how-to/desktop-setup-and-updates.md@@ -90,8 +90,8 @@ After you authenticate, the app checks the **currently selected tenant** for itsupdate policy, so different tenants can be on different versions at the sametime. It asks that tenant's External REST API for its release info, including a`minimumDesktopVersion`. If the installed version is **below** that minimum, the-app shows an **update-required** screen and opens the release page for the new-build (tag `desktop-app-<version>`) in your browser. (A packaged distribution is+app shows a **Desktop update required** dialog; **Download update** opens the+release page for the new build (tag `desktop-app-<version>`) in your browser. (A packaged distribution iswhere this matters most — a source checkout can just pull the latest.)This is update **detection**, not silent auto-install: the app tells the user andiff --git a/docs/how-to/use-the-desktop-app.md b/docs/how-to/use-the-desktop-app.mdnew file mode 100644index 000000000..beffe3184--- /dev/null+++ b/docs/how-to/use-the-desktop-app.md@@ -0,0 +1,305 @@+# How to: use the Desktop App day to day++The Desktop App is where members chat with their agents, approve the actions+that need a human, open the apps that plugins ship, and work with files in+EvenDrive. This guide walks through the screens as they appear in the app. It+is written for members, and for the admins who help them.++For what the app is and how it connects to the platform, see+[Desktop App](../surfaces/desktop-app.md). For adding environments, the+invitation setup, and update checks, see+[Desktop setup & updates](desktop-setup-and-updates.md).++> **Shortcut convention.** **Mod** means **Cmd (⌘)** on macOS and **Ctrl** on+> Windows and Linux. For example, Mod+K is ⌘K on a Mac and Ctrl+K elsewhere.++## First run++The first time you open the app, it has no server to connect to yet, so it+shows a short setup wizard instead of the sign-in screen. The first question+is **Do you already have an Evenfire server?**, and it has three answers:++| Answer | What happens next |+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| **My team already uses Evenfire** | **Connect to your team**: enter the email address your team invited and choose **Continue setup**. The app opens your browser so you can finish setup there. |+| **I have a server address** | **Connect to a server**: enter an **Environment name** and the **External REST API** address, then choose **Save environment**. If the app finds an Evenfire server running on this computer, it also offers a one-click **Localhost** option. |+| **No, I'm just getting started** | **How do you want to run Evenfire?**, with three choices: **Evenfire hosts it for me**, **I'll run it myself**, or **I have no idea**. The last one opens **Which one is right for you?**, which compares the two options. |++The hosted and self-hosted choices each explain the option and offer a+button that opens more in your browser: **See hosted Evenfire** or+**Open the deployment guide**. A second button,+**I have a server — enter its address**, takes you to **Connect to a server**. Use **Back** at the bottom of the card to change an+earlier answer.++After setup you sign in with your **Email** and **Password**. If you forgot+your password, **Forgot password** opens the reset page in your browser.+Environments are added and switched from the **Environment** selector at the+bottom of the sign-in screen. See+[Desktop setup & updates](desktop-setup-and-updates.md) for details.++## Find your way around++### Sidebar++| Entry | What it does |+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| **Chat** | Opens your chats. The **New chat** button next to it starts a chat. Expand it to see your most recent sessions. Each session has a **⋯** menu with **Rename** and **Delete** (deleted messages can't be recovered). |+| **Apps** | Opens the app picker. Expand it to launch an app directly. |+| **EvenDrive** | Opens your files. Expand it to see a file tree that you can browse right in the sidebar. |+| **Settings** (bottom) | Opens a menu that shows your name and email, plus **Agents**, **Connectors**, **Plugins**, **Settings**, and **Logout**. |++You can collapse the sidebar to icons with **Collapse sidebar** and bring it+back with **Expand sidebar**.++### Tabs and Home++Chats, apps, EvenDrive folders, and file previews open as **tabs** in one+strip across the top of the window. Tabs stay open as you move around the+app. You can drag a tab to reorder it, and close it with its **×**. Closing a+chat tab doesn't delete the conversation; you can reopen it from the sidebar.+When no tabs are open, Home shows **Nothing open** with a **New chat** button.++### Title bar++The window has its own title bar on every platform:++- **Search** (Mod+F) searches your **Agents**, **Connectors**, **Plugins**,+ and **Apps**.+- The bell, **Notifications and approvals**, opens your inbox. When something+ is waiting on you, it shows a **Pending approvals** section at the top.+- **Open chat drawer** appears while you're on a tab that isn't a chat, such+ as an app or a folder. It opens a chat panel on the right so you can talk to+ an agent alongside your work.+- The window buttons (**Minimize**, **Maximize**/**Restore**, **Close**)+ follow your platform's order. Double-click an empty part of the title bar+ to maximize or restore the window.++### Chat drawer++The chat drawer is a resizable panel on the right. At the top is the+**Open chats** switcher, which lets you jump between open chats. While an app+is open, Mod+E opens the drawer and puts you in the switcher. The+drawer also has buttons for **New chat**, **Open chat in full screen**, and+**Collapse chat drawer**. If the window gets too narrow, the drawer hides+itself and comes back when there's room again.++## Chat with an agent++1. Start a chat with **New chat** (or Mod+T). The page asks+ **Start a new conversation with:** followed by an agent picker. Choose the+ agent you want.+2. Type in the composer. **Enter** sends the message. **Shift+Enter** adds a+ new line. While a chat is showing, in a tab or in the drawer, Mod+Shift+L+ moves the cursor to the composer.+3. While the agent works, a live status line shows what it's doing, such as+ `Using <tool>`, `Thinking …`, or `Finished <tool>`. When the answer+ arrives, **More details · N tools** expands the steps behind it, and the+ square **Stop agent** button cancels a run that's still going.++### Add context and attach files++The **+** button (**Add context**) in the composer opens a menu with:++- **Plugins** and **Connectors**: attach a reference to a specific plugin or+ connector so the agent knows to use it.+- **Upload Files**: pick files from your computer. You can also drag files+ onto the composer (**Drop files here**) or paste them in.++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 |++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+most 2048 px on their longest side. If the model you've chosen doesn't accept+images, the composer tells you.++### Choose a model for this chat++The model chip in the composer shows which model the chat uses. Click it to+pick another model your admin allows. The change **applies to your next+message**, not to one that's already running. If the list can't load, the+chip reads **Models unavailable**; click it to try again.++### Approve, deny, or connect++Some tool calls need your approval before they run, depending on how your+admin set up approvals (see [Configure approvals](configure-approvals.md)).+When that happens, the run pauses in the chat and shows+**`<tool>` requires approval**, with a preview of the tool's input and+**Approve** and **Deny** buttons. Approvals from plugin workflows also show up+under **Pending approvals** in the notifications inbox.++If a connector needs you to sign in first, the chat shows+**Connect `<server>` to continue** and a **Connect `<server>`** button+instead. The button opens the provider's sign-in page.++### Generated files++When an agent produces files, they appear under the answer in a+**Generated files** list. You can **Download** each file, or use+**Download all**. HTML and Markdown files also have a **Preview** button.++## EvenDrive++**EvenDrive** in the sidebar opens the **Files** page. It starts at+**Shared with me**, which lists everything that has been shared with you;+click a folder to go into it. The breadcrumb at the top shows where you are.++- **Add files.** In a folder you can edit, use **New folder** and+ **Upload file**, or drag files onto the page. The server sets the size+ limit for uploads, and the app tells you if a file is too large.+- **Organize.** Each item's menu has **Rename**, **Move to…**, **Download**,+ and **Delete**, depending on your access. When you open a file you can edit,+ its menu also has **Replace file**. You can also drag an item onto a folder+ to move it. Deleting a file or folder deletes it for everyone who has+ access.+- **Share.** Choose **Share** to open the sharing dialog. Under+ **Add people, teams, agents, or workflows**, you can give someone **Read** or+ **Editor** access. The **People with access** list shows who already has+ access, including people who get it from a parent folder. A folder's+ permissions apply to everything inside it, so changing or removing someone's+ inherited access on one item asks you to confirm the change on the parent+ folder (**Update role on parent folder?** or **Remove from parent folder?**).+ To give one file less access than its folder, put it in a separate folder+ with more limited access.+- **Preview.** Images, Markdown, and videos open in a preview tab.+- **Links.** **Copy link** copies a link to an item. On **Shared with me**,+ **Open EvenDrive link** lets you paste a link to go straight to that item.++For how EvenDrive storage works behind the scenes (the GlobalFileSystem), see+[Shared and global files](shared-and-global-files.md).++## Agents++**Settings → Agents** lists the agents you can use (_Create, manage, and+monitor your AI agents from one place_). Open an agent to see its+**Connectors**, **Members**, and **Activity** sections. In a new chat, each+agent in the agent picker has a **⋯** menu that jumps to the same sections.++## Connectors++**Settings → Connectors** lists each connector for each agent you can use,+with a status of **Authorized**, **Requires setup**, or **No OAuth**. Choose+**Authorize** to sign in to a connector's provider, or **Disconnect** to+remove your access. Hover over the status to see whether access applies only+to you or is shared with your whole Context. Click a row to open that+agent's own Connectors tab. For the full sign-in flow, see+[Connect an OAuth connector](connect-oauth-connector.md).++## 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+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+**`<plugin>` wants access to your information**, with **Allow** and **Deny**.+You can review or remove that access later under+**Settings → Plugin permissions**, using **Revoke** or **Revoke all**.++**Settings → Plugins** lists the plugins deployed for you, along with their+**Status** and **Recent Runs**. You can download files produced by recent+runs from here. **Trigger** starts a plugin, asking for any inputs it needs,+if the plugin supports being started by hand. **Refresh** reloads the+run list.++## Keyboard shortcuts and the command palette++| Shortcut | Action |+| ------------------------- | --------------------------------------------------------------------- |+| Mod+T | New chat tab |+| Mod+E | Open chats switcher (while an app is open) |+| Mod+W | Close current tab (the conversation is kept) |+| Mod+1 … Mod+8 | Select tab 1–8 |+| Mod+9 | Select last tab |+| Ctrl+Tab / Ctrl+Shift+Tab | Next / previous tab (this is Ctrl on every platform, including macOS) |+| Mod+F | Focus global search |+| Mod+Shift+F | Search current content (find text in the open chat or app) |+| Mod+Shift+L | Focus message composer (while a chat is showing) |+| Mod+K | Open command palette |+| Mod+, | Open Settings |++These shortcuts also work while an app has focus. You can't change them:+**Settings → Shortcuts** lists them for reference only.++**Mod+K** opens the command palette (**Type a command**). Besides everything+in the table above, it can run commands that have no shortcut:+**Keyboard shortcuts**, **Log out**, **Go to Chat / Apps / Agents / Plugins /+Connectors / EvenDrive**, **Open notifications and approvals**,+**Toggle sidebar**, **Refresh current app**, and **Back to Apps**. The palette+only lists the commands that make sense at that moment.++## Links that open the app++The app handles `evenfire://` links:++| Link | What it does |+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `evenfire://desktop-environment?externalRestApiBaseUrl=…` | Adds or updates an environment. The app first asks **Add desktop environment?** and shows the addresses, so you can check that you trust them. Profile UI's **Open desktop app and setup** button opens this kind of link. |+| `evenfire://desktop-setup?…` | Finishes invitation setup after you complete it in the browser. |+| `evenfire://logout` | Signs the app out. |+| `evenfire://app/<namespace>/<name>?path=…&team=…` | Opens an app, optionally on a specific page and team. The app first asks **Open app link?**; choose **Open** or **Dismiss**. |++**Copy current app link** copies a regular web link of the form+`https://<profile-ui>/open/apps/<namespace>/<name>`, which you can paste+anywhere. Opening it in a browser hands it to the Desktop App as an+`evenfire://app/…` link, so the person you share it with lands in the same+app (as long as they have access to it).++## Settings++Open Settings with **Settings → Settings** or Mod+,. It has these tabs:++- **Account**: your name and email. **Edit** and **Update password** open+ your profile in Profile UI.+- **Appearance**: **Dark** or **Light** theme.+- **Notifications**:+ - **In App Notifications** and **Desktop notifications** each let you+ choose **Always show notifications**, **Show while I'm elsewhere in+ Evenfire**, or **Show only when I'm away from Evenfire**.+ - **Channel fallback** chooses whether Telegram or Slack should get plugin+ notifications when the desktop app doesn't acknowledge them in time.+ - **Notification sound** sets the alert volume.+- **Plugin permissions**: see [Apps and Plugins](#apps-and-plugins).+- **Social channels**: appears only if your account has social channels+ available. It links to Profile UI to set them up.+- **Shortcuts**: the keyboard shortcut reference.+- **Information**: the app version, the External REST API and RPC proxy+ addresses with their versions and health, and whether an update is+ required. This is the first place to look when something seems off.++Environments aren't managed in Settings. Add and switch them from the+**Environment** selector on the sign-in screen.++## Troubleshooting++| You see | What it means / what to do |+| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| On sign-in: **Couldn't reach `<environment>`. A local Evenfire looks like it's running — switch to `<other>` and retry?** | The selected environment isn't responding, but one on this computer is. Choose **Switch to `<other>` & retry**, or pick the right environment from the **Environment** selector. |+| **Services Unavailable**, with `external-rest-api` or `rpc-proxy` marked unavailable | The app can't reach the server. Choose **Retry Health Check**. If it keeps failing, ask your admin whether the server is up. |+| **Desktop update required** | Your server needs a newer version of the app. **Download update** opens the release page. **More info** shows the version you have and the latest one. |+| **Desktop notifications are blocked by system permission.** (in **Settings → Notifications**) | Allow notifications for Evenfire in your operating system's settings. |+| The composer says **Agent degraded — fix the LLM Secret to resume.** | The agent's model credentials aren't working. An admin needs to fix the agent's LLM Secret. |+| **Connect `<server>` to continue** in a chat | Choose **Connect `<server>`**, or use **Authorize** on the Connectors page. |+| **Models unavailable** on the model chip | The model list couldn't load. Click the chip to try again. |+| **File access is not authorized** in EvenDrive | Choose **Retry file access**. If it still fails, sign in again or ask an admin. |+| **Session refresh failed: …** in an open app | Close the app and open it again. |+| **A message can carry at most 20 attachments.** (or a size message) | Remove some attachments, or split them across several messages. See [the limits above](#add-context-and-attach-files). |+| Something else looks wrong | Check **Settings → Information** for health status and versions, and share it with your admin. |++## Related++- [Desktop App](../surfaces/desktop-app.md): what the app is, how it's wired, how to package it+- [Desktop setup & updates](desktop-setup-and-updates.md): environments, invitations, update checks+- [Configure approvals](configure-approvals.md): which tool calls ask for approval+- [Connect an OAuth connector](connect-oauth-connector.md): the connector sign-in flow+- [Shared and global files](shared-and-global-files.md): the storage behind EvenDrive+- [Profile UI](../surfaces/profile-ui.md): account, password, and desktop setup in the browserdiff --git a/docs/llm-providers/README.md b/docs/llm-providers/README.mdindex 35b21c09a..219eb7b63 100644--- a/docs/llm-providers/README.md+++ b/docs/llm-providers/README.md@@ -119,14 +119,16 @@ authenticates with an `api-key` header instead of `Authorization: Bearer`, and| Grok subscription | `grok-subscription` | OAuth sign-in held by control-api, no Secret slot | `CONTROL_API_GROK_SUBSCRIPTION_ENABLED`, `GROK_LLM_PROXY_EXECUTION_ENABLED`, `WRC_GROK_SUBSCRIPTION_ENABLED` (recipes); mcp-host's flag is injected per Host |These providers use a subscription account instead of an API key. An admin-signs in from Control UI (**Secrets → LLM → Subscriptions**,+signs in from Control UI (**Secrets → LLM Subscriptions**,`/secrets/llm/subscriptions`); control-apikeeps the OAuth tokens, and model traffic goes through the in-cluster`codex-llm-proxy` / `grok-llm-proxy`. A Host selects a sign-in with`spec.model.connectionRef` and needs no `secretRef` when every target isthe same subscription provider. A Host may use at most one subscriptionprovider. They are **off in `deploy/base`** and switched on in the minikube-overlay. Wire-level details:+overlay. Setup guide:+[Use a ChatGPT or Grok subscription](../how-to/connect-llm-subscription.md).+Wire-level details:[Codex transport contract](../architecture/codex-subscription-transport-contract.md),[Grok transport contract](../architecture/grok-subscription-transport-contract.md).diff --git a/docs/llms.txt b/docs/llms.txtindex 78e8900dd..48ad80066 100644--- a/docs/llms.txt+++ b/docs/llms.txt@@ -36,6 +36,9 @@- Connect Telegram: how-to/connect-telegram.md- Connect Slack (app scopes, request URL, verify flow, approval buttons): how-to/connect-slack.md- Connect Microsoft Teams (Teams CLI registration, derived endpoint, single-tenant requirement, verify flow): how-to/connect-teams.md+- Use the Desktop App (chat, attachments, EvenDrive, shortcuts, deep links): how-to/use-the-desktop-app.md+- Configure guardrails (rules, installed hooks, built-ins): how-to/configure-guardrails.md+- Connect an OAuth connector (remote MCP servers, user authorization, connector credentials): how-to/connect-oauth-connector.md- 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@@ -49,6 +52,7 @@- LLM providers overview (the 24 providers, including the Codex and Grok subscription sign-ins, mental model, support matrix): llm-providers/README.md- Configure LLM providers — operator guide (credentials, Vertex/Bedrock/Azure, allowlist, session selector): deploy/llm-providers.md+- Use a ChatGPT (Codex) or Grok subscription instead of an API key: how-to/connect-llm-subscription.md- Add an LLM provider (data-only vs driver-based integration): llm-providers/adding-a-provider.md## Deploy & operatediff --git a/docs/surfaces/desktop-app.md b/docs/surfaces/desktop-app.mdindex e159e90a5..5d248a773 100644--- a/docs/surfaces/desktop-app.md+++ b/docs/surfaces/desktop-app.md@@ -15,10 +15,9 @@ platform, and the [Control UI](control-ui.md) for the admin side of that split.## The daily loop-1. **Log in.** Password login posts to `POST /api/v1/auth/password-login`;- Google login posts an already-issued `idToken` to- `POST /api/v1/auth/google` — the token has to already exist, since the- app does not drive a full OAuth browser redirect yet. Once a session is+1. **Log in.** The sign-in screen offers email and password, posted to+ `POST /api/v1/auth/password-login`. (The main process also exposes a+ Google `idToken` login IPC, but no screen uses it today.) Once a session isestablished, it is restored from the OS keychain via `keytar`, with alocal file fallback when no keychain is available.2. **Pick a team.** Team listing and switching read the access catalog:@@ -100,7 +99,8 @@ The app's top-level routes (`DESKTOP_ROUTES` in**Apps** (`sandbox-ui`), **Agents** (`agents`), **Connectors**(`mcp-servers`), **Plugins** (`workflows`), **EvenDrive** (`files`), a file`preview` view, and **Settings**. Inside an agent, the workspace has-Connectors, Members, Shared files and Activity sub-routes. Outside that+Connectors, Members and Activity sub-routes (plus **Agent Files** when the+app is built with `VITE_SHOW_AGENT_FILES_UI`). Outside thatauthenticated shell sit the first-run onboarding flow, the auth page (login),and `UnavailablePage`, shown instead of login when a required backenddependency is unreachable.@@ -117,7 +117,7 @@ Two screens worth calling out specifically:fourth top-level product.Below, the LeadForge recipe's own dashboard runs inside the Desktop App's- frame — the app's rail and its "Back to apps" bar are still in charge, and+ frame — the Desktop App's own navigation stays in charge, andeverything the plugin's UI loads comes through `rpc-proxy`. The plugin getsa real interface; it does not get a second client to install.@@ -240,8 +240,8 @@ above for why leaving it unset is silently wrong rather than loudly broken.## Limits-- The Google login path expects an already-issued `idToken`; there is no- full OAuth browser redirect yet.+- There is no Google or SSO sign-in screen; members sign in with email and+ password.- The activity stream never carries internal reasoning / chain-of-thoughtcontent, and it is read-only — message submission always goes through the`/messages` endpoint, never the stream.@@ -255,6 +255,7 @@ above for why leaving it unset is silently wrong rather than loudly broken.## Next+- [Use the Desktop App](../how-to/use-the-desktop-app.md) — the end-user guide: chat, attachments, EvenDrive, shortcuts, deep links- [UI Surfaces](README.md) — the persona matrix across all three consoles- [Control UI](control-ui.md) — the admin console- [Profile UI](profile-ui.md) — the invited member's front door