evenfire README

The project's README from github.com/evenfire-ai/evenfire. As one markdown file: README.md.

Evenfire

Build your company's intelligence layer, without losing control.

Where your team and AI agents work together — a complete, fully open-source platform, from a native desktop app to a secure, self-hosted backend. Bring your own model keys; every risky action waits for a human "yes."

License: MPL-2.0 CI GitHub release Status: Beta

Quick start · What is Evenfire · The platform · Why · Security · Providers · Deploy · Docs · Status · License

Control UI: usage dashboard with charts of token consumption per model over time

The Control UI's usage dashboard: token consumption per model, over time. Tour all three UIs →


Quick start

This quick start runs the whole platform on a local minikube cluster — the fastest way to try Evenfire on your workstation.

Stand up every service on minikube with one command, including a seeded agent named chatllm. On a fresh minimal install, setup consumes the first-run admin bootstrap before any login, creates the matching Desktop identity, and records the governed initial_setup GFS operator link atomically:

git clone https://github.com/evenfire-ai/evenfire.git && cd evenfire
cp .env.example .env
# edit .env: set ADMIN_PASSWORD (required, no default ships) and ONE LLM key
MINIKUBE_IMAGE_TAG=latest make minikube-setup   # see the note below on this override
make minikube-status                            # wait for every deployment READY

The seeded [email protected] Desktop account is therefore the initial GFS operator. Re-running setup is idempotent: it may log in to verify the existing active link, but it never recreates a revoked link or silently creates a second ordinary member. If the link is missing, setup stops with an actionable error.

Then run the UIs from your workstation and say hello to the chatllm agent:

make install-all && npm --prefix control-ui install
npm run ui              # Control UI + Profile UI + Desktop App

The full walkthrough (prerequisites, login, and the pure-API path) is in Get started on minikube.

Evenfire is meant to be run on a remote cluster — see Deploying to a remote cluster.


What is Evenfire

Evenfire is a complete platform for running LLM agents that take real actions on your infrastructure.

Agents in Evenfire can:

Every piece of the fleet — agents, connectors, channels, workflows, policies, plugins — is a Kubernetes custom resource, so your platform is version-controlled, reviewable configuration. You bring your own model keys, so prompts and data flow only to the provider you choose


The platform

Evenfire is not just an agent runtime. It is nine first-class capabilities, each backed by code in this repo and declared as configuration. Each row links to its deep dive.

Capability What you get Deep dive
Agents Real actions across Telegram / Email / Slack / desktop (shell_exec, HTTP, a real browser, files), plus memory and approval gates mcp-host
Console & client An admin Control UI console and an Electron Desktop App, plus a small Profile UI for invites surfaces
Connectors (MCP) Governed MCP servers with per-Context allowlists; stdio tools via the bridge; remote SaaS behind a pinned egress proxy mcp-servers
Workflows Declarative multi-workload WorkflowRecipes with a lifecycle: risk-based approval, shadow testing, rollback workflowrecipe
Plugins & registry Author, publish, and install connectors and recipes through a governed, trust-rated registry workflow-sdk
Teams & access Profiles, teams, roles (admin / inviter / member), invitations, and session → scoped-RPC token brokerage external-rest-api
Files Read-only team workspaces agents can draw on, plus a brokered, audited shared drive where every read and write is checked and logged gfs-controller
Cost & governance Token budgets per scope (block/warn), usage and LLM-price accounting, and a connector-image allowlist token budgets
Config as code The whole fleet as eight clerum.io (why that name?) CRDs: version-controlled, reviewable, GitOps-friendly crds

Why Evenfire


Security model

We never fully trust the model. It can be steered, misled, or simply wrong, so four layers constrain what it can do:

Report vulnerabilities privately: SECURITY.md.


Supported LLM providers

A broad, growing set of providers behind one interface, from frontier labs to local models. Keys live in a Kubernetes Secret you create (dev mode: a single environment variable; setup infers the matching provider).

Provider provider value Integration
OpenAI openai Native SDK
Anthropic claude Native SDK
Z.AI zai OpenAI-compatible
Bailian bailian OpenAI-compatible
Google Vertex AI vertex Native SDK
Amazon Bedrock bedrock Native SDK
OpenRouter openrouter OpenAI-compatible
Google Gemini gemini OpenAI-compatible
DeepSeek deepseek OpenAI-compatible
Groq groq OpenAI-compatible
Together AI together OpenAI-compatible
Fireworks AI fireworks OpenAI-compatible
Mistral AI mistral OpenAI-compatible
xAI (Grok) xai OpenAI-compatible
Cerebras cerebras OpenAI-compatible
DeepInfra deepinfra OpenAI-compatible
Perplexity perplexity OpenAI-compatible
Moonshot (Kimi) moonshot OpenAI-compatible
Nebius nebius OpenAI-compatible
Novita AI novita OpenAI-compatible
MiniMax minimax OpenAI-compatible
Azure OpenAI azure Light driver

Most providers are OpenAI-compatible and plug in as config with no custom code; only a few (claude, vertex, bedrock, azure) need a dedicated integration. Overview: docs/llm-providers/README.md · Configure: docs/deploy/llm-providers.md · Add one: docs/llm-providers/adding-a-provider.md · Details: mcp-host/README.md.


Deploying to a remote cluster

The quick start runs on local minikube for evaluation. Evenfire is meant to be run on a remote Kubernetes cluster — deploy the platform there with a NetworkPolicy-capable CNI (Calico or equivalent).

