EDDI

E.D.D.I — Multi-Agent Orchestration Middleware for Conversational AI

E.D.D.I (Enhanced Dialog Driven Interface) is a production-grade, config-driven multi-agent orchestration middleware for conversational AI. It coordinates users, AI agents, and business systems through intelligent routing, persistent memory, and API orchestration — without writing code.

Built with Java 25 and Quarkus. Ships as a Red Hat-certified Docker image with the Manager dashboard and Chat UI built in. Selected as a UNIDO Trusted Partner for Industrial AI. Native support for MCP (Model Context Protocol), A2A (Agent-to-Agent), the OpenAI Chat Completions API, Slack, OpenAPI, and OAuth 2.0.

Website · Documentation · License: Apache 2.0

📑 Table of Contents

• 🏁 Quick Start
• 💡 Why EDDI?
• 📸 See It In Action
• ✨ Features
• 📖 Documentation
• 📋 Compliance & Privacy
• 🏗️ Development
  • Prerequisites
  • Quarkus Dev Mode
  • Maven Command Reference
  • Build & Docker
  • Kubernetes
• 🤝 Contributing
• 🔒 Security
• 📜 Code of Conduct

🏁 Quick Start

The fastest way to get EDDI running is the one-command installer. It sets up EDDI + your choice of database via Docker Compose and points you at the dashboard, where the Platform Operator (or the form-based agent wizard) creates your first AI agent for you.

Linux / macOS / WSL2:

curl -fsSL https://raw.githubusercontent.com/labsai/EDDI/main/install.sh | bash

Windows (PowerShell):

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/labsai/EDDI/main/install.ps1" -OutFile "install.ps1"
Unblock-File .\install.ps1
.\install.ps1

Requires Docker. The wizard auto-generates a unique vault encryption key for secret management.

Everything is served from one port: http://localhost:7070 opens a chooser between the Manager (/manage, the admin dashboard) and the Workforce workspace (/workforce, group conversations), and the standalone chat UI is at /chat. See Getting Started.

bash install.sh --defaults                 # All defaults, no prompts
bash install.sh --db=postgres --with-auth  # PostgreSQL + Keycloak
bash install.sh --full                     # Everything enabled (PostgreSQL + auth + monitoring)
bash install.sh --local                    # Build Docker image from local source
bash install.sh --eddi-version=6.5.0       # Pin a release (image and compose files from its tag)
bash install.sh --dry-run                  # Show the image tag and the git ref the files come from

.\install.ps1 -Defaults                    # All defaults, no prompts
.\install.ps1 -Database postgres -WithAuth # PostgreSQL + Keycloak
.\install.ps1 -Full                        # Everything enabled
.\install.ps1 -Local                       # Build Docker image from local source (run from a repo checkout, after .\mvnw.cmd package -DskipTests)
.\install.ps1 -DryRun                      # Show what would be done

./mvnw package -DskipTests    # Build the Java app
bash install.sh --local        # Build Docker image + start containers

🔄 Updating

The installer creates an eddi CLI wrapper that makes updating easy:

eddi update

This pulls the latest Docker image from the registry and restarts the containers. It works even when the same tag (e.g. latest) was re-published — Docker always checks the remote digest for changes.

Upgrading across releases? Read the upgrade guide first: Upgrading from 6.4 lists what an existing deployment must change, because several defaults now fail closed (a Keycloak realm imported from 6.1–6.4 needs a repair that re-running the installer applies and eddi update does not). A database that comes from EDDI 5 starts with Upgrading from 5.x.

eddi command not found? The CLI lives at ~/.eddi/eddi (Linux/macOS) or ~/.eddi/eddi.cmd (Windows). Either restart your terminal so the PATH takes effect, or use the full path:

# Linux / macOS
~/.eddi/eddi update

# Windows (PowerShell)
& "$HOME\.eddi\eddi.cmd" update

cd ~/.eddi
docker compose --env-file .env -f docker-compose.yml pull
docker compose --env-file .env -f docker-compose.yml up -d

🐳 Docker Compose (Manual)

If you prefer manual control over Docker Compose:

# Default (EDDI + MongoDB)
docker compose up

# PostgreSQL instead of MongoDB — a complete stack, so it is NOT layered on
# docker-compose.yml (an overlay cannot un-declare the base's mongodb service).
# The database password has no default; keep the value stable across runs
# (install.sh --db=postgres generates one into .env for you)
POSTGRES_PASSWORD=$(openssl rand -base64 24) docker compose -f docker-compose.postgres-only.yml up

