Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs: address review findings on operating and contributing docs
Jose Gabriel Ramirez Encinasaac86c952bb1
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex e346b4a3a..a2929173f 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -5,7 +5,7 @@ Thanks for your interest! evenfire is **open source** under the## Set up-- **Node.js 24.** `.nvmrc` pins `24`, every service declares+- **Node.js 24.** `.nvmrc` pins `24`, most services declare`"node": ">=24"`, `desktop-app` declares `24.x`, and CI uses Node 24.- Install dependencies across the repo:@@ -13,8 +13,10 @@ Thanks for your interest! evenfire is **open source** under themake install-all```- This runs `npm install` at the root, then in every service in parallel, then- in `tests/e2e`. The root install's `postinstall` sets+ This runs `npm install` at the root, then in each directory listed in+ `SERVICES` in the Makefile, in parallel, then in `tests/e2e`. Directories not+ in that list, such as `control-ui`, `gfs-controller` and+ `workspace-files-controller`, need their own `npm install`. The root install's `postinstall` sets`git config core.hooksPath .githooks`, so the git hooks below are active fromthen on. `make install-git-hooks` does the same on its own.diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.mdindex 5b9a9dfe0..ffdf68bbc 100644--- a/docs/architecture/grok-subscription-transport-contract.md+++ b/docs/architecture/grok-subscription-transport-contract.md@@ -205,7 +205,7 @@ both, not a proven minimum. The manifest therefore sets`--max-old-space-size=768`, a 2048Mi limit and a 768Mi request, and`grok-llm-proxy/test/deployManifest.test.ts` requires the limit to be at least1.25 × the largest peak (`ceil(1481.6 × 1.25)` = 1852 MiB). The in-cluster peak-is not measured (keyper-labs/evenfire-infra#102). The heap cap is a resource+is not measured yet. The heap cap is a resourcechange only: the resident heap after GC at that load was 420.8 MiB, above the200 MiB target recorded for`BODY_STRUCTURE_LIMITS`, so lowering the resident set needs a code changediff --git a/docs/architecture/overview.md b/docs/architecture/overview.mdindex 07b0ce9d9..d887f134b 100644--- a/docs/architecture/overview.md+++ b/docs/architecture/overview.md@@ -533,9 +533,9 @@ a `Set<string>` so an unchanged hostRef triggers exactly one reconcile.**RBAC:** HCC's `host-context-controller-channels-runtime` Role grants`get/list/watch` on `communicationchannels.clerum.io` in the `channels`-namespace. **Applied out-of-band** via `make gcp-dev-bootstrap-rbac` /-`make gcp-prod-bootstrap-rbac` because the CD service account intentionally-cannot grant RBAC (see `deploy/scripts/post-deploy-sync.sh`).+namespace. **Applied out-of-band** with+[`deploy/scripts/bootstrap-rbac.sh`](../../deploy/scripts/bootstrap-rbac.sh),+because a deploy service account should not be able to grant RBAC.---diff --git a/docs/deploy/production.md b/docs/deploy/production.mdindex 8c97e548b..7cdb5620a 100644--- a/docs/deploy/production.md+++ b/docs/deploy/production.md@@ -111,7 +111,8 @@ certificates for these Services:| Slack, Teams, webhook triggers | `webhook-proxy` (`webhook-ingress`, 8095) | Inbound only if you use them. See [Slack](../how-to/connect-slack.md) and [Teams](../how-to/connect-teams.md). |**The NetworkPolicies decide which ingress works.** Base admits public traffic-to `control-ui`, `profile-ui`, `rpc-proxy` and `webhook-proxy` only from pods+to `control-ui`, `profile-ui`, `external-rest-api`, `rpc-proxy` and+`webhook-proxy` only from podslabeled `app: cloudflared` in a namespace named `ingress`. That matches theoptional Cloudflare Tunnel stack in [`deploy/base/ingress`](../../deploy/base/ingress),which `deploy/base/kustomization.yaml` deliberately does not include. To use it,@@ -120,8 +121,9 @@ tunnel credentials Secret yourself. To use any other ingress controller, eitherrun it so it matches those selectors or patch those NetworkPolicies in youroverlay.-Then point the platform at your public URLs. In base these default to-`127.0.0.1`/`localhost` values that only work with port-forwards:+Then point the platform at your public URLs. In base and the minikube configs+these are unset or `127.0.0.1`/`localhost` values that only work with+port-forwards; set them in your overlay:| Variable | Where || ------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |@@ -196,6 +198,7 @@ of copying minikube's choices.| `storageClassName` on `control-postgres-data` and `clerum-workflow-output` | unset | Patch, or rely on your default StorageClass. || `CONTEXT_MAPPER_HOST_IMAGE_PULL_SECRET` (HCC) | `clerum` | Name your pull Secret in `mcp-host`, or set `""` if none is needed (minikube sets `""`). || `CONTEXT_MAPPER_ENFORCE_IMAGE_ALLOWLIST` (HCC) | `"false"` (audit) | Set `"true"`, and narrow `CONTEXT_MAPPER_ALLOWED_IMAGE_PREFIXES` (base includes `clerum/`). |+| `CONTROL_API_ENFORCE_IMAGE_ALLOWLIST` (control-api) | `"false"` (audit) | Set `"true"` so control-api refuses non-allowlisted connector images up front, not only HCC at reconcile. |For a read-only check of API-server and DNS egress before you rely onenforcement, see [`deploy/scripts/np-enforce-preflight.sh`](../../deploy/scripts/np-enforce-preflight.sh).@@ -243,13 +246,17 @@ exact allowlist of kube-contexts they may touch.- Set `ADMIN_BOOTSTRAP_PASSWORD_HASH` (a bcrypt hash) before you run it.Otherwise it writes a placeholder hash.- It writes the `control-postgres` Secret with user `postgres` and password- `postgres`. Replace it before Postgres first starts.- - Base ships placeholder values for the `control-api-public-key` and- `clerum-wrc-public-key` ConfigMaps, and `mcp-host-config` must carry the- RPC public key as `CLERUM_AUTH_JWT_PUBLIC_KEY`. A later- `kubectl apply -k` resets anything your overlay still holds as a- placeholder, so put the real public keys in your overlay. (Minikube- re-runs its key script after every apply for this reason.)+ `postgres`. Replace it before Postgres first starts. A re-run resets that+ Secret to `postgres`/`postgres`, and the admin hash to the placeholder+ unless you set `ADMIN_BOOTSTRAP_PASSWORD_HASH` again.+ - `mcp-host-config` must carry the RPC public key as+ `CLERUM_AUTH_JWT_PUBLIC_KEY`. `gen-jwt-keys.sh` patches it only if the+ ConfigMap already exists, so after your first overlay apply (and after+ any apply that rewrites it) copy `RPC_PROXY_JWT_PUBLIC_KEY` from Secret+ `rpc-proxy-secrets` (namespace `rpc-proxy`) into it. Never keep the key+ from the minikube copy. `control-api-public-key` and+ `clerum-wrc-public-key` are not in base: `gen-jwt-keys.sh` creates them+ and `kubectl apply -k` leaves them alone.- `apply-inter-service-tokens.sh` creates any missing Secret and thenwrites with `kubectl patch`, so later `kubectl apply -k` runs do not wipethe tokens. It keeps existing values. Minikube runs it again after every@@ -328,8 +335,10 @@ runbooks are in [releases and upgrades](releases-and-upgrades.md#upgrade-notes):port beyond the NetworkPolicy-allowed edge services. The edge trust headersit accepts are forgeable by anyone who can reach the port.- Keep default-deny NetworkPolicies; only open (context, server) pairs you intend.-- Switch the connector-image allowlist to enforce- (`CONTEXT_MAPPER_ENFORCE_IMAGE_ALLOWLIST=true`).+- Switch both connector-image allowlists to enforce+ (`CONTEXT_MAPPER_ENFORCE_IMAGE_ALLOWLIST=true` for HCC and+ `CONTROL_API_ENFORCE_IMAGE_ALLOWLIST=true` for control-api), and narrow both+ allowed-prefix lists.- Custom workflow coordinator images are off by default(`WRC_ENABLE_CUSTOM_COORDINATOR_IMAGE=false`). If you turn them on, keep`WRC_REQUIRE_COORDINATOR_IMAGE_DIGEST=true` (the default), which requires adiff --git a/docs/deploy/releases-and-upgrades.md b/docs/deploy/releases-and-upgrades.mdindex fec52f429..738505b67 100644--- a/docs/deploy/releases-and-upgrades.md+++ b/docs/deploy/releases-and-upgrades.md@@ -109,12 +109,12 @@ private pipeline. That pipeline is not part of this repository.### What is fixed and what moves-| Tag | Moves? |-| --------------------- | -------------------------------------------------------------------------------------- |-| `:latest`, `:sha-<7>` | `:latest` moves on every `dev` build of that image. `:sha-<7>` names one build. |-| `:vX.Y.Z` | Written by the release workflow for that tag. Nothing in normal operation rewrites it. |-| `:stable` | Moves to the newest strict `vX.Y.Z` release. |-| `@sha256:…` digest | Never moves. Use a digest when you need a byte-for-byte guarantee. |+| Tag | Moves? |+| --------------------- | -------------------------------------------------------------------------------------------------- |+| `:latest`, `:sha-<7>` | `:latest` moves on every `dev` build of that image. `:sha-<7>` names one build. |+| `:vX.Y.Z` | Written by the release workflow for that tag. Nothing in normal operation rewrites it. |+| `:stable` | Moves to whichever strict `vX.Y.Z` tag was promoted last (a patch to an older line moves it back). |+| `@sha256:…` digest | Never moves. Use a digest when you need a byte-for-byte guarantee. |The release workflow has no guard that stops a second run from writing`:vX.Y.Z` again. If you need an image that cannot change, pin the digest.@@ -147,8 +147,9 @@ MINIKUBE_IMAGE_TAG=v0.9.0 make minikube-setup # an older release```On a branch where the release-prep commit has landed but the tag has not been-promoted yet, the pin names images that do not exist yet. That is why-[the quickstart](../get-started/quickstart.md) uses `MINIKUBE_IMAGE_TAG=latest`.+promoted yet, the pin names images that do not exist yet. In that window,+re-run with `MINIKUBE_IMAGE_TAG=latest`, as+[the quickstart](../get-started/quickstart.md) explains.To build every image from source instead, use `make minikube-setup-local`.See [minikube.md](minikube.md) for the full setup.@@ -179,7 +180,7 @@ from the same checkout as your images.The Desktop App version is the release version, and its GitHub release tag isthe same `vX.Y.Z` tag. There is no separate `desktop-app-<version>` tag.-The External REST API serves `GET /desktop/release` (authenticated). It returns+The External REST API serves `GET /api/v1/desktop/release` (authenticated). It returnsthe values in `releaseManifest.ts` plus `releaseTag` (`v<desktopVersion>`) and`releaseUrl`. `releaseUrl` is built from `EXTERNAL_REST_API_DESKTOP_RELEASE_BASE_URL`,which defaults to `https://github.com/evenfire-ai/evenfire/releases`. Point itdiff --git a/docs/faq.md b/docs/faq.mdindex 3ae7df1b7..4fcbdbc6e 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -48,7 +48,7 @@ Details (category-level, no product rankings):- The #1 cause: no real LLM API key in `.env`. With no key, setup gives theHost `openai/gpt-5.4-mini` with a placeholder key and warns that the agent- will not reply. Fix `.env`, then `make minikube-setup ARGS="--skip-build"`.+ will not reply. Fix `.env`, then `make minikube-setup REUSE_DB=true ARGS="--skip-build"`.- How setup picks the Host model: an explicit `CLERUM_MODEL_PROVIDER` wins(with `CLERUM_MODEL_NAME`, or that provider's default model). Without it,setup takes the provider of the first key present, in the orderdiff --git a/docs/get-started/dev-mode.md b/docs/get-started/dev-mode.mdindex a45cc1afc..330294889 100644--- a/docs/get-started/dev-mode.md+++ b/docs/get-started/dev-mode.md@@ -6,7 +6,10 @@ native tool, guardrails or an MCP server.> **Dev mode is not full platform security.** It turns off JWT verification> and runs without NetworkPolicies, CRDs, host-context-controller, control-api-> or the UIs. Do not expose a dev-mode process to a network you do not trust.+> or the UIs. mcp-host listens on all interfaces, and anyone who can reach the+> port can forge the edge headers and drive the agent, including the shell+> tool. Run it only on a machine and network you control; with Docker, publish+> the port on `127.0.0.1` only.> For the full platform, use the [Quickstart](quickstart.md).## Run mcp-host locally@@ -90,7 +93,8 @@ for the other routes.it, the approval resolver allows no approver, and `CLERUM_APPROVAL_TIMEOUT`defaults to `0` (never time out), so a tool that needs approval waitsforever. For local iteration, either set `CLERUM_APPROVAL_CONFIG` or turn- the gate off with `CLERUM_ENABLE_APPROVAL=false`. Decisions go to+ the gate off with `CLERUM_ENABLE_APPROVAL=false`. With the gate off, shell+ commands run without review; never do this on a reachable port. Decisions go to`POST /v1/runtime/approvals/approve` and `POST /v1/runtime/approvals/deny`,which need the same edge headers as messages. See[Configure approvals](../how-to/configure-approvals.md).@@ -129,7 +133,7 @@ shared packages from `packages/`:```bash# from the repository rootdocker build -f mcp-host/Dockerfile -t mcp-host-dev .-docker run --rm -p 8080:8080 \+docker run --rm -p 127.0.0.1:8080:8080 \-e CLERUM_DEV_MODE=true \-e CLERUM_ENABLE_AUTH=false \-e OPENAI_API_KEY=sk-... \diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.mdindex 77b1afb03..c2fd5ae0e 100644--- a/docs/get-started/quickstart.md+++ b/docs/get-started/quickstart.md@@ -110,8 +110,11 @@ Verify:make minikube-status # every deployment should show READY```-Useful re-runs: `make minikube-setup ARGS="--skip-build"` (redeploy in ~1 min) ·-`ARGS="--reset-db"` (fix postgres after a cold-start crash) ·+Useful re-runs (setup rebuilds the database by default, so keep it with+`REUSE_DB=true` on an existing cluster):+`make minikube-setup REUSE_DB=true ARGS="--skip-build"` (redeploy in ~1 min) ·+`ARGS="--reset-db"` with `CONTROL_DB_RESET_PVC_UID` (fix postgres after a+cold-start crash; see the troubleshooting table) ·`ARGS="--force-keys"` (regenerate the JWT chain) ·`ARGS="--seed-profile=e2e"` or `make minikube-setup-e2e` (adds the E2E fixtureset: test user, `e2e-*` recipes, demo MCP servers).@@ -184,7 +187,7 @@ curl -s -X POST "$RPC/api/v1/rpc/hosts/$HOST/approvals/approve" \1. Create a bot with [@BotFather](https://t.me/BotFather); get your numericuser id (e.g. via `@userinfobot`).2. Set `CLERUM_TELEGRAM_BOT_TOKEN` and `CLERUM_TELEGRAM_USER_ID` in `.env`.-3. Re-run `make minikube-setup ARGS="--skip-build"` and message your bot.+3. Re-run `make minikube-setup REUSE_DB=true ARGS="--skip-build"` and message your bot.Approval requests arrive on Telegram with inline **Approve / Deny** buttons.Details: [Connect Telegram](../how-to/connect-telegram.md).@@ -196,7 +199,7 @@ Details: [Connect Telegram](../how-to/connect-telegram.md).| Agent never replies | No real LLM key in `.env`; with several keys, set `CLERUM_MODEL_PROVIDER` explicitly (see step 1) || `minikube start` fails on memory | Raise Docker Desktop to ≥10 GB RAM / 6 CPUs — or, if you can't spare it, `MINIKUBE_MEMORY=9216 make minikube-setup` (stock Docker Desktop's ~9.9 GB is just under the 10 GB default) || Pods `Pending` early on | Calico is still coming up — wait, then `make minikube-status` |-| postgres CrashLoopBackOff after cold start | `make minikube-setup ARGS="--reset-db --skip-build"` |+| postgres CrashLoopBackOff after cold start | `CONTROL_DB_RESET_PVC_UID="$(kubectl --context clerum-test -n control-plane get pvc control-postgres-data -o jsonpath='{.metadata.uid}')" make minikube-setup ARGS="--reset-db --skip-build"` || Port-forwards die | Re-run `make minikube-pf-all` (it holds them open; Ctrl-C stops) |## Next stepsdiff --git a/docs/how-to/connect-telegram.md b/docs/how-to/connect-telegram.mdindex 9491afdd0..8cd8f753c 100644--- a/docs/how-to/connect-telegram.md+++ b/docs/how-to/connect-telegram.md@@ -17,7 +17,7 @@ CLERUM_TELEGRAM_USER_ID=<your-numeric-user-id>5. Re-apply secrets and redeploy:```bash-make minikube-setup ARGS="--skip-build"+make minikube-setup REUSE_DB=true ARGS="--skip-build"```6. Message the bot from the allowed user account.diff --git a/docs/operations/monitoring.md b/docs/operations/monitoring.mdindex 3c342e7f7..4a931dadd 100644--- a/docs/operations/monitoring.md+++ b/docs/operations/monitoring.md@@ -74,7 +74,8 @@ helm install grafana grafana/grafana -n monitoring \--set persistence.storageClassName=standardmake -C monitoring status-make -C monitoring port_forward_grafana # http://localhost:3000+# Control UI already uses localhost:3000 on minikube, so forward Grafana elsewhere:+kubectl port-forward -n monitoring svc/grafana 3001:80 # http://localhost:3001```The admin user is `admin`. The values file does not set a password. Setdiff --git a/monitoring/README.md b/monitoring/README.mdindex 674cf04e1..fc839ec5c 100644--- a/monitoring/README.md+++ b/monitoring/README.md@@ -19,6 +19,11 @@ Helm values and Grafana dashboard configs for the Clerum observability stack. Th## Setup+> **On minikube**, follow [Monitoring and observability](../docs/operations/monitoring.md#install-on-minikube)+> instead: it overrides the storage class and the 100 Gi Loki volume. That page+> also explains what this starter covers (logs only; no metrics scraping is+> shipped).+```bash# Add Grafana Helm repo and create namespacemake setup@@ -35,10 +40,6 @@ kubectl create configmap grafana-dashboards \make install_grafana```-On minikube, set the storage class to `standard` and reduce the 100 Gi Loki-volume in `loki/values.yaml` before installing. See-[Monitoring and observability](../docs/operations/monitoring.md) for what this-starter covers (logs only; no metrics scraping is shipped).## Makefile Targets