Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs(minikube): state the Host model rule and the openai default
Alfredo Lopezcbbc7765d4a3
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 8d177bbcd..f2956da37 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -57,12 +57,12 @@ NetworkPolicy owned by whichever component is responsible for that selector.### Agent runtime — `mcp-host`, `mcp-server` (both deny-all)-| Service | Role |-| ----------------------------------------- | -------------------------------------------------------------------------------------- |-| [mcp-host](mcp-host/) | The agent: LLM loop, MCP tool calling, state machine, approval gate, queue |-| [mcp-proxy](mcp-proxy/) | Optional centralized MCP router (`MCP_PROXY_ENABLED`); discovers servers via HCC |-| [stdio-bridge](stdio-bridge/) | Sidecar translating stdio MCP transport to StreamableHTTP; injected by HCC |-| [nginx-egress-proxy](nginx-egress-proxy/) | Image only — the pinned egress path HCC deploys for remote (`spec.remote`) MCP servers |+| Service | Role |+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |+| [mcp-host](mcp-host/) | The agent: LLM loop, MCP tool calling, state machine, approval gate, queue |+| [mcp-proxy](mcp-proxy/) | Optional centralized MCP router (`MCP_PROXY_ENABLED`); discovers servers via HCC |+| [stdio-bridge](stdio-bridge/) | Sidecar translating stdio MCP transport to StreamableHTTP; injected by HCC |+| [nginx-egress-proxy](nginx-egress-proxy/) | Image only — the pinned egress path HCC deploys for remote (`spec.remote`) MCP servers || [mcp-servers](mcp-servers/) | Platform-packaged MCP servers — first-party (Airtable, web-search) plus upstream images (MongoDB, Playwright, …) |### Recipes & sandbox — `sandbox-recipes`, `sandbox-ui` (both deny-all)@@ -140,8 +140,11 @@ flowchart TB## Swapping LLM providersSet `CLERUM_MODEL_PROVIDER` to `openai | claude | zai | bailian` and supply the-matching API key. One interface, no code change. See-[mcp-host/README.md](mcp-host/README.md).+matching API key. One interface, no code change. `CLERUM_MODEL_NAME` picks a+model only together with `CLERUM_MODEL_PROVIDER`; minikube setup refuses it+alone and defaults to `openai/gpt-5.4-mini` when no key is set. See+[mcp-host/README.md](mcp-host/README.md) and+[docs/llm-providers/README.md §4.7](docs/llm-providers/README.md#47-local-minikube-make-minikube-setup).## Securitydiff --git a/docs/architecture/overview.md b/docs/architecture/overview.mdindex 1aa757d23..367762ed3 100644--- a/docs/architecture/overview.md+++ b/docs/architecture/overview.md@@ -724,7 +724,7 @@ interface LLMProvider {- API key: `BAILIAN_API_KEY` / Secret key `bailian-api-key`- Implementation: same data-driven `openaiCompatible.ts` provider as ZAI-**Provider selection**: Auto-detected from available API key (priority order: openai, claude, zai, bailian), or set explicitly via `CLERUM_MODEL_PROVIDER`.+**Provider selection**: Auto-detected from available API key (priority order: openai, claude, zai, bailian), or set explicitly via `CLERUM_MODEL_PROVIDER`. `CLERUM_MODEL_NAME` applies only together with `CLERUM_MODEL_PROVIDER`; minikube setup refuses it alone, defaults to `openai/gpt-5.4-mini` when no key is set, and checks the pair against `llm_allowed_models` before applying the Host (see [LLM providers §4.7](../llm-providers/README.md#47-local-minikube-make-minikube-setup)).### MCP Integration@@ -817,27 +817,27 @@ The HTTP response is held open until the agent finishes processing. The response### Configuration-| Variable | Default | Description |-| ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------- |-| `CLERUM_DEV_MODE` | `false` | Enable dev mode |-| `CLERUM_HOST_NAME` | - | Host CRD name (production, required) |-| `CLERUM_NAMESPACE` | `"default"` | Kubernetes namespace |-| `CLERUM_SERVER_PORT` | `8080` | HTTP server port |-| `CLERUM_CONTEXT_MAPPER_URL` | auto | Context-mapper service URL |-| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | `30000` | Poll interval (ms) |+| Variable | Default | Description |+| ------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `CLERUM_DEV_MODE` | `false` | Enable dev mode |+| `CLERUM_HOST_NAME` | - | Host CRD name (production, required) |+| `CLERUM_NAMESPACE` | `"default"` | Kubernetes namespace |+| `CLERUM_SERVER_PORT` | `8080` | HTTP server port |+| `CLERUM_CONTEXT_MAPPER_URL` | auto | Context-mapper service URL |+| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | `30000` | Poll interval (ms) || `HCC_AUTHORITY_MAX_STALENESS_MS` | `180000` | Max retained HCC authority while HCC is unreachable (ms); operator-tunable, hard-capped at 600000; must be greater than the poll interval in cluster mode (issue #425) |-| `CLERUM_MODEL_PROVIDER` | auto-detected | `"openai"`, `"claude"`, `"zai"`, or `"bailian"` |-| `CLERUM_MODEL_NAME` | provider default | Specific model name |-| `OPENAI_API_KEY` | - | OpenAI key (dev mode) |-| `CLAUDE_API_KEY` | - | Claude key (dev mode) |-| `ZAI_API_KEY` | - | ZAI/z.ai key (dev mode) |-| `BAILIAN_API_KEY` | - | Bailian/DashScope key (dev mode) |-| `CLERUM_HOST_CONFIG` | - | JSON host config (dev mode) |-| `CLERUM_MCP_SERVERS` | - | JSON MCP server array (dev mode) |-| `CLERUM_AGENT_TASK_DELAY` | `3` | Delay between tasks (ms) |-| `CLERUM_AGENT_MAX_TASK_DURATION` | `86400000` | Max active task duration, excluding approval waits (ms) |-| `CLERUM_AGENT_MAX_TOOL_CALLS` | `1000` | Max LLM/tool iterations per task, configured per Host process |-| `CLERUM_AGENT_MAX_QUEUE_SIZE` | `100` | Max pending queue size |+| `CLERUM_MODEL_PROVIDER` | auto-detected | `"openai"`, `"claude"`, `"zai"`, or `"bailian"` |+| `CLERUM_MODEL_NAME` | provider default | Specific model name; used only with `CLERUM_MODEL_PROVIDER` |+| `OPENAI_API_KEY` | - | OpenAI key (dev mode) |+| `CLAUDE_API_KEY` | - | Claude key (dev mode) |+| `ZAI_API_KEY` | - | ZAI/z.ai key (dev mode) |+| `BAILIAN_API_KEY` | - | Bailian/DashScope key (dev mode) |+| `CLERUM_HOST_CONFIG` | - | JSON host config (dev mode) |+| `CLERUM_MCP_SERVERS` | - | JSON MCP server array (dev mode) |+| `CLERUM_AGENT_TASK_DELAY` | `3` | Delay between tasks (ms) |+| `CLERUM_AGENT_MAX_TASK_DURATION` | `86400000` | Max active task duration, excluding approval waits (ms) |+| `CLERUM_AGENT_MAX_TOOL_CALLS` | `1000` | Max LLM/tool iterations per task, configured per Host process |+| `CLERUM_AGENT_MAX_QUEUE_SIZE` | `100` | Max pending queue size |### Dependenciesdiff --git a/docs/faq.md b/docs/faq.mdindex 668bc11f3..a20ec2c30 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -46,10 +46,21 @@ Details (category-level, no product rankings):### Setup finished but the agent never replies-- The #1 cause: no real LLM API key in `.env`. Setup infers- `CLERUM_MODEL_PROVIDER` when exactly one key is set and fails loudly when- several keys are set without an explicit provider. Fix `.env`, then- `make minikube-setup ARGS="--skip-build"`.+- 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"`.+- 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+ `OPENAI_API_KEY`, `CLAUDE_API_KEY`, `ZAI_API_KEY`, `BAILIAN_API_KEY`, and+ that provider's default model. Several keys do **not** stop setup: the+ first one in that order wins, so set `CLERUM_MODEL_PROVIDER` when that is+ not the provider you want.+- Setup stops (exit 1, before the Host is applied) when `CLERUM_MODEL_NAME` is+ set without `CLERUM_MODEL_PROVIDER`, or when the resulting pair is not an+ enabled row of the model allowlist (`HOST_MODEL_UNKNOWN`,+ `HOST_MODEL_DISABLED`, `HOST_MODEL_CHECK_FAILED`). See+ [LLM providers](llm-providers/README.md#47-local-minikube-make-minikube-setup).- `make minikube-status` — every deployment should show READY.- With `make minikube-pf-all` running:`curl -sS http://localhost:8080/v1/runtime/health`.diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.mdindex f934fecbd..d7d6758b3 100644--- a/docs/get-started/quickstart.md+++ b/docs/get-started/quickstart.md@@ -43,14 +43,18 @@ Then set **one** LLM key (setup infers the matching provider):```bashOPENAI_API_KEY=sk-...CLERUM_MODEL_PROVIDER=openai # optional with one key: openai | claude | zai | bailian-# CLERUM_MODEL_NAME=gpt-5.4-mini # optional model override (default follows the provider)+# CLERUM_MODEL_NAME=gpt-5.4-mini # optional override; only with CLERUM_MODEL_PROVIDER```-> ⚠️ **Provider selection:** with exactly **one** API key set, setup auto-infers-> `CLERUM_MODEL_PROVIDER` and logs the choice. With multiple keys, set it-> explicitly — setup fails with a clear error naming the keys instead of-> guessing. With no key at all, the seeded agent gets placeholder credentials-> and will not reply.+> ⚠️ **Provider selection:** without `CLERUM_MODEL_PROVIDER`, setup takes the+> first key present in the order `OPENAI_API_KEY`, `CLAUDE_API_KEY`,+> `ZAI_API_KEY`, `BAILIAN_API_KEY`, uses that provider's default model, and logs+> the choice. With several keys the first one in that order wins, so set+> `CLERUM_MODEL_PROVIDER` when you want another. `CLERUM_MODEL_NAME` without+> `CLERUM_MODEL_PROVIDER` stops setup with an error naming both, and so does a+> pair that is not enabled in the model allowlist. With no key at all, the+> seeded agent gets `openai/gpt-5.4-mini` with placeholder credentials and will+> not reply.## 2. Set up the cluster (one command)@@ -192,12 +196,12 @@ Details: [Connect Telegram](../how-to/connect-telegram.md).## Troubleshooting-| Symptom | Fix |-| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| 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 MINIKUBE_IMAGE_TAG=latest 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"` |+| Symptom | Fix |+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| 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 MINIKUBE_IMAGE_TAG=latest 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"` || Port-forwards die | Shared profile: re-run `make minikube-pf-all` (it holds them open; Ctrl-C stops). Branch-owned profile: `MINIKUBE_PROFILE=<owned-profile> make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf` (do not use `branch-profile-pf-health` as the lasting hold; do not replace it with `make minikube-pf-all-bg`) |## Next stepsdiff --git a/docs/llm-providers/README.md b/docs/llm-providers/README.mdindex 8165acdc5..be556c39f 100644--- a/docs/llm-providers/README.md+++ b/docs/llm-providers/README.md@@ -222,6 +222,30 @@ slots are all present and uses that provider's default model;> auto-select `bedrock`. Set `CLERUM_MODEL_PROVIDER` explicitly if that's not> what you want.+### 4.7 Local minikube (`make minikube-setup`)++`scripts/minikube/full-setup.sh` step 6f writes the `chatllm` Host's+`spec.model` from `.env`, by the rule in `scripts/minikube/host-model.sh`:++| `.env` | Host model |+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |+| `CLERUM_MODEL_PROVIDER` + `CLERUM_MODEL_NAME` | used as given |+| `CLERUM_MODEL_PROVIDER` only | that provider's default model (openai, claude, zai, bailian) |+| `CLERUM_MODEL_NAME` only | **refused** — setup exits 1 naming both variables |+| neither, one or more of the four keys | first key in the order `OPENAI_API_KEY`, `CLAUDE_API_KEY`, `ZAI_API_KEY`, `BAILIAN_API_KEY`, with its default model |+| neither, no key | `openai/gpt-5.4-mini`, with a warning that the agent will not reply |++The default models are the `defaultModel` values in+`mcp-host/src/llm/registryCore.ts`. Any other provider needs both variables.++Before applying the Host, setup checks the pair against `llm_allowed_models`+in the profile's control-postgres (after migrations) and exits 1 on+`HOST_MODEL_UNKNOWN` (no row), `HOST_MODEL_DISABLED` (row disabled) or+`HOST_MODEL_CHECK_FAILED` (the query could not run). A name without a provider+is refused because a model id belongs to one provider: pairing+`CLERUM_MODEL_NAME=glm-4.7` with whichever key is present produced+`openai/glm-4.7`, which no catalog serves.+---## 5. The model allowlistdiff --git a/docs/testing/e2e-guide.md b/docs/testing/e2e-guide.mdindex 3772a7996..63a28fd21 100644--- a/docs/testing/e2e-guide.md+++ b/docs/testing/e2e-guide.md@@ -19,12 +19,20 @@ From root `README.md` §Testing prerequisites:- **Node.js 24+** for unit tests- `.env` file at repo root with LLM API keys:- | Variable | Required For | How to Get |- | ----------------------- | ------------------------ | --------------------------------------- |- | `ZAI_API_KEY` | LLM tool-calling | https://z.ai |- | `OPENAI_API_KEY` | Alternative LLM provider | https://platform.openai.com/api-keys |- | `CLAUDE_API_KEY` | Alternative LLM provider | https://console.anthropic.com/ |- | `CLERUM_MODEL_PROVIDER` | Provider selection | `zai`, `openai`, `claude`, or `bailian` |+ | Variable | Required For | How to Get |+ | ----------------------- | ------------------------------------------------ | --------------------------------------- |+ | `OPENAI_API_KEY` | LLM tool-calling (first in auto-detection) | https://platform.openai.com/api-keys |+ | `CLAUDE_API_KEY` | Alternative LLM provider | https://console.anthropic.com/ |+ | `ZAI_API_KEY` | Alternative LLM provider | https://z.ai |+ | `CLERUM_MODEL_PROVIDER` | Provider selection | `openai`, `claude`, `zai`, or `bailian` |+ | `CLERUM_MODEL_NAME` | Model override; requires `CLERUM_MODEL_PROVIDER` | a model enabled in `llm_allowed_models` |++ With no provider set, setup takes the first key present in the order+ `OPENAI_API_KEY`, `CLAUDE_API_KEY`, `ZAI_API_KEY`, `BAILIAN_API_KEY`; with no+ key it uses `openai/gpt-5.4-mini` and the agent does not reply. Setup exits 1+ on `CLERUM_MODEL_NAME` without `CLERUM_MODEL_PROVIDER`, and on a pair that is+ not an enabled `llm_allowed_models` row+ ([LLM providers §4.7](../llm-providers/README.md#47-local-minikube-make-minikube-setup)).Copy `.env.example` to `.env` and fill in your keys. `.env` is gitignored.diff --git a/scripts/minikube/full-setup.sh b/scripts/minikube/full-setup.shindex 18c4c5058..001707faf 100755--- a/scripts/minikube/full-setup.sh+++ b/scripts/minikube/full-setup.sh@@ -237,6 +237,13 @@ Environment:CLERUM_EMAIL_USERNAME, CLERUM_EMAIL_PASSWORDCLERUM_MODEL_PROVIDER, CLERUM_MODEL_NAME+ Host model (scripts/minikube/host-model.sh): CLERUM_MODEL_PROVIDER wins, with+ CLERUM_MODEL_NAME or that provider's default. CLERUM_MODEL_NAME without+ CLERUM_MODEL_PROVIDER is refused. Otherwise the first key present, in the+ order above, picks the provider; with no key the Host gets+ openai/gpt-5.4-mini and the agent does not reply. The pair must be an+ enabled llm_allowed_models row, or setup exits 1 before applying the Host.+Examples:$(basename "$0") # Full setup from scratch$(basename "$0") --skip-build # Re-deploy without rebuilding images