# Evenfire runs LLM agents as Kubernetes resources

> Evenfire is a self-hosted platform for running LLM agents that take real actions on your own infrastructure, with MCP connectors, workflows, budget caps and approval gates, where every agent, connector, channel, workflow, policy and plugin is a Kubernetes custom resource. It is MPL-2.0 licensed, marked beta, and ships a minikube quick start.

**evenfire-ai/evenfire** — Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

- Repository: https://github.com/evenfire-ai/evenfire
- Website: https://www.evenfire.ai/
- Stars: 707 · Forks: 20
- Language: TypeScript
- License: MPL-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/evenfire-ai-evenfire

## Agents that act, with a human in the loop

Evenfire is described as an intelligence layer platform for running LLM agents that take real actions on your infrastructure, and the README frames it as a complete, fully open-source platform, from a native desktop app to a secure, self-hosted backend.

The list of what an agent can do is the clearest statement of scope. Agents can converse across the native desktop app, Telegram, Microsoft Teams and Slack. They can call tools over the Model Context Protocol. They can share teams, files and cost budgets, and they can compose multi-step workflows.

The part that decides whether you can let one near production is the guardrail list: approval thresholds, budget caps, network deny-rules, and tool-level scopes so risky actions automatically pause for human review. Combined with the header line about every risky action waiting for a human yes, the design assumption is that agents are given real capability and then fenced in.

You bring your own model keys, and the README is explicit that prompts and data flow only to the provider you choose. That is a different arrangement from a hosted agent service, and it is the reason the whole platform is deployable on your own cluster.

The status badge in the README says beta, and the licence is MPL-2.0 with a TRADEMARK.md file in the repository, so the code is open while the name is protected.

## Everything is a Kubernetes custom resource

The architectural decision that defines the project is stated in the README: every piece of the fleet, agents, connectors, channels, workflows, policies, plugins, is a Kubernetes custom resource, so your platform is version-controlled, reviewable configuration.

That is the whole pitch in one line, and it is a strong argument for anyone who has tried to run agents in production. An agent runtime where the agent's tools, its budget, its network access and its approval policy live in YAML you can diff is auditable in a way that a dashboard and a set of API keys are not. A pull request can change what an agent is allowed to do.

The capability table makes the same point from the feature side, and each row names the deep dive document in the repository. Agents get real actions across Telegram, Email, Slack and desktop, with shell_exec, HTTP, a real browser and files, plus memory and approval gates. Connectors are governed MCP servers with per-Context allowlists, stdio tools via the bridge, and remote SaaS behind a pinned egress proxy.

Workflows are declarative multi-workload WorkflowRecipes with a lifecycle covering risk-based approval, shadow testing and rollback. Files are read-only team workspaces plus a brokered, audited shared drive where every read and write is checked and logged. Teams and access cover profiles, teams, the roles admin, inviter and member, invitations, and a session to scoped-RPC token brokerage.

The repository layout backs up the claim. There are separate directories for mcp-host, mcp-servers, mcp-proxy, rpc-proxy, stdio-bridge, gfs-controller, host-context-controller, codex-llm-proxy, grok-llm-proxy, webhook-gateway, control-api, control-ui, profile-ui, desktop-app, channel-reader, nginx-egress-proxy, plus packages and deploy directories and a charts directory for Helm.

## The minikube quick start in four commands

The quick start runs the whole platform on a local minikube cluster, which the README calls the fastest way to try Evenfire on your workstation.

