Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
FAQ & troubleshooting
Product
What is evenfire?
A self-hostable platform for LLM agents that take real actions: multi-channel messaging, MCP tools, human-in-the-loop approvals, and default-deny networking, declared as Kubernetes CRDs. See Why evenfire.
Is it “open source”?
Yes — MPL-2.0 (Mozilla Public License 2.0), an OSI-approved, file-level copyleft license. You can use, modify, self-host, and build commercial products on it; changes to MPL-licensed files must stay under MPL when distributed, while larger works that combine with this code may carry their own licenses. See LICENSE.
Is multi-tenancy or hosting included?
No. This repo is the full single-tenant platform — one organization per deployment. Multi-tenant provisioning and the hosted registry control plane belong to the managed evenfire hosted service and are not open source. Member registration is similar — the invitation-signup backend itself is an extracted sibling service, not open source — but self-hosted deployments don't need to run it: hosted mode sends invitation emails via evenfire's shared registration hub with one env var. See Member invitations on self-hosted. What you self-host is complete and not feature-gated. See Open core: self-host vs hosted.
Why do I keep seeing “clerum”?
Internal code name. Public name is evenfire. See Code names.
How does evenfire compare to personal assistants or agent libraries?
Personal assistants optimize for chat surfaces and fast individual setup. In-process frameworks optimize for embedding agents in your application code. evenfire optimizes for governed action on infrastructure you control. Details (category-level, no product rankings): When to use evenfire.
Quickstart
Setup finished but the agent never replies
- The #1 cause: no real LLM API key in
.env. With no key, setup gives the Hostopenai/gpt-5.4-miniwith a placeholder key and warns that the agent will not reply. Fix.env, thenmake minikube-setup REUSE_DB=true ARGS="--skip-build". - How setup picks the Host model: an explicit
CLERUM_MODEL_PROVIDERwins (withCLERUM_MODEL_NAME, or that provider's default model). Without it, setup takes the provider of the first key present, in the orderOPENAI_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 setCLERUM_MODEL_PROVIDERwhen that is not the provider you want. - Setup stops (exit 1, before the Host is applied) when
CLERUM_MODEL_NAMEis set withoutCLERUM_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. make minikube-status— every deployment should show READY.- With
make minikube-pf-allrunning:curl -sS http://localhost:8080/v1/runtime/health.
The agent answers but has no MCP connectors
Expected for the seeded agent (native tools only). Declare an McpServer and
allowlist it in the Context: Add an MCP server.
Telegram bot ignores me
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.
Platform
Do I need Kubernetes?
Yes — evenfire is Kubernetes-native; make minikube-setup gives you the full
platform on a local cluster in minutes. (Contributors hacking on a single
service can run it standalone in dev mode — see that service's README.)
Which UI am I supposed to use?
Depends on who you are: Control UI if you administer the platform — admin login, governs the fleet (agents, connectors, budgets, approvals, the registry). Desktop App if you use agents — chat, approvals, artifacts. Profile UI is where an invited member lands to accept an invitation and set a password, on the way to installing the Desktop App. See the persona matrix: Which surface is for me?.
Do I need kubectl to run day-to-day?
No, for day-2 operations: agents, connectors, channels, and approvals all have
Control UI screens, and each one writes the same CRD you would otherwise
apply by hand. Budgets and the registry are Control UI screens too, but
they are not CRD-backed: budgets live in control-api's own Postgres, while
the registry catalog lives in a separate registry service that control-api
calls over HTTP (CLERUM_REGISTRY_URL). Neither is reachable with
kubectl apply. Yes, for install and for GitOps — bootstrapping the
platform is still make and kubectl. See
Quickstart and Production notes.
Can I ship the desktop app to my users?
Yes — electron-forge is already configured with makers for
dmg/squirrel/deb/rpm/zip, covering macOS, Windows, and Linux. See
Ship it to your users.
How many CRDs are there?
Nine under clerum.io: Host, Context, McpServer, LlmHook, CommunicationChannel,
WorkflowRecipe, WorkflowRecipePolicy, SharedFileSystem, GlobalFileSystem.
Index: CRDs.
Approvals never show up
- Host
spec.approval/CLERUM_ENABLE_APPROVALconfigured? - Approver ids match the channel identity?
- Desktop or channel-reader running and able to reach the runtime?
- See Configure approvals
NetworkPolicy blocks everything
That is the baseline (default deny). Connectivity is added per Context ↔
McpServer. Check host-context-controller reconciliation and
platform topology.
Contributing & security
How do I contribute?
CONTRIBUTING.md. PRs need tests; third-party MCP servers and recipes go to the registry, not this monorepo.
How do I report a vulnerability?
Privately — SECURITY.md. Do not open a public issue.
Still stuck?
- Learning path
- E2E guide for cluster validation
- Open a GitHub issue with logs redacted of secrets and tokens