# With Keycloak authentication. No realm account ships a password (see the
# header of docker-compose.auth.yml, or let install.sh --with-auth set one)
docker compose -f docker-compose.yml -f docker-compose.auth.yml up

# With Prometheus + Grafana monitoring
docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up

# With a local LLM — Ollama on the same Docker network, reachable as
# http://ollama:11434 (no host.docker.internal needed)
docker compose -f docker-compose.yml -f docker-compose.ollama.yml up -d

# The same local LLM, on the host's NVIDIA GPUs — layered on the Ollama overlay
# above, never instead of it (all it adds is `gpus: all`)
docker compose -f docker-compose.yml -f docker-compose.ollama.yml \
  -f docker-compose.ollama-nvidia.yml up -d

# Auth + monitoring + NATS together (overlays stack in any combination)
docker compose -f docker-compose.yml -f docker-compose.auth.yml \
  -f docker-compose.monitoring.yml -f docker-compose.nats.yml up

# A cluster: three EDDI replicas behind a round-robin load balancer, a
# three-node NATS JetStream cluster and MongoDB — a whole stack, run on its own
EDDI_VAULT_MASTER_KEY=$(openssl rand -base64 24) MONGO_PASSWORD=$(openssl rand -base64 24) NATS_PASSWORD=$(openssl rand -base64 24) \
  docker compose -f docker-compose.cluster.yml up -d

Available compose overlays: docker-compose.auth.yml (Keycloak), docker-compose.monitoring.yml (Prometheus+Grafana), docker-compose.nats.yml (cluster mode with one replica and one NATS server), docker-compose.ollama.yml (local LLM; add docker-compose.ollama-nvidia.yml on top for NVIDIA GPU access), docker-compose.chroma.yml (vector store), docker-compose.mcp-sidecar.yml (reach a stdio-only MCP server through a bridge sidecar — read the MCP Client guide first), docker-compose.local.yml (build from source). docker-compose.postgres-only.yml is a complete standalone stack rather than an overlay — use it on its own, not with -f docker-compose.yml; so is docker-compose.openwebui.yml, a runnable Open WebUI demo of the OpenAI-compatible API, and docker-compose.cluster.yml, the multi-replica stack above (see Clustering).

The compose files publish EDDI (and Keycloak) on 127.0.0.1 only. To reach them from another host, set EDDI_BIND=0.0.0.0 (and KEYCLOAK_BIND for Keycloak) in .env — with authentication on.

The Ollama overlay pulls llama3.2:3b on first start and keeps models in a named volume; override with OLLAMA_PULL_MODEL=qwen3:4b, or set it empty to skip the pull. It also sets EDDI_OLLAMA_DEFAULT_BASE_URL, so the agent wizard and the setup API pre-fill a base URL that resolves from inside the container — the one thing that trips up every first local-LLM agent, because localhost there is the container, not the host.

docker-compose.ollama-nvidia.yml adds GPU access to that Ollama and needs two things of the host, neither of which it degrades gracefully without: Docker Compose 2.30.0 or newer, which is where the gpus service attribute was introduced — older versions fail on it, so check docker compose version — and the NVIDIA Container Toolkit configured as a Docker runtime. gpus: all is a device request: with no GPU driver registered, the daemon cannot satisfy it and the container fails to start (could not select device driver "" with capabilities: [[gpu]]) rather than quietly falling back to the CPU. If you want Ollama on the CPU, leave this overlay off.

docker pull labsai/eddi    # Pull latest from Docker Hub

→ hub.docker.com/r/labsai/eddi

💡 Why EDDI?

Most multi-agent frameworks (LangGraph, CrewAI, AutoGen) are Python/Node libraries — great for prototyping, hard to govern in production. EDDI approaches from the opposite direction: a deterministic engine built to safely govern non-deterministic AI.

“The engine is strict so the AI can be creative.” — Project Philosophy

📸 See It In Action