```bash
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 first two lines get the code and the environment file in place. The third line is the only manual edit, and the README is explicit that no default ADMIN_PASSWORD ships, so setup aborts in step one if it is unset. The third line brings up every service, including a seeded agent named chatllm, and the fourth line waits until every deployment is READY.

The setup step has some careful semantics worth reading before you run it. 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. The seeded admin@evenfire.local 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, and if the link is missing, setup stops with an actionable error.

Then the user interfaces, which run on your workstation rather than in the cluster:

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

The README notes that Evenfire is meant to be run on a remote cluster, with the minikube path presented as the way to try it first.

## The JWT chain that ties the surfaces together

The root Makefile opens with a comment block describing what it calls the JWT AUTH CHAIN, marked CRITICAL, and it is the most informative piece of the repository for anyone integrating a client.

The chain runs control-api issues RPC token to Desktop App, with iss set to control-api and aud set to rpc-proxy, and a TTL of 300 seconds. The comment is explicit about the audience: it is rpc-proxy, not mcp-host. The Desktop App then presents a Bearer rpc_token to rpc-proxy on port 8094, and rpc-proxy passes the same token through to chatllm on port 8080, where chatllm validates it with iss equal to control-api and aud equal to rpc-proxy.

The key requirement is spelled out too: all three keys must be the same RSA-4096 pair, covering rpc-proxy-secrets.RPC_PROXY_JWT_PUBLIC_KEY, mcp-host-config.CLERUM_AUTH_JWT_PUBLIC_KEY and jwt-signing-keys.CONTROL_API_RPC_JWT_PRIVATE_KEY on the private side. And the sequence to fix it is given: after make minikube-gen-keys, run make minikube-sync-auth-key to push the new public key into mcp-host-config and restart the affected pods.

A 300 second token lifetime with a fixed audience is a sensible design for a desktop client talking to a brokered RPC layer, and the fact that the Makefile documents it at the top rather than in a doc file is a hint about how much of this platform is understood by reading its source.

## The local docker-compose path, and its deliberate looseness

Before minikube there is a docker-compose.yml at the repository root, and it is worth reading because it shows the same services in a much simpler form.

```yaml
  mcp-host:
    build:
      context: ./mcp-host
      dockerfile: Dockerfile
    environment:
      CLERUM_DEV_MODE: "true"
      CLERUM_ENABLE_AUTH: "false"
      CLERUM_MODEL_PROVIDER: ${CLERUM_MODEL_PROVIDER:-openai}
      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
      CLAUDE_API_KEY: ${CLAUDE_API_KEY:-}
      ZAI_API_KEY: ${ZAI_API_KEY:-}
      BAILIAN_API_KEY: ${BAILIAN_API_KEY:-}
