Skip to content

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.md
index 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 providers
Set `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).
## Security
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index 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 |
### Dependencies
diff --git a/docs/faq.md b/docs/faq.md
index 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.md
index 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):
```bash
OPENAI_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 steps
diff --git a/docs/llm-providers/README.md b/docs/llm-providers/README.md
index 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 allowlist
diff --git a/docs/testing/e2e-guide.md b/docs/testing/e2e-guide.md
index 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.sh
index 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_PASSWORD
CLERUM_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