📊 Dashboard Platform overview with active agents, workflows, quick actions, and recent conversations	🤖 Agent Fleet All deployed agents at a glance with status, descriptions, and one-click chat
💬 Live Conversation Real-time conversation with visible actions, step timing, and tool calls	🗣️ Multi-Agent Debate Peer Review with phased discussion: Opinion → Critique → Revision → Synthesis
🛡️ Secrets Vault Envelope-encrypted secrets with rotation tracking, checksums, and per-agent access control	💰 Tenant Quotas Rate limits, cost budgets, and live usage monitoring per tenant

More screenshots: LLM Config, Logs, User Memory, Schedules, Agent Detail

⚡ LLM Task Configuration System prompt, model parameters, cascading, RAG, context window, and budget settings	📋 Real-Time Logs Live log stream with per-call cost tracking, token counts, warnings, and errors
🧠 Persistent User Memory Cross-session memory with categorized entries, visibility scoping, and conflict detection	⏰ Scheduled Execution Cron jobs and heartbeats with fire history, retry logic, and dead-letter tracking
🔧 Agent Detail Full agent config: environments, workflows, A2A, security, capabilities, and memory policy

✨ Features

🤖 Multi-Agent Orchestration

• 🔀 Intelligent Routing — Direct conversations to different agents based on context, rules, and intent
• 🗣️ Group Conversations — Multi-agent debates with 7 built-in discussion styles: Round Table, Peer Review, Devil’s Advocate, Delphi, Debate, Task Force, and Negotiation
• 🔄 Follow-up & Continue — After a group discussion completes, follow up with any specific member agent or continue all phases with a new question — agents retain full context across rounds
• 💬 Slack Integration — Deploy agents to Slack channels and run multi-agent debates directly in threads
• 🪆 Nested Groups — Compose groups of groups for tournament brackets, red-team vs blue-team, and panel reviews
• 🤖 Dynamic Agents — Create, recruit, and delegate to new agents at runtime during group discussions with configurable guardrails
• 🗳️ Group Voting — VOTE phases collect explicit ballots (majority or approval, weighted, quorum-gated) and record a decision with the full tally, the raw ballots, and the losing side’s dissents
• 📋 Shared Artifacts — A blackboard members co-edit through tools, with compare-and-set concurrency and declarative JSON-Schema, regex, or max-length validators — never an LLM merge
• 🧑‍🤝‍🧑 Humans as Members — A person can hold a seat in the group: their turn pauses the discussion until they answer, or the configured timeout policy resolves it
• 🎚️ Facilitator — An optional facilitator agent is briefed at checkpoints and picks one move from a config-enumerated list (end, extend, call a vote, recruit, escalate) — bounded adaptation, never free-form orchestration
• 🤝 Negotiation — Typed two-party bargaining: positions → proposals → a quoted concession ledger → signed acceptances, with arbitration skipped once agreement is reached
• 🎯 Bid-Based Assignment — Contract-Net-lite task auctions: eligible members bid blind in parallel, highest confidence wins, with deterministic tie-break and fallback to role assignment
• 🎓 Team Memory — A RETRO phase distils lessons into team-owned group memory, so they surface in every member’s later discussions — institutional knowledge that compounds run over run
• 🏢 Standing Teams — A persistent workspace per group: a backlog that survives between discussions, cron cadences that pull from it, cross-run retry of unverified work, and running team metrics
• 📦 Preset Group Templates — Five packaged, validated group configs (research pod, editorial team, ops task force, decision board, negotiation table) — instantiate by assigning agents to named roles, not by hand-writing phases
• 📊 Discussion Overview — The Manager and the Workforce board render a running discussion as a phase rail, a members × phases matrix, and a roster of one-line member stances, updated live (details)
• 👥 Managed Conversations — Intent-based auto-routing with one conversation per user per intent (details)
• 🎯 Capability Matching — Discover and route to agents by skill, confidence score, and custom attributes
• 🧙 Platform Operator — Meta-agent that reads and operates the deployment — including creating other agents — with every write behind a human approval gate (how it works)
• 🔁 Agent Version Following — Running conversations move to a newer agent version only when its author saved it as compatible; every other save is a breaking change, and the Manager previews what a deployment does to live conversations (details)

🧠 LLM Provider Support (19 Providers)

• 🔀 Multi-Model Cascading — Start with cheap/fast models, escalate to powerful ones based on confidence (details)
• 📋 JSON Response Mode — jsonResponseFormat policy (auto | on | off) negotiates structured JSON output across all execution paths with provider-aware rules
• 🔧 Tool Calling — Native function/tool calling across all providers that support it
• 🗄️ Tool Result Caching — Per-tool cache scoping (GLOBAL, USER, CONVERSATION) to avoid redundant calls; fail-safe to USER on misconfiguration

