Evo CRM Community

Open-source, single-tenant AI-powered customer support platform — by Evolution Foundation.

Website · Documentation · Community · Support

---

#About

Evo CRM Community is the open-source edition of the Evo CRM platform — a complete suite for AI-assisted customer support. It brings together authentication, CRM, AI agents, agent processing, bot pipelines and a modern frontend into a unified, self-hostable stack.

This repository is the monorepo entrypoint: it aggregates all community services as Git submodules, giving you a single place to clone, update and orchestrate the entire platform.

---

#Current Version

v1.0.0-rc2 (latest) — see the release notes for highlights, security advisories and known issues. Previous: v1.0.0-rc1.

The umbrella tag pins each Community submodule at its corresponding v1.0.0-rc2 tag. Cloning with --recurse-submodules at this tag reproduces the full stack as released:

The following projects are part of the broader Evolution Foundation ecosystem but follow independent versioning:

Note on tag naming: the git tag has the v prefix (v1.0.0-rc2) following standard Git convention. The Docker tag drops the v (1.0.0-rc2) following SemVer / Docker Hub convention. latest on Docker Hub always tracks the most recent published tag.

# Source clone (pinned to the release):
git clone --recurse-submodules --branch v1.0.0-rc2 git@github.com:evolution-foundation/evo-crm-community.git

# Or pull pre-built images (compose files use :latest by default):
docker pull evoapicloud/evo-ai-crm-community:1.0.0-rc2

---

#Architecture

The Evo CRM Community platform is composed of 6 independent services:

#Design principles (Community Edition)

• Single-tenant — one account, no multi-tenancy overhead
• No billing / plans — all limits removed, features unlocked by default
• Configuration via seed data and environment variables — with one exception: installation-level settings (SMTP, Storage, Social Login, OpenAI, Channels, Inbound Email, Frontend Runtime) live in the database, behind installation_configs.manage
• Role hierarchy — three seeded roles (agent, account_owner, super_admin), plus any custom role created at runtime — see Roles
• Account resolution via token — no account-id header required between services

#Roles

db/seeds/rbac.rb in evo-auth-service-community is the authoritative role model. It seeds three roles:

Two facts a security review needs, because neither is enforced by the code:

• super_admin has no single-holder guarantee. The setup wizard grants it to the user it creates, and the PromoteFirstUserToSuperAdmin migration grants it to the oldest user of an already-bootstrapped installation. Nothing prevents it being assigned to more — audit user_roles for the super_admin role key instead of assuming one installation owner.
• The seeded three are not the whole set. account_owner holds roles.create and roles.bulk_update_permissions, so custom roles with arbitrary permission sets can be created at runtime via POST /api/v1/roles.

Role::ADMIN_ROLE_KEYS (defined in evo-ai-crm-community, mirrored in auth and the frontend) is an admin-bypass allowlist, not the role model: it also names legacy administrator/admin keys the seed never creates, and the three copies disagree.

#Companion services (independent versioning)

The following services are part of the Evolution Foundation ecosystem but are not pinned to the Evo CRM release tag:

---

#Getting Started

#Prerequisites

• Docker & Docker Compose
• Git with submodule support

#1. Clone with submodules

git clone --recurse-submodules git@github.com:evolution-foundation/evo-crm-community.git
cd evo-crm-community

If you already cloned without submodules:

git submodule update --init --recursive

#2. Update all submodules to latest

git submodule update --remote --merge

#3. Setup each service

Refer to each service's own README for environment configuration, setup and seed instructions:

• evo-auth-service-community
• evo-ai-crm-community
• evo-ai-frontend-community
• evo-ai-processor-community
• evo-ai-core-service-community
• evo-bot-runtime

Note: evo-auth-service-community must be seeded before evo-ai-crm-community — the CRM depends on the user created by the auth seed.

Production deployment — required environment overrides

Before promoting any environment to production, the following variables in .env.example must be replaced with public URLs (the bundled http://localhost:* defaults exist for local development only):

• BACKEND_URL — public URL of the CRM backend (e.g. https://crm.example.com). The CRM refuses to boot in production if this is missing or points at localhost.
• FRONTEND_URL — public URL of the frontend (e.g. https://app.example.com). Used for OAuth redirects and channel webhook fallbacks.

Leaving the localhost defaults in production results in webhook callbacks pointing at the container, broken OAuth redirects and silently failed external integrations.

For detailed setup instructions, visit the full documentation.

---

#Service Dependencies

evo-ai-frontend-community
    └── evo-auth-service-community  (authentication)
    └── evo-ai-crm-community        (conversations, contacts)
    └── evo-ai-core-service-community (agents, tools, API keys)
    └── evo-ai-processor-community  (agent execution, sessions)
        └── evo-bot-runtime         (bot pipeline execution)

All inter-service communication uses Bearer token authentication. The token issued by evo-auth-service-community is forwarded between services — no additional headers required.

---

#Submodules Reference

#Evo CRM Community core (pinned to v1.0.0-rc2)

#Companion projects (independent versioning)

---

#Documentation

---

#Hosting

Deploy Evo CRM Community with optimized infrastructure through our HostGator partnership:

Evo CRM VPS — HostGator

---

#Contributing

Contributions are welcome! Please open an issue or pull request in the relevant submodule repository. See CONTRIBUTING.md for guidelines.

Join our community to discuss ideas, ask questions and collaborate.

---

#Security

For security issues, do not open a public issue. Email suporte@evofoundation.com.br or use GitHub's private vulnerability reporting. See SECURITY.md for details.

---

#License

Evo CRM Community is licensed under the Apache License 2.0, with additional brand-protection conditions (LOGO/copyright preservation and Usage Notification requirement). See LICENSE for full details.

For licensing inquiries, contact suporte@evofoundation.com.br.

#Trademarks

"Evolution Foundation", "Evolution" and "Evo CRM" are trademarks of Evolution Foundation. See TRADEMARKS.md for the brand assets policy.

Third-party attributions are documented in NOTICE.

---

Made by Evolution Foundation · © 2026