Build on the Kubernetes manifests in deploy/base and the kustomize deploy/overlays — the shipped minikube overlay is the reference to copy and adapt for your own cluster. Then follow the production deployment guide for the rollout order, signing/JWT keys, secrets, and the security non-negotiables.


Development and testing

Each service is an independent npm package. Run npm test in a package, or make test-unit-all after installing deps; make test-counts prints the live unit-test file and case totals: "is it real, is it tested" without a hardcoded number to drift. E2E suites run against minikube with Calico NetworkPolicies and the approval flow: docs/testing/e2e-guide.md. Contributor loop: CONTRIBUTING.md.


Docs and components

Start here

Doc For
docs/README.md Docs index
docs/get-started/learning-path.md Role-based path
docs/concepts/why-evenfire.md Product intent
docs/concepts/when-to-use-evenfire.md Fit by category
docs/faq.md FAQ & troubleshooting
ARCHITECTURE.md Architecture & data flow
docs/crds/README.md Config as code (the 8 CRDs)
docs/llms.txt Map for coding agents

Components: every deployable service has its own README (the deep dive):

Component Role
mcp-host Agent runtime: LLM loop, tools, approval gate
channel-reader Telegram / Email / Slack ingress
control-api Control plane: CRDs, secrets, token mint, usage
control-ui Admin dashboard
profile-ui End-user profile and invitation confirmation
desktop-app Electron + React desktop client
external-rest-api Auth, profiles, teams, RPC-token brokerage
rpc-proxy External JWT-gated gateway for desktop/tenant traffic
host-context-controller Operator: CRDs → Deployments + NetworkPolicies
workflow-recipes Operator: WorkflowRecipe lifecycle
gfs-controller Brokered GlobalFileSystem API + audit chain
workspace-files-controller SharedFileSystem write path
mcp-proxy Optional centralized MCP router
mcp-servers Connector catalog (MongoDB, Airtable, …)
stdio-bridge Sidecar: stdio MCP → StreamableHTTP
nginx-egress-proxy Pinned egress path for remote connectors
webhook-gateway Per-recipe webhook signature verifier
webhook-proxy Stateless public webhook router
workflow-approval-request-reader Inbound Telegram/Slack approval callbacks

Ops & platform directories:


Status

Evenfire is in beta and under active development. The whole platform runs end to end and comes up locally with one command, but some APIs and CRDs may still change before a 1.0 release; pin a release tag if you need stability.

The code uses the internal name clerum for the same project (clerum.io CRDs, CLERUM_* env vars, clerum-* packages); see code names.


Community and license

Evenfire is open source under the Mozilla Public License 2.0 (MPL-2.0), an OSI-approved, file-level copyleft license.

evenfire (evenfire-ai/evenfire)

Searching Database…

Что это?Evenfire — селф-хостед платформа для запуска LLM-агентов, которые выполняют реальные действия на вашей инфраструктуре: бэкенд на Kubernetes, админская Control UI и нативный десктоп-клиент на Electron, чтобы команда и ИИ-агенты работали вместе без потери контроля.
Это приложение для установки или платформа-бэкенд для развёртывания?И то и другое: бэкенд на Kubernetes, где агенты, коннекторы, воркфлоу и политики — всё это кастомные ресурсы Kubernetes, плюс нативное десктоп-приложение Electron+React, админ-панель Control UI и Profile UI, и все они общаются с одним и тем же селф-хостед кластером.
Как это запустить?Быстрый старт поднимает все сервисы на локальном кластере minikube одной командой, включая предустановленного агента «chatllm», с которым можно сразу поболтать; для реального использования те же манифесты Kubernetes разворачиваются на удалённом кластере с CNI, поддерживающим NetworkPolicy, например Calico.
Нужны ли мне свои API-ключи LLM?Да, у Evenfire нет встроенного доступа к моделям; вы предоставляете свои ключи для провайдеров вроде OpenAI, Anthropic, Gemini или DeepSeek (или локальной модели), они хранятся в Kubernetes Secret.
Готова ли платформа к продакшену?Evenfire официально в бете: вся платформа запускается локально от начала до конца одной командой, но некоторые API и CRD могут ещё измениться до релиза 1.0, так что для стабильности стоит зафиксировать конкретный релизный тег.
Проходят ли мои данные через серверы самой Evenfire?Нет. Поскольку вы используете свои ключи к моделям, промпты и файлы идут напрямую выбранному провайдеру, а если направить агента на селф-хостед или локальную модель, всё остаётся внутри вашего окружения.
Как Evenfire не даёт агенту натворить опасного?Рискованные действия — команды shell, исходящие HTTP-запросы, управление браузером — приостанавливаются и ждут подтверждения человека из канала, а агенты работают с сетью в режиме «запрещено всё», с токенами минимальных привилегий и колбэками с проверкой подписи.
Из каких чатов можно общаться с агентами?Агенты могут общаться через нативное десктоп-приложение, Telegram, Microsoft Teams и Slack, а вызывать инструменты — по Model Context Protocol.
Каких провайдеров LLM он поддерживает?Широкий и растущий список: OpenAI, Anthropic Claude, Google Gemini/Vertex AI, Amazon Bedrock, DeepSeek, Groq, Mistral и другие, причём большинство подключается как OpenAI-совместимая конфигурация без своего кода.
Что за агент «chatllm» из быстрого старта?Это предустановленный демо-агент, который создаётся автоматически при настройке, чтобы было с чем сразу поболтать на minikube и проверить, что платформа работает от начала до конца.
Size
77.6 MB
Stars
729
Age
3mo
Commits · 90 Days