🔗 Standards & Interoperability

EDDI implements open standards — not proprietary APIs:

💭 Memory & Context Management

• 💾 Persistent User Memory — Agents remember facts, preferences, and context across conversations via structured key-value entries with visibility scoping (self, group, global)
• 🧠 LLM Memory Tools — Built-in tools agents can call to read, write, and search their own persistent memory; guardrails keep the model to its own self memories unless the agent allows more
• 💤 Dream Consolidation — Background memory maintenance: stale entry pruning, contradiction detection, and fact summarization (inspired by Anthropic’s research on background memory consolidation)
• 🪟 Token-Aware Windowing — Intelligent context packing with model-specific tokenizer support and anchored opening steps
• 📝 Rolling Summary — Incremental LLM-powered summarization of older turns with a Conversation Recall Tool for drill-back into compressed history
• 🔧 Property Extraction — Config-driven slot-filling with longTerm / conversation / step scoping, plus secret for values that go straight into the vault — EDDI’s importance extraction mechanism
• 🛡️ Memory Policy (Commit Flags) — Strict write discipline marks failed task output as uncommitted (hidden from LLM context) and injects concise error digests for graceful degradation
• 🧹 Tool Context Ceiling — maxToolContextTokens caps tool output within a single turn (default 60k tokens), evicting oldest tool exchanges to prevent provider context-window errors while preserving tool-call pairing
• 🔄 Conversation State — Full history with undo/redo support

📚 RAG (Retrieval-Augmented Generation)

• 📦 8 Embedding Providers — OpenAI, Azure OpenAI, Ollama, Mistral, Bedrock, Cohere, Google Gemini, Vertex AI — queries and documents are embedded asymmetrically where the model supports it
• 🗄️ 6 Vector Stores — pgvector, Chroma, In-Memory, MongoDB Atlas, Elasticsearch, Qdrant
• 🕷️ Web Crawler Sources — A knowledge base can crawl a website itself: robots-aware, sitemap-driven, bounded by depth, page count and time budget, with deleted pages tombstoned on later runs (details)
• 📄 File Uploads — Upload PDF, Word, Excel, PowerPoint, CSV, HTML, Markdown and text files to a knowledge base; the content, not the file name, decides the format
• ⏱️ Scheduled Ingestion — Each source runs on its own cron or on demand, with preview, purge and a run history of counters and errors — all editable in the Manager’s knowledge-base editor
• 🌐 httpCall RAG — Zero-infrastructure RAG via any search API (BM25, Elasticsearch, custom)
• 📥 REST Ingestion API — Async document ingestion with status tracking and in-place replacement of an earlier version

🛠️ Built-In AI Agent Tools

📎 Multimodal Attachments