```

Note the two settings at the top of that block. CLERUM_DEV_MODE is true and CLERUM_ENABLE_AUTH is false, so the local compose path deliberately runs without authentication. That is fine for a laptop and it is exactly what you would not want in a deployment, and the file makes the difference explicit rather than hiding it.

The provider variables show the model choices the platform supports out of the box: OpenAI as the default, with Claude, ZAI and Alibaba Cloud Model Studio, also called Bailian, alongside it. The .env.example file repeats the same set with the console URLs for each key, plus the required ADMIN_PASSWORD, and notes that the remaining MCP and channel credentials are optional and only needed for those integrations.

The channel-reader service in the compose file is behind a profiles entry named telegram, and the comment above it says it wires Telegram or Slack or Email to mcp-host, that it requires a real bot token, and that you can omit the service if you only want the local HTTP surface. The mcp-host service itself is exposed on port 8080 and has a healthcheck against the v1/runtime/health endpoint.

One naming detail is worth flagging for anyone reading the repository. The root package.json is named clerum and private, and the environment variables use a CLERUM_ prefix throughout, even though the product is called Evenfire.

## Release pace, and what is still in flight

The release notes are unusually informative, because each tag carries its own summary.

v0.11.0, tagged 2026-10-12, is described as Extended MCP OAuth, file attachments, live GFS changes. v0.10.0 from 2026-09-28 covers EvenDrive, standardized Control editing, and a hardened LLM path. v0.9.0 from 2026-09-22 brought Grok Subscription and universal desktop tabs. The last push to the repository was on 2026-10-20, so the work is current.

Three minor versions in three weeks is a fast cadence for a platform of this size, and it has consequences. A component called Grok Subscription appearing in v0.9.0 and a grok-llm-proxy directory in the repository show that provider support is being added as a matter of course rather than treated as a one-off integration.

It also means the shape of the platform is still moving, and the beta badge in the README should be read alongside that. For an adopter this is the main risk: you are deploying something whose interfaces are being revised weekly, and the security model itself was tightened in v0.10.0 with a hardened LLM path.

The governance files are part of that picture. The repository carries GOVERNANCE.md, SECURITY.md, TRADEMARK.md, CLA.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, ARCHITECTURE.md, and both AGENTS.md and CLAUDE.md for coding agents, plus a .gitleaks.toml configuration and a skills-lock.json. The presence of a Contributor Licence Agreement alongside a company-led repository says something about who is expected to contribute and on what terms, and it is worth reading before you send a patch.

The project is described as a complete platform, and the repository layout supports that claim: separate control-api, control-ui, profile-ui and desktop-app surfaces, mcp-host, mcp-servers, mcp-proxy, rpc-proxy, stdio-bridge and webhook-gateway, gfs-controller and host-context-controller, channel-reader, a nginx-egress-proxy, monitoring and charts directories, and a docs tree with per-topic deep dives.

## Conclusion

Evenfire suits a team that wants agents to act on real systems while keeping the actions reviewable and version-controlled, since the whole fleet is expressed as Kubernetes custom resources and the dangerous steps pause for a human yes. It is the wrong tool if you want a library to call a model from your own application, because Evenfire is a platform you deploy, not a dependency you import, and the README still marks it beta. Before adopting it, clone the repository, copy .env.example to .env and set ADMIN_PASSWORD and one LLM key, then run make minikube-setup and make minikube-status to see whether the whole service set comes up on your workstation.

## FAQ

### How do I run Evenfire locally for the first time?

Clone the repository, copy .env.example to .env, set ADMIN_PASSWORD and one LLM key in it, then run MINIKUBE_IMAGE_TAG=latest make minikube-setup followed by make minikube-status. That brings up every service on a local minikube cluster including a seeded chatllm agent, and the UIs are then started with make install-all and npm run ui.

### What licence is Evenfire released under?

The README badge and the repository state MPL-2.0, and there is a TRADEMARK.md file alongside the LICENSE, so the code is open source while the name is protected. The repository also carries a CLA.md, a Contributor Licence Agreement.

### How does Evenfire keep agent actions under control?

Through guardrails configured as approval thresholds, budget caps, network deny-rules and tool-level scopes, so risky actions automatically pause for human review. Every agent, connector, channel, workflow, policy and plugin is a Kubernetes custom resource, so those settings are version-controlled and reviewable configuration rather than dashboard state.

### Which LLM providers does Evenfire support?

The .env.example file lists OpenAI, Anthropic Claude, ZAI and Alibaba Cloud Model Studio, also called Bailian, and the docker-compose configuration defaults CLERUM_MODEL_PROVIDER to openai. You bring your own keys, and the README states that prompts and data flow only to the provider you choose.

### How does the Desktop App authenticate against the platform?

The root Makefile documents the chain: control-api issues an RPC token with iss set to control-api, aud set to rpc-proxy and a TTL of 300 seconds, the Desktop App presents it as a Bearer token to rpc-proxy on port 8094, and rpc-proxy passes the same token through to chatllm on port 8080. All three components must share the same RSA-4096 key pair.

## Sources

- [evenfire-ai/evenfire on GitHub](https://github.com/evenfire-ai/evenfire)
- [License: MPL-2.0](https://github.com/evenfire-ai/evenfire/blob/main/LICENSE)
- [Project website](https://www.evenfire.ai/)
- [README](https://github.com/evenfire-ai/evenfire/blob/main/README.md)
- [Releases](https://github.com/evenfire-ai/evenfire/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/evenfire-ai-evenfire