Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs: address review findings on operating and contributing docs

Jose Gabriel Ramirez Encinasaac86c952bb1
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 the
make 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 from
then 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.md
index 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 least
1.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 resource
change only: the resident heap after GC at that load was 420.8 MiB, above the
200 MiB target recorded for
`BODY_STRUCTURE_LIMITS`, so lowering the resident set needs a code change
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index 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.md
index 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 pods
labeled `app: cloudflared` in a namespace named `ingress`. That matches the
optional 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, either
run it so it matches those selectors or patch those NetworkPolicies in your
overlay.
-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 on
enforcement, 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 then
writes with `kubectl patch`, so later `kubectl apply -k` runs do not wipe
the 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 headers
it 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 a
diff --git a/docs/deploy/releases-and-upgrades.md b/docs/deploy/releases-and-upgrades.md
index 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 is
the 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 returns
the 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 it
diff --git a/docs/faq.md b/docs/faq.md
index 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 the
Host `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 order
diff --git a/docs/get-started/dev-mode.md b/docs/get-started/dev-mode.md
index 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 waits
forever. 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 root
docker 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.md
index 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 fixture
set: 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 numeric
user 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 steps
diff --git a/docs/how-to/connect-telegram.md b/docs/how-to/connect-telegram.md
index 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.md
index 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=standard
make -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. Set
diff --git a/monitoring/README.md b/monitoring/README.md
index 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 namespace
make 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