Skip to content

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

TypeScript
19.1 KB
Raw Blame

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.