Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
evenfire Documentation
evenfire is a self-hostable platform for LLM agents that take real actions: multi-channel messaging, MCP tools, human-in-the-loop approvals, and deny-all-baseline networking — declared as Kubernetes CRDs.
Code and API group still use the historical name clerum (
clerum.io,CLERUM_*). Same project — code names.
Start at the root README.md for the product pitch and license.
Use this index for long-form docs. User and operator pages describe what
deploy/base and the minikube overlays ship; features that are off by default
say so. Design records are point-in-time and not maintained.
Get started
| Doc | Description |
|---|---|
| Quickstart | Full platform on minikube: set .env, one command |
| Registry quickstart | Connect, install, and publish as a self-hoster |
| Dev mode | Run mcp-host alone without Kubernetes (contributors; not platform security) |
| Learning path | Choose a path by role and goal |
| FAQ | Common questions and troubleshooting |
Concepts
| Doc | Description |
|---|---|
| Why evenfire | Problem, audience, design intent |
| When to use evenfire | Fit vs personal assistants / in-process frameworks (categories only) |
| A tool call, end to end | From a user request through approval to the artifact |
| Open core: self-host vs hosted | What's in this repo vs the managed evenfire hosted service |
| Code names | evenfire vs clerum |
| Architecture overview | Services, CRDs, message lifecycle, NetworkPolicy model |
| Platform topology | Namespaces, controller split, deny-all baseline |
| Non-MCP services | Namespace splitting and L0–L3 policy layers |
Surfaces (the UIs)
| Doc | Description |
|---|---|
| Surfaces index | Which UI is for whom, and what each may reach |
| Control UI | Admin console: usage, budgets, approvals, egress, marketplace, guardrails |
| Desktop App | End-user client: chat, live activity, approvals, artifacts; how to ship it |
| Profile UI | Member front door: invitation, password, desktop handoff |
How-to guides
| Doc | Description |
|---|---|
| Connect Telegram | Minikube env or CRD channel path |
| Connect Slack | Slack app scopes, request URL, conversation verification |
| Connect Microsoft Teams | Teams CLI bot registration, endpoint, conversation verify |
| Use the Desktop App | Daily use: chat, attachments, approvals, EvenDrive, shortcuts, deep links |
| Configure guardrails | Tool-call rules, installed guardrail hooks, built-ins |
| Connect an OAuth connector | Remote/OAuth MCP servers, Microsoft 365 (Entra ID), user auth, secrets |
| Configure approvals | Human-in-the-loop tool gates |
| Add an MCP server | Dev-mode JSON, CRD, or Control UI path |
| Desktop setup & updates | Environments, invitation setup, updates |
| Manage users and teams | Members, teams, roles, control admins, agent access |
| Member invitations on self-hosted | Hosted mode zero-config emails vs running your own service |
| Track usage & set budgets | Enable budgets, scope, block vs warn |
| Connect to the registry | Self-hosted registry connect flow |
| Publish a plugin | Publish under your org with an efrk_ key |
| Shared & global files | Team workspaces (SFS) and the brokered drive (EvenDrive / GFS) |
LLM providers
| Doc | Description |
|---|---|
| LLM providers overview | The 24 providers, mental model, support matrix, request flow, fallback |
| Configure LLM providers | Operator guide: credentials, Vertex/Bedrock/Azure, allowlist, selector |
| Use a ChatGPT or Grok subscription | Sign in with a subscription instead of an API key (off by default) |
| Add an LLM provider | Data-only vs driver-based integration paths |
Deploy & operate
| Doc | Description |
|---|---|
| Minikube full stack | In-depth reference for the local platform |
| Production notes | Checklist and in-repo deploy assets |
| WorkflowRecipes operations | Recipe ops, RBAC, debugging |
| Releases and upgrades | Versioning, release images, pinning a release, upgrade order |
| Monitoring and observability | Logs starter, metrics endpoints, health checks, what to alert on |
| Upgrade notes | |
| Workflow output PVC upgrade | Per-recipe output PVC ownership change |
| Plugin Workload SDK upgrade | promptBridge / clientNotifications rollout order and migration |
| Host PVC layout upgrade | Upgrading stateless Hosts from v0.10.x / v0.11.x |
| Runbooks | |
| GFS permission store | gfs_controller DB credential: provisioning, rotation, recovery |
| Password work ownership recovery | Recover the bcrypt work-bounding singleton |
| MCP secret rollback permits | Short-lived permits for the legacy MCP secret rollback path |
| GFS large-file downloads | GFS admission limits vs visual model input |
Reference
| Doc | Description |
|---|---|
| Configuration switches | Feature flags that differ between deploy/base and minikube, and where each service's variables are documented |
| Plugin UI SDK | window.clerum API for plugin apps embedded in the Desktop App |
| CRD index | All 9 clerum.io CRDs |
| Workflow SDK | @clerum/workflow-sdk — build custom workflow coordinator images |
| llms.txt | Machine-readable doc map for coding agents |
| Service READMEs | One-line map per component in the root README components list |
Architecture deep dives
Design-level explanations of specific subsystems. Read the overview first.
| Doc | Description |
|---|---|
| Diagrams | Excalidraw sources |
| Stateless agent invariants | Guardrails for the suspend/wake agent lifecycle |
| Host storage layout | Workspace PVC layout, merge init, database failures, rollback rule |
| HCC readiness flows | Probe vs data-path readiness in host-context-controller |
| Live entity-change semantics | Latest-state convergence contract for live UI updates |
| Governed tracing | Control-plane evidence of what agents, admins, controllers did |
| Administrative rate limits | Control API quotas and how the UIs handle throttling |
| GFS desktop operator parity | Initial Desktop identity as EvenDrive operator on self-hosted |
| Registry pull secrets: self-provisioning | How a self-hosted install provisions its registry image-pull Secret |
| Registry pull secrets: recipe workloads | Extending that pull Secret to WorkflowRecipe workloads |
| Codex subscription transport contract | Wire contract for the codex-subscription provider |
| Grok subscription transport contract | Wire contract and flags for grok-subscription |
| WorkflowRecipe naming | Generated resource-name rules |
Testing & contributor runbooks
Contributor-facing. Most assume a local development cluster and the lanes in
CONTRIBUTING.md.
| Doc | Description |
|---|---|
| E2E guide | Cluster E2E suites, approvals, desktop |
| Minikube T0/T1/T2 runbook | The validation-lane contract |
| Custom coordinator E2E gates | Gates for custom coordinator images |
| Desktop observation smoke test | Desktop surface smoke check |
| Control UI headful journeys | Optional Playwright QA recorder for Control UI |
| Desktop headful journeys | Optional Playwright QA recorder for the Desktop App |
| Codex subscription validation | Evidence lanes for codex-subscription |
| Grok subscription validation | Evidence lanes for grok-subscription image input |
| Workflow NetworkPolicy regressions | Ownership rules learned from workflow policy bugs |
| Stateless idle calibration | Measuring the stateless time-to-idle |
| Local measurements | Running benchmarks through the intake gate |
| CodeQL rate-limiting dispositions | Audited dispositions for js/missing-rate-limiting |
For coding agents
| Doc | Description |
|---|---|
| WorkflowRecipe guide | Authoring recipes, for agents |
| Shared frontend rules | Cross-app rules for the three frontend surfaces |
| Control UI rules | Control UI application-specific guidance |
| Profile UI rules | Profile UI application-specific guidance |
| Desktop renderer rules | Desktop renderer application guidance |
Design records
Point-in-time design notes and inventories, kept for context and not maintained as user docs: design/.
Community & trust
| Doc | Description |
|---|---|
| Contributing | Dev loop, PR rules |
| Security | Private vulnerability reporting |
| Claims guardrails | Never-overclaim rules for public docs |
| Governance | How the project is run |
| Code of conduct | Community standards |
| License | MPL-2.0 (open source) |
Finding things
| I want to… | Start at |
|---|---|
| Chat with a local agent | Quickstart |
| Understand why this exists | Why evenfire |
| Decide if evenfire fits my use case | When to use evenfire |
| Configure Host / Context / McpServer | CRD index |
| Pick or configure an LLM provider | LLM providers overview |
| Run the full stack locally | Minikube |
| Ship to a real cluster | Production notes |
| Upgrade an existing install | Releases and upgrades |
| Debug E2E | E2E guide |
| Feed docs to an LLM | llms.txt |
| Use the admin console | Control UI |
| Chat with an agent from the desktop | Desktop App |
Note: Contributor-local working artifacts live under
docs/superpowers/on each checkout. They are git-ignored and intentionally not part of the repo.