Skip to content

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

TypeScript

docs: address second-round review on operate and contribute docs

Jose Gabriel Ramirez Encinasca6350d7ae7b
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a2929173f..abaddd658 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -152,8 +152,10 @@ for private reporting.
## CLA
-This project requires a signed Contributor License Agreement. Contributions
-may be used in the project's commercial / managed editions.
+The project plans to require a signed Contributor License Agreement, and
+contributions may be used in the project's commercial / managed editions.
-See [CLA.md](CLA.md) for the agreement and how to accept it (it is a draft,
-pending legal review).
+The agreement in [CLA.md](CLA.md) is a draft pending legal review and is not
+open for signing yet: no CLA bot runs on pull requests and there is no
+signature record. You cannot sign it today. Once it is final, CLA.md will say
+how to accept it.
diff --git a/desktop-app/README.md b/desktop-app/README.md
index 58b07dfd9..8875295ba 100644
--- a/desktop-app/README.md
+++ b/desktop-app/README.md
@@ -68,7 +68,7 @@ The app now auto-populates default RPC `hostRefs` from authorized agent names re
- `EXTERNAL_REST_API_BASE_URL` (default: `http://127.0.0.1:8091`)
- `RPC_PROXY_BASE_URL` (default: `http://127.0.0.1:8094`)
-- `MEMBER_REGISTRATION_SERVICE_BASE_URL` (no working default — falls back to the placeholder `https://example.com`, so set it explicitly; locally this is usually `http://127.0.0.1:8092`)
+- `MEMBER_REGISTRATION_SERVICE_BASE_URL` (default: `https://registration.evenfire.ai`, the hosted service — set it when you run your own; locally this is usually `http://127.0.0.1:8092`)
- `REQUEST_TIMEOUT_MS` (default: `60000`)
## Architecture
@@ -231,16 +231,16 @@ npm run test:e2e:all # Phase 1 + Phase 2
### Environment Configuration (`.env.e2e`)
-| Variable | Default | Description |
-| -------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `EXTERNAL_REST_API_BASE_URL` | `http://localhost:8091` | external-rest-api URL |
-| `RPC_PROXY_BASE_URL` | `http://localhost:8094` | rpc-proxy URL |
-| `MEMBER_REGISTRATION_SERVICE_BASE_URL` | `https://example.com` (placeholder — set it) | member-registration-service activation URL. There is no working default: unset, it silently points at `example.com`. |
-| `E2E_DEV_LOGIN_EMAIL` | `[email protected]` | Test-only login email (must have agent access) |
-| `E2E_DEV_LOGIN_EMAIL_2` | `[email protected]` | Second user, required by the cross-device session tests |
-| `E2E_DEV_LOGIN_NAME` | `Test User` | Test-only login display name |
-| `E2E_HOST_REF` | `chatllm` | Agent hostRef to test against |
-| `E2E_ALLOW_DEV_PORT_FORWARD` | unset (off) | Set to `1`/`true` to let the Playwright global-setup guard accept localhost port-forward URLs |
+| Variable | Default | Description |
+| -------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `EXTERNAL_REST_API_BASE_URL` | `http://localhost:8091` | external-rest-api URL |
+| `RPC_PROXY_BASE_URL` | `http://localhost:8094` | rpc-proxy URL |
+| `MEMBER_REGISTRATION_SERVICE_BASE_URL` | `https://registration.evenfire.ai` | member-registration-service activation URL. Unset or empty, it points at the hosted evenfire service; set it for your own. |
+| `E2E_DEV_LOGIN_EMAIL` | `[email protected]` | Test-only login email (must have agent access) |
+| `E2E_DEV_LOGIN_EMAIL_2` | `[email protected]` | Second user, required by the cross-device session tests |
+| `E2E_DEV_LOGIN_NAME` | `Test User` | Test-only login display name |
+| `E2E_HOST_REF` | `chatllm` | Agent hostRef to test against |
+| `E2E_ALLOW_DEV_PORT_FORWARD` | unset (off) | Set to `1`/`true` to let the Playwright global-setup guard accept localhost port-forward URLs |
## Notes
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index d887f134b..42e83fc36 100644
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -533,9 +533,11 @@ 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** with
-[`deploy/scripts/bootstrap-rbac.sh`](../../deploy/scripts/bootstrap-rbac.sh),
-because a deploy service account should not be able to grant RBAC.
+namespace. It lives in `deploy/base/channels/rbac.yaml`, so the overlay apply
+creates it. Where the CD identity is not allowed to patch Roles, apply it once
+out of band with
+[`deploy/scripts/bootstrap-rbac.sh`](../../deploy/scripts/bootstrap-rbac.sh)
+and an admin kubeconfig.
---
diff --git a/docs/deploy/minikube.md b/docs/deploy/minikube.md
index 74c7c889a..bdc35599c 100644
--- a/docs/deploy/minikube.md
+++ b/docs/deploy/minikube.md
@@ -98,11 +98,17 @@ otherwise surfaces at the migration gate as
`control_api_runtime relation privileges differ from the explicit access contract`.
On a fresh cluster (no volume, no reset state) there is nothing to delete and
setup continues. On a cluster that already has the volume, the reset refuses to
-run unless you name the exact volume it may delete:
+run unless you name the exact volume it may delete. This deletes all data in
+that volume, so check the UID yourself before passing it — do not read it inline:
```bash
-CONTROL_DB_RESET_PVC_UID="$(kubectl --context clerum-test -n control-plane \
- get pvc control-postgres-data -o jsonpath='{.metadata.uid}')" make minikube-setup
+# 1. Inspect the volume you are about to delete and note its UID
+kubectl --context clerum-test -n control-plane get pvc control-postgres-data \
+ -o custom-columns=NAME:.metadata.name,UID:.metadata.uid,CREATED:.metadata.creationTimestamp
+
+# 2. Paste that UID as a literal value
+CONTROL_DB_RESET_PVC_UID=<uid-from-previous-step> make minikube-setup
+
# or keep the data instead:
make minikube-setup REUSE_DB=true
```
@@ -678,10 +684,14 @@ make minikube-pf-desktop # Re-establish port forwards
## Restart With Database Wipe
```bash
-# Deletes the postgres PVC, recreates it, restarts control-api.
-# Name the exact PVC it may delete (or `none` if there is none):
-CONTROL_DB_RESET_PVC_UID="$(kubectl --context clerum-test -n control-plane \
- get pvc control-postgres-data -o jsonpath='{.metadata.uid}')" make minikube-db-reset
+# Destructive: deletes the postgres PVC and all its data, recreates it,
+# restarts control-api.
+# 1. Inspect the PVC it will delete and note its UID:
+kubectl --context clerum-test -n control-plane get pvc control-postgres-data \
+ -o custom-columns=NAME:.metadata.name,UID:.metadata.uid,CREATED:.metadata.creationTimestamp
+
+# 2. Paste that UID as a literal value (or `none` if there is no PVC):
+CONTROL_DB_RESET_PVC_UID=<uid-from-previous-step> make minikube-db-reset
# → Allows re-running the initial admin setup in Control UI
```
@@ -1137,11 +1147,18 @@ re-applies the manifests.
### Postgres CrashLoopBackOff (WAL corruption)
-Common after cold starts. The setup script detects and auto-fixes this, but you can also force a DB rebuild:
+Common after cold starts. The setup script detects an invalid checkpoint and
+stops; it does not repair the volume, because automatic destructive recovery is
+disabled. Fix it by rebuilding the DB, which deletes all data in the
+`control-postgres-data` volume:
```bash
-CONTROL_DB_RESET_PVC_UID="$(kubectl --context clerum-test -n control-plane \
- get pvc control-postgres-data -o jsonpath='{.metadata.uid}')" \
+# 1. Inspect the PVC you are about to delete and note its UID
+kubectl --context clerum-test -n control-plane get pvc control-postgres-data \
+ -o custom-columns=NAME:.metadata.name,UID:.metadata.uid,CREATED:.metadata.creationTimestamp
+
+# 2. Paste that UID as a literal value
+CONTROL_DB_RESET_PVC_UID=<uid-from-previous-step> \
make minikube-setup ARGS="--reset-db --skip-build"
```
diff --git a/docs/deploy/production.md b/docs/deploy/production.md
index 7cdb5620a..fcc215a41 100644
--- a/docs/deploy/production.md
+++ b/docs/deploy/production.md
@@ -193,7 +193,7 @@ of copying minikube's choices.
| Setting | Base value | What to do |
| ----------------------------------------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| API server `cidr` in `allow-k8s-api-egress-control-plane`, `-mcp-host`, `-channels` | `10.109.0.1/32` | Patch to your API server endpoint IP (`kubectl get endpoints kubernetes -n default`). The minikube template [`k8s-api-ip.yaml.template`](../../deploy/overlays/minikube/patches/k8s-api-ip.yaml.template) explains why this is an `ipBlock`. |
+| API server `cidr` in `allow-k8s-api-egress-control-plane`, `-mcp-host`, `-channels` | `10.109.0.1/32` | Patch to your API server endpoint IP (`kubectl --context "$KCTX" get endpoints kubernetes -n default`). The minikube template [`k8s-api-ip.yaml.template`](../../deploy/overlays/minikube/patches/k8s-api-ip.yaml.template) explains why this is an `ipBlock`. |
| `CONTEXT_MAPPER_HOST_WORKSPACE_STORAGE_CLASS` (HCC) | `do-block-storage-retain` | Set to a block StorageClass in your cluster. |
| `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 `""`). |
@@ -212,19 +212,28 @@ scripts under [`deploy/scripts`](../../deploy/scripts) take a `CONTEXT` and are
the ones to use elsewhere. Several of them also require `ALLOWED_CONTEXTS`, an
exact allowlist of kube-contexts they may touch.
+Pick one kube-context for the whole install and pass it explicitly to every
+command; do not rely on your kubeconfig's current context. The examples use
+`KCTX`, and the same value goes into each script's `CONTEXT`:
+
+```bash
+KCTX=<your-context>
+kubectl --context "$KCTX" cluster-info # confirm this is the cluster you mean
+```
+
1. **CRDs.**
```bash
- helm install clerum-crds ./charts/clerum-crds
+ helm --kube-context "$KCTX" install clerum-crds ./charts/clerum-crds
# After chart upgrades, re-apply the CRD YAML (Helm 3 does not upgrade crds/):
- kubectl apply -f ./charts/clerum-crds/crds/
+ kubectl --context "$KCTX" apply -f ./charts/clerum-crds/crds/
```
2. **Namespaces.** The key scripts write into existing namespaces, so create
them first:
```bash
- kubectl apply -f deploy/base/namespaces.yaml
+ kubectl --context "$KCTX" apply -f deploy/base/namespaces.yaml
```
Your overlay apply (step 4) adds the deny-all baselines, Roles and
@@ -234,7 +243,7 @@ exact allowlist of kube-contexts they may touch.
3. **Keys and secrets.** Run
[`deploy/scripts/gen-jwt-keys.sh`](../../deploy/scripts/gen-jwt-keys.sh)
- with `CONTEXT=<your-context>`. It creates the four RSA-4096 key pairs
+ with `CONTEXT="$KCTX"`. It creates the four RSA-4096 key pairs
(session, rpc, admin, wrc), the OAuth state HMAC and encryption key, the
Control UI CSRF secret, the prompt-history encryption key, and the
Secrets and public-key ConfigMaps that carry them. Then run
@@ -266,7 +275,7 @@ exact allowlist of kube-contexts they may touch.
- Secrets for LLM keys and channel credentials are separate; see
[LLM providers (operator guide)](llm-providers.md).
-4. **Apply your overlay** (`kubectl apply -k <your-overlay>`), with the
+4. **Apply your overlay** (`kubectl --context "$KCTX" apply -k <your-overlay>`), with the
ghcr component pinned to one release tag.
5. **Database migrations and roles.** Run
@@ -275,8 +284,11 @@ exact allowlist of kube-contexts they may touch.
[`provision-control-api-runtime-roles.sh`](../../deploy/scripts/provision-control-api-runtime-roles.sh).
If you use the Global File System, follow
[GFS permission-store credential lifecycle](gfs-permission-store.md)
- (`provision-gfs-db.sh`, `provision-gfs-runtime.sh`; production contexts
- need `--allow-prod`).
+ (`provision-gfs-db.sh`, `provision-gfs-runtime.sh`).
+ `provision-gfs-runtime.sh` refuses a non-dev context unless it is listed in
+ `ALLOWED_CONTEXTS` or you pass `--allow-prod`. `provision-gfs-db.sh` has no
+ such guard: it runs against whatever `CONTEXT` you give it, so check that
+ value before you run it.
6. **First admin.** control-api creates the bootstrap admin from
`CONTROL_API_ADMIN_BOOTSTRAP_USERNAME`, `CONTROL_API_ADMIN_BOOTSTRAP_EMAIL`
diff --git a/docs/deploy/releases-and-upgrades.md b/docs/deploy/releases-and-upgrades.md
index 738505b67..b7f8e8194 100644
--- a/docs/deploy/releases-and-upgrades.md
+++ b/docs/deploy/releases-and-upgrades.md
@@ -42,8 +42,10 @@ for what the hook does to your commits.
## How a release is made
-Images are built once, on the `dev` branch. A release never rebuilds them. It
-copies the exact images that `dev` already built to the release tag.
+Images are built by `build-publish.yml`: automatically on every push to `dev`,
+or when a maintainer runs that workflow by hand (`workflow_dispatch`, optionally
+with `build_all`). A release never rebuilds them. It copies images that were
+already built to the release tag.
```text
push to dev ──► build-publish.yml ──► ghcr.io/evenfire-ai/<image>:sha-<7> and :latest
@@ -206,7 +208,8 @@ Read the notes for every release you skip over, not only the target release.
2. **Apply the CRDs first.**
```bash
- kubectl apply -f ./charts/clerum-crds/crds/
+ KCTX=<your-context> # the cluster you are upgrading; never rely on the current context
+ kubectl --context "$KCTX" apply -f ./charts/clerum-crds/crds/
```
`helm upgrade` does not update files in a chart's `crds/` directory, so you
diff --git a/docs/faq.md b/docs/faq.md
index 4fcbdbc6e..363e664af 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -72,9 +72,11 @@ allowlist it in the Context: [Add an MCP server](how-to/add-mcp-server.md).
### Telegram bot ignores me
-Your numeric user id must be allowlisted
-(`CLERUM_TELEGRAM_USER_ID` in `.env`, or CRD `userIds`). Usernames alone are
-not enough. See [Connect Telegram](how-to/connect-telegram.md).
+The sender must be allowed on the channel: the access list of a channel
+created in the Control UI's External Channels page, or the numeric Telegram
+user ids in CRD `userIds` (usernames alone are not enough). On minikube,
+`.env` Telegram variables do not configure the channel; create it in the
+Control UI. See [Connect Telegram](how-to/connect-telegram.md).
## Platform
diff --git a/docs/get-started/dev-mode.md b/docs/get-started/dev-mode.md
index da7861cc5..5d0a4d6f2 100644
--- a/docs/get-started/dev-mode.md
+++ b/docs/get-started/dev-mode.md
@@ -17,6 +17,13 @@ native tool, guardrails or an MCP server.
You need Node.js 24 and an API key for one
[supported provider](../llm-providers/README.md).
+mcp-host has no setting to bind only to localhost, and with
+`CLERUM_ENABLE_AUTH=false` any client that reaches port `8080` can send the
+edge headers, approve its own shell commands and run them. Before you start it
+this way, make sure no other machine can reach that port (a host firewall rule,
+or a network you control). Otherwise use [Run it in Docker](#run-it-in-docker),
+which publishes the port on `127.0.0.1` only.
+
```bash
cd mcp-host
npm ci
@@ -144,4 +151,5 @@ docker run --rm -p 127.0.0.1:8080:8080 \
The root `docker-compose.yml` declares the same dev-mode settings, plus an
optional channel-reader under the `telegram` profile. Its mcp-host build does
not work as written: it uses `context: ./mcp-host`, so the Dockerfile cannot
-find `packages/`. Use the commands above instead.
+find `packages/`. It also publishes `8080:8080` on all interfaces with auth
+off. Use the commands above instead.
diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md
index c2fd5ae0e..3e188f533 100644
--- a/docs/get-started/quickstart.md
+++ b/docs/get-started/quickstart.md
@@ -79,7 +79,7 @@ CRDs → JWT signing keys → secrets from `.env` → service images pulled from
`ghcr.io/evenfire-ai` → deploy → readiness wait with auto-recovery → seed →
verify.
-**You do not build images.** The 23 service images are published for
+**You do not build images.** The 25 service images are published for
`linux/amd64` and `linux/arm64`, so an Apple Silicon Mac pulls a native image
instead of compiling anything. MCP servers are not loaded into the cluster at
all — they are installed on demand from the evenfire registry.
@@ -184,10 +184,12 @@ curl -s -X POST "$RPC/api/v1/rpc/hosts/$HOST/approvals/approve" \
## 5. Optional: chat from Telegram
-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 REUSE_DB=true ARGS="--skip-build"` and message your bot.
+1. Create a bot with [@BotFather](https://t.me/BotFather) and copy its token.
+2. In the Control UI, open **External Channels** → **Create**, pick your Host
+ and the Telegram provider, enter the bot handle and token, and grant access
+ to your user.
+3. Message your bot. (Setting the Telegram variables in `.env` and re-running
+ setup does not enable Telegram on minikube.)
Approval requests arrive on Telegram with inline **Approve / Deny** buttons.
Details: [Connect Telegram](../how-to/connect-telegram.md).
@@ -199,7 +201,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 | `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"` |
+| postgres CrashLoopBackOff after cold start | Rebuild the DB — this deletes all its data. First print and check the volume's UID: `kubectl --context clerum-test -n control-plane get pvc control-postgres-data -o jsonpath='{.metadata.uid}'`. Then paste it: `CONTROL_DB_RESET_PVC_UID=<uid-from-previous-step> make minikube-setup ARGS="--reset-db --skip-build"` ([details](../deploy/minikube.md#postgres-crashloopbackoff-wal-corruption)) |
| 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 8cd8f753c..2d4e0cfcd 100644
--- a/docs/how-to/connect-telegram.md
+++ b/docs/how-to/connect-telegram.md
@@ -6,21 +6,18 @@ Reach an evenfire agent from Telegram.
1. Complete the [Quickstart](../get-started/quickstart.md) so the platform runs.
2. Create a bot via [@BotFather](https://t.me/BotFather); copy the bot token.
-3. Find your numeric Telegram **user id** (not username), e.g. via `@userinfobot`.
-4. Set in `.env`:
-
-```bash
-CLERUM_TELEGRAM_BOT_TOKEN=<bot-token>
-CLERUM_TELEGRAM_USER_ID=<your-numeric-user-id>
-```
-
-5. Re-apply secrets and redeploy:
-
-```bash
-make minikube-setup REUSE_DB=true ARGS="--skip-build"
-```
-
-6. Message the bot from the allowed user account.
+3. In the Control UI, open **External Channels** (`/external-channels`) →
+ **Create**, pick your Host and the Telegram provider, enter the bot handle,
+ paste the bot token as the write-only credential, and grant access to the
+ users who may use it. See
+ [In the Control UI](#in-the-control-ui) below.
+4. Message the bot from the allowed user account.
+
+Putting `CLERUM_TELEGRAM_BOT_TOKEN` / `CLERUM_TELEGRAM_USER_ID` in `.env` and
+re-running `make minikube-setup` does **not** enable Telegram: setup no longer
+writes channel credentials from `.env`, and the default minikube
+`CommunicationChannel` declares no Telegram entry. channel-reader reads those
+variables only in its standalone dev mode.
`channel-reader` polls Telegram and forwards allowed senders to `mcp-host`.
Users not in the allowlist are dropped.
@@ -58,7 +55,7 @@ API server rejects the resource without them.
## In the Control UI
-External Channels → `/communication-channels` → **Create** builds the same
+External Channels → `/external-channels` → **Create** builds the same
`CommunicationChannel` resource as the CRD path above: pick the host, the
Telegram provider, add the bot token as a write-only credential, and grant
access to specific users/teams — writing `spec.access.users` /
diff --git a/docs/operations/monitoring.md b/docs/operations/monitoring.md
index 1c8efd3a9..d600f4081 100644
--- a/docs/operations/monitoring.md
+++ b/docs/operations/monitoring.md
@@ -53,35 +53,51 @@ clusters want. Override both at install time.
The dashboard ConfigMap must exist before Grafana starts, because
`grafana/values.yaml` mounts the `grafana-dashboards` ConfigMap.
+Every command below names the target cluster explicitly. Set `KCTX` to your
+minikube profile (`clerum-test` by default) and check it before you run
+anything:
+
```bash
+KCTX=clerum-test
+kubectl --context "$KCTX" get nodes # confirm this is the cluster you mean
+
# Helm repo + monitoring namespace
-make -C monitoring setup
+helm repo add grafana https://grafana.github.io/helm-charts
+helm repo update
+kubectl --context "$KCTX" apply -f monitoring/namespace.yaml
# Dashboard ConfigMap (before Grafana)
-kubectl create configmap grafana-dashboards \
+kubectl --context "$KCTX" create configmap grafana-dashboards \
--from-file=monitoring/dashboards/loki-grafana-dashboard.json \
-n monitoring
# Loki + Promtail, with a minikube storage class and a smaller volume
-helm install loki grafana/loki-stack --version 2.9.10 -n monitoring \
+helm --kube-context "$KCTX" install loki grafana/loki-stack --version 2.9.10 \
+ -n monitoring \
-f monitoring/loki/values.yaml \
--set loki.persistence.storageClassName=standard \
--set loki.persistence.size=10Gi
# Grafana
-helm install grafana grafana/grafana -n monitoring \
+helm --kube-context "$KCTX" install grafana grafana/grafana -n monitoring \
-f monitoring/grafana/values.yaml \
--set persistence.storageClassName=standard
-make -C monitoring status
+kubectl --context "$KCTX" get pods,daemonset,pvc -n monitoring
# Control UI already uses localhost:3000 on minikube, so forward Grafana elsewhere:
-kubectl port-forward -n monitoring svc/grafana 3001:80 # then open localhost:3001
+kubectl --context "$KCTX" port-forward -n monitoring svc/grafana 3001:80 # then open localhost:3001
```
The admin user is `admin`. The values file does not set a password. Set
`adminPassword` with `--set` or an existing Secret, or read the one the chart
-generates. On a cluster whose StorageClass matches the values files, the plain
-`make -C monitoring install_loki` and `install_grafana` targets work as-is.
+generates. On a cluster whose StorageClass matches the values files, the same
+`helm --kube-context` commands work without the `--set` overrides.
+
+The targets in `monitoring/Makefile` (`setup`, `install_*`, `upgrade_*`,
+`uninstall_*`, `status`, `port_forward_grafana`) take no context: they run
+`kubectl` and `helm` against your kubeconfig's **current** context. Use them
+only after `kubectl config current-context` shows the intended cluster; the
+explicit commands above are the safer default.
## Logs
@@ -91,11 +107,11 @@ picks them up. The format differs by service:
| Service | Format | Level variable |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------- |
| control-api | Pino JSON, `svc: control-api`, ISO timestamps, token paths removed | `LOG_LEVEL` |
-| workspace-files-controller | Pino and Pino HTTP JSON | |
-| codex-llm-proxy, grok-llm-proxy | Pino JSON | |
+| workspace-files-controller | Pino and Pino HTTP JSON | `LOG_LEVEL` |
+| codex-llm-proxy, grok-llm-proxy | Pino JSON | `LOG_LEVEL` |
| mcp-host | JSON lines (`timestamp`, `level`, `component`, `msg`), sensitive keys redacted | `LOG_LEVEL` |
| host-context-controller | JSON lines from its own logger, sensitive keys redacted | `LOG_LEVEL` |
-| workflow-recipes (controller and coordinator), workflow-approval-request-reader | JSON lines from their own loggers | |
+| workflow-recipes (controller and coordinator), workflow-approval-request-reader | JSON lines from their own loggers | `LOG_LEVEL` |
Other services may still print plain text. Don't assume every line is JSON.
The repository logging standard is in [CLAUDE.md](../../CLAUDE.md) under
diff --git a/docs/surfaces/desktop-app.md b/docs/surfaces/desktop-app.md
index ac4f199f3..1f898b367 100644
--- a/docs/surfaces/desktop-app.md
+++ b/docs/surfaces/desktop-app.md
@@ -202,8 +202,8 @@ Six `npm` scripts in `desktop-app/package.json` drive the makers, each running
`electron-forge make --platform=<platform> --arch=<arch>`. Packaging runs
`npm run build` first through the forge `prePackage` hook (set
`EVENFIRE_SKIP_PACKAGE_BUILD=1` to reuse an existing build). `desktop-app/Makefile`
-has no packaging targets — only install, build, dev, start, clean, and
-port-forward helpers — so use the scripts directly:
+has no packaging targets — only install, build, dev, start, clean,
+reinstall, and port-forward helpers — so use the scripts directly:
| Script | Platform | Arch | Makers |
| -------------------- | -------- | ----- | --------------------- |
@@ -215,10 +215,11 @@ port-forward helpers — so use the scripts directly:
| `make:linux:arm64` | linux | arm64 | zip, deb, rpm |
Output lands in `desktop-app/out/` (git-ignored). Run the macOS scripts on a
-macOS host: signing, notarization, and the adaptive-icon step (`xcrun actool`)
-are all gated on the **build host** being macOS. The adaptive-icon
-step is best-effort and falls back to the static icon unless
-`EVENFIRE_REQUIRE_ADAPTIVE_ICONS=1`.
+macOS host. Signing and notarization run only when the **build host** is macOS
+(and `ENABLE_APPLE_CODESIGN=1`). The adaptive-icon step (`xcrun actool`) runs
+for every **darwin target**, whatever the host, and needs `xcrun`, which exists
+only on macOS. It is best-effort: on failure it falls back to the static icon,
+unless `EVENFIRE_REQUIRE_ADAPTIVE_ICONS=1` makes the failure stop the build.
The package is built with ASAR integrity validation, `OnlyLoadAppFromAsar`, and
the `RunAsNode`, `NODE_OPTIONS`, and inspector-argument fuses turned off.
@@ -279,7 +280,10 @@ installers. The user-facing flow is in
You ship **one** packaged app, not a build per customer. A packaged build does
**not** read `EXTERNAL_REST_API_BASE_URL` or `RPC_PROXY_BASE_URL` from the
environment — those apply only to unpackaged dev runs, since
-`desktop-app/src/config.ts` gates them behind `!app.isPackaged`. Instead, each
+`desktop-app/src/config.ts` gates them behind `!app.isPackaged`. (The one
+exception is a packaged build launched with `--evenfire-desktop-dev-package`
+whose two URLs are the localhost defaults; it is for local packaging tests.)
+Instead, each
user points the installed app at whatever instance they want — your hosted
service, a teammate's, or local `make`-forwarded services — from the app's own
**Environment** screen: name it, paste the External REST API URL, Save. The RPC
@@ -290,9 +294,9 @@ config file. Adding and switching environments and the invitation setup path
are covered in [Desktop setup & updates](../how-to/desktop-setup-and-updates.md).
Two variables **do** apply to a packaged build, read from the environment or
-the bundled `.env.prod`: `MEMBER_REGISTRATION_SERVICE_BASE_URL` — which has
-**no working default**, so left unset it silently falls back to the placeholder
-`https://example.com` — and `REQUEST_TIMEOUT_MS`.
+the bundled `.env.prod`: `MEMBER_REGISTRATION_SERVICE_BASE_URL` — left unset
+(or empty) it falls back to `https://registration.evenfire.ai`, the hosted
+evenfire service, so set it when you run your own — and `REQUEST_TIMEOUT_MS`.
## The `member-registration-service` gap
diff --git a/monitoring/README.md b/monitoring/README.md
index fc839ec5c..ebf2ca512 100644
--- a/monitoring/README.md
+++ b/monitoring/README.md
@@ -32,7 +32,7 @@ make setup
make install_loki
# Create the dashboards ConfigMap first: Grafana's values mount it
-kubectl create configmap grafana-dashboards \
+kubectl --context <your-context> create configmap grafana-dashboards \
--from-file=dashboards/loki-grafana-dashboard.json \
-n monitoring
@@ -43,6 +43,12 @@ make install_grafana
## Makefile Targets
+These targets pass no `--context` / `--kube-context`: they run `kubectl` and
+`helm` against your kubeconfig's **current** context. Check
+`kubectl config current-context` before you run any of them, or use the
+explicit commands in
+[docs/operations/monitoring.md](../docs/operations/monitoring.md#install-on-minikube).
+
| Target | Description |
|--------|-------------|
| `setup` | Add Grafana Helm repo + create namespace |
@@ -72,7 +78,7 @@ The `grafana/values.yaml` configures:
The setup steps above create the `grafana-dashboards` ConfigMap that Grafana's values reference. To recreate it after editing the dashboard:
```bash
-kubectl create configmap grafana-dashboards \
+kubectl --context <your-context> create configmap grafana-dashboards \
--from-file=dashboards/loki-grafana-dashboard.json \
-n monitoring
```
@@ -81,6 +87,10 @@ kubectl create configmap grafana-dashboards \
```bash
make port_forward_grafana
-# Open http://localhost:3000
+# Open localhost:3000
# Default user: admin (password set via secret or Helm override)
```
+
+On minikube the Control UI already uses local port 3000. Forward Grafana to
+another port instead:
+`kubectl --context <your-context> port-forward -n monitoring svc/grafana 3001:80`.