• 📤 3 Input Paths — URL reference, base64 inline, or file upload (POST /conversations/{id}/attachments with multipart/form-data)
• 🗄️ DB-Agnostic Storage — GridFS (MongoDB) or bytea (PostgreSQL) via IAttachmentStore SPI with grant-based access control and per-tenant quotas
• 📄 Hybrid PDF Extraction — PDFs are auto-extracted to text (shared AttachmentTextExtractor) and forwarded as inline context to any LLM, not just vision models
• 🔍 readAttachment Tool — Agents can recall attachments from earlier turns in multi-turn conversations
• 🧠 Model Capability Gating — ModelCapabilityService routes images to vision-capable LLMs and falls back to text metadata for others
• 🔀 Content-Type Routing — contentTypeMatcher behavior rule condition routes image/*, application/pdf, etc. to different workflows
• 👥 Group Parity — Attachments fan out with grant injection so group member agents can access the original user’s files
• 🗑️ GDPR Cleanup — deleteByConversation() cascades to attachment storage when conversations are erased

⏰ Scheduled Execution & Heartbeats

• 🫀 Heartbeat Triggers — Periodic agent wake-ups at configurable intervals for proactive behavior (inspired by OpenClaw’s heartbeat architecture)
• ⏲️ Cron Scheduling — Standard cron expressions for timed agent execution
• 🔄 Conversation Strategies — persistent (reuse same conversation across fires) or new (fresh context each time)
• 📊 Fire Logging — Complete execution history with status, duration, cost tracking, and retry logic
• 🌙 Dream Cycles — Scheduled background memory consolidation with cost ceilings per run

📈 Smart Model Cascading

• 📉 Cost Optimization — Try cheap/fast models first, escalate to powerful models only when confidence is low
• 📊 4 Confidence Strategies — Structured output, heuristic, judge model, or none
• 💰 Per-Conversation Budgets — Automatic cost tracking with budget caps and eviction
• 🏢 Tenant Cost Ceilings — Monthly cost budgets per tenant with automatic enforcement
• 🔢 Tenant Agent Quotas — maxAgentsPerTenant enforcement on agent deployment

✋ Human-in-the-Loop Governance

• 🚦 Turn-Level Approval — PAUSE_CONVERSATION action halts the entire pipeline; new user input returns 409 Conflict until a human resumes
• 🔧 Per-Tool-Call Gating — Individual tool invocations can require human approval before execution, with glob-pattern allow/exempt lists across built-in, HTTP, MCP, A2A, dynamic, memory, and recall tools
• 👥 Group Phase Approval — Multi-agent discussion phases can require human sign-off at PHASE or TASK granularity
• 🧑‍🤝‍🧑 Humans in the Room — Beyond approving, a human can be a full group member with their own speaking turn; a facilitator can also pause a discussion to put a question to a named principal
• ⏱️ Timeout Policies — WAIT_INDEFINITELY, AUTO_APPROVE, AUTO_REJECT, or ABORT when humans don’t respond in time
• 🔁 No-Progress Guard — Detects infinite approval loops (identical pause fingerprints after automated decisions) and breaks the cycle
• 💬 Slack Approvals — Interactive Block Kit cards with redacted argument previews and approver whitelists
• 🔌 MCP Approvals — External clients can list pending approvals and approve/reject via MCP tools
• 🖥️ Manager Approvals — One page lists pending conversation and group-phase approvals and resolves them
• 🔄 Crash Recovery — Pending approvals survive server restarts; timeout timers are re-armed automatically

🔐 Enterprise Security & Compliance

⚙️ Configuration-Driven Architecture

• 📄 JSON Configs, Not Code — Agent behavior defined in versioned, diffable JSON documents
• 🔧 Lifecycle Pipeline — Pluggable task pipeline: Input → Parse → Rules → API/LLM → Output
• 📦 Composable Agents — Agents assembled from reusable, version-controlled workflows and extensions
• 🧪 Behavior Rules — IF-THEN logic engine for routing, orchestration, and business logic
• 📤 Import / Export — Agents portable as ZIP files with automatic secret scrubbing on export
• 🔄 Agent Sync — Live instance-to-instance sync with structural matching, content diffing, and selective resource picking — no ZIP intermediary needed
• 📝 Prompt Snippets — Reusable, versioned system prompt building blocks available as {snippets.safety_rules}
• 🌐 Global Variables — Deployment-wide values such as a default model, referenced as {vars.default-model} in any config (details)
• 📎 Content Type Routing — MIME-based behavior rule conditions for multimodal attachment routing

🚀 Cloud-Native & Observable

• 🐳 One-Command Install — Interactive wizard sets up EDDI + database via Docker
• ☸️ Kubernetes / OpenShift — Kustomize overlays, Helm charts, PDB, NetworkPolicy, and an HPA in cluster mode
• 🧩 Horizontal scaling — eddi.messaging.type=nats runs any number of replicas of the published image behind a plain round-robin load balancer: cluster-wide conversation leases with fencing, shared security and tool state in NATS JetStream KV, cross-node cancel/GDPR/undeploy, rolling updates without lost turns. See Clustering
• 📊 Prometheus & Grafana — 50+ Micrometer metrics at /q/metrics (tools, vault, memory, scheduling, conversations). Pre-built Grafana dashboard included
• 🔭 OpenTelemetry Tracing — Per-task distributed traces via OTLP (Jaeger, Tempo, Datadog). Every pipeline task emits a span named eddi.pipeline.task carrying eddi.task.id, eddi.task.type, eddi.task.index, eddi.conversation.id and eddi.agent.id. The equivalent metric tags are un-prefixed (task.id, task.type)
• 🤖 LLM Telemetry — Every model call, on every provider, streaming or not, is timed and counted (eddi.llm.request.duration, eddi.llm.tokens, eddi.llm.request.errors) and traced as a gen_ai.client.inference span
• 🩺 Health Checks — Liveness & readiness probes at /q/health/live and /q/health/ready
• 🔄 NATS JetStream — Cluster coordination: leases, shared KV state, cache-invalidation events and durable dead letters
• 🛟 Error Handling & Recovery — Automatic retry with exponential backoff, MCP circuit breakers (open after 3 failures within 60 s), LLM response validation (onEmpty / onTruncation / onRefusal), streaming timeout retry, and admin endpoint to reset stuck conversations
• ⚡ Virtual Threads — Java 25 virtual threads for true OS-level concurrency (no Python GIL or Node.js event loop bottleneck)
• 🗃️ DB-Agnostic — Choose MongoDB or PostgreSQL; switch with one env var. Single Docker image for both
• 🏗️ Red Hat Certified — Container certification with automated preflight checks in CI/CD

📖 Monitoring Guide: See docs/monitoring/monitoring-guide.md for architecture overview, metrics reference, alerting rules, and a production checklist.

🖥️ Manager Dashboard & Chat UI

Both UIs live in this repository (ui/manager, ui/chat) and are built into the EDDI jar and Docker image — nothing to deploy separately.

• 🎨 React 19 Manager (/manage) — Admin dashboard for agent building, testing, deployment, and monitoring, with the Platform Operator, an agent wizard, and editors for every resource type, including knowledge-base ingestion sources
• 👥 Workforce (/workforce) — A workspace for group conversations: boards, member threads, a live discussion overview, and history
• 💬 Chat UI (/chat) — Standalone React chat with SSE streaming and Keycloak auth
• ✋ Approvals, Connections & Sharing — Pages for pending HITL approvals, connections and linked accounts, and sharing resources between users and teams
• 🔍 Audit Trail Viewer — Timeline-based compliance and debugging UI
• 📋 Logs Panel — Live SSE log streaming + searchable history
• 🔑 Secrets Manager — Write-only vault UI with copy-reference support
• 🌍 11 Languages — English, German, Spanish, French, Portuguese, Chinese, Japanese, Korean, Arabic (RTL), Hindi, Thai

📖 Documentation

📋 Compliance & Privacy

EDDI provides built-in infrastructure for regulatory compliance:

🏗️ Development

Prerequisites

Windows users: Replace ./mvnw with .\mvnw.cmd in all commands below.

Quarkus Dev Mode

Dev mode starts the application with live reload — code changes are picked up automatically without restarting:

# Linux / macOS
./mvnw compile quarkus:dev '-Djvm.args=--add-modules=jdk.incubator.vector'

# Windows (PowerShell)
.\mvnw.cmd compile quarkus:dev '-Djvm.args=--add-modules=jdk.incubator.vector'

-Djvm.args hands the forked dev JVM the same --add-modules=jdk.incubator.vector flag the container image sets. Only jlama (in-process) agents need it — without it Jlama silently falls back to scalar tensor operations and answers far too slowly — so you may drop it if you never run one. mise run dev passes it for you.

Then open http://localhost:7070. The Quarkus Dev UI is available at http://localhost:7070/q/dev.

💡 The Manager and Chat UI build with Maven, at packaging time. Their sources live in ui/manager and ui/chat. ./mvnw package (and verify, install) builds them into the jar, about two minutes; compile, test and dev mode never touch npm, so dev mode serves /manage only after a package. For frontend work run npm run dev in ui/manager (port 3000, proxying to the backend on 7070). Upgrading an older checkout? Run ./mvnw clean once.

Dev mode also enables:

• Continuous testing — press r in the terminal to re-run tests on changes
• Dev UI — browse endpoints, CDI beans, configuration, and health checks
• Live reload — Java and resource changes apply instantly

💡 Secrets Vault: To use the secrets vault (storing API keys encrypted), set the master key before starting:

# Linux/macOS
export EDDI_VAULT_MASTER_KEY=my-dev-passphrase

# Windows (PowerShell)
$env:EDDI_VAULT_MASTER_KEY = "my-dev-passphrase"

# Or in a .env file (already in .gitignore)
echo "EDDI_VAULT_MASTER_KEY=my-dev-passphrase" > .env

Without this, the vault is disabled and secret management returns HTTP 503. Any passphrase works for local development. See Secrets Vault for production setup.

Maven Command Reference

target/site/jacoco/index.html

Build & Docker

# Build app + Docker image
./mvnw clean package '-Dquarkus.container-image.build=true'

# Build without container (for install.sh --local)
./mvnw package -DskipTests

# Generate third-party licenses (Red Hat certification)
./mvnw package -Plicense-gen -DskipTests

☸️ Kubernetes

No shipped manifest creates the eddi-secrets Secret that holds the vault master key — a Secret in the manifests would be reconciled on every kubectl apply and overwrite a live key, making everything already encrypted with it undecryptable. So the Secret is created out-of-band, before the first apply. Without it the EDDI pod sits in ContainerCreating (MountVolume.SetUp failed: secret "eddi-secrets" not found) and never starts.

# Kustomize overlays — create the vault Secret first, then apply
bash k8s/create-secrets.sh                 # PowerShell 7: pwsh -File .\k8s\create-secrets.ps1
# ...plus the database credentials, which are no longer shipped: mongodb-secrets
# (MongoDB runs authenticated) or postgres-secrets — commands in the Kubernetes Guide
kubectl apply -k k8s/overlays/mongodb/     # MongoDB backend
kubectl apply -k k8s/overlays/postgres/    # PostgreSQL backend

# Quickstart (one-file manifest; same Secret step, see the Kubernetes Guide)
kubectl apply -f https://raw.githubusercontent.com/labsai/EDDI/main/k8s/quickstart.yaml

# Helm (renders the Secret itself, so the key is a required value). Local,
# port-forward shape without OIDC: the two opt-ins are required, see the guide.
helm install eddi ./helm/eddi \
  --set eddi.vaultMasterKey="$(openssl rand -base64 24)" \
  --set mongodb.rootPassword="$(openssl rand -base64 24)" \
  --set eddi.security.allowUnauthenticatedMcp=true \
  --set eddi.security.allowUnauthenticatedSecretStore=true \
  --namespace eddi --create-namespace

Includes overlays for auth (Keycloak), monitoring (Prometheus/Grafana), cluster mode (a three-node NATS JetStream cluster and three EDDI replicas), Ingress, and production hardening (PDB, NetworkPolicy). See the Kubernetes Guide for details, including the Keycloak upgrade note for existing installs.

🤝 Contributing

We welcome contributions! Please read our Contributing Guide for details on setting up your development environment, code style, commit conventions, and the pull request process.

Every PR is automatically checked by CI (build + tests), CodeQL (security), dependency review, and AI-powered code review.

🔒 Security

EDDI ships with security-by-default for production deployments:

• Authentication enforced — AuthStartupGuard fails startup if OIDC is disabled in production without explicit opt-out; tokens must carry the eddi-backend audience and name a user
• Secrets encrypted at rest — Envelope encryption (PBKDF2 → AES-256-GCM) with per-deployment salt. Never plaintext in DB. A weak vault master key stops a production boot
• Credentials only where configured — A ${vault:…}, ${connection:…} or ${caller:…} reference resolves only where the configuration wrote it, not when it arrives through conversation data (a value EDDI auto-vaulted itself is the one exception)
• SSRF protection — EDDI’s own outbound HTTP (LLM tools, the crawler, OAuth, A2A, remote sync) goes through one facade, OutboundHttp, with private IP blocking, per-hop redirect validation, scheme enforcement and in-flight body caps
• Security headers — X-Content-Type-Options, X-Frame-Options, Content-Security-Policy configured out of the box
• Loopback by default — The Docker Compose files publish EDDI, Keycloak and the datastores on 127.0.0.1, and the Helm chart and Kustomize overlays ship no default credentials
• CI/CD security gates — Every push/PR is scanned by:
  • CodeQL — Semantic SAST analysis with security-extended queries
  • Trivy — CVE scanning for both filesystem dependencies and Docker images (blocking on CRITICAL/HIGH)
  • Gitleaks — Git history scanning to prevent secret/credential leakage
  • CycloneDX — SBOM generation for supply chain transparency
  • Jazzer — Coverage-guided fuzz testing for security-critical parsers (PathNavigator, MatchingUtilities)
  • All actions SHA-pinned to prevent supply-chain attacks

For vulnerability reports, see our Security Policy. For architecture details, see Security Architecture.

📜 Code of Conduct

This project follows the Contributor Covenant Code of Conduct.