README.md

May 6, 2026 · View on GitHub

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:

Service	Git tag	Docker image	Release notes
`evo-auth-service-community`	`v1.0.0-rc2`	`evoapicloud/evo-auth-service-community:1.0.0-rc2`	link
`evo-ai-crm-community`	`v1.0.0-rc2`	`evoapicloud/evo-ai-crm-community:1.0.0-rc2`	link
`evo-ai-frontend-community`	`v1.0.0-rc2`	`evoapicloud/evo-ai-frontend-community:1.0.0-rc2`	link
`evo-ai-processor-community`	`v1.0.0-rc2`	`evoapicloud/evo-ai-processor-community:1.0.0-rc2`	link
`evo-ai-core-service-community`	`v1.0.0-rc2`	`evoapicloud/evo-ai-core-service-community:1.0.0-rc2`	link
`evo-bot-runtime`	`v1.0.0-rc2`	`evoapicloud/evo-bot-runtime:1.0.0-rc2`	link
`evo-crm-gateway` (built from this repo)	`v1.0.0-rc2`	`evoapicloud/evo-crm-gateway:1.0.0-rc2`	(see umbrella release)

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

Service	Repository	Notes
`evolution-api`	WhatsApp messaging API (Node.js)	Independent versioning
`evolution-go`	WhatsApp messaging API (Go)	Independent versioning
`evo-nexus`	Multi-agent operating layer	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:

Service	Role	Stack	Default Port
`evo-auth-service-community`	Authentication, RBAC, OAuth 2.0, token issuance	Ruby 3.4 / Rails 7.1	`3001`
`evo-ai-crm-community`	Conversations, contacts, inboxes, messaging	Ruby 3.4 / Rails 7.1	`3000`
`evo-ai-frontend-community`	Web interface	React / TypeScript / Vite	`5173`
`evo-ai-processor-community`	AI agent execution, sessions, tools, MCP	Python 3.10 / FastAPI	`8000`
`evo-ai-core-service-community`	Agent management, API keys, folders	Go / Gin	`5555`
`evo-bot-runtime`	Bot pipeline execution, debouncing, dispatch	Go / Gin	`8080`

Design principles (Community Edition)

Single-tenant — one account, no multi-tenancy overhead
No super-admin — all configuration via seed data and environment variables
No billing / plans — all limits removed, features unlocked by default
Role hierarchy: account_owner and agent — no intermediate roles
Account resolution via token — no account-id header required between services

Companion services (independent versioning)

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

Service	Role
`evolution-api`	WhatsApp messaging engine (Node.js) — used as a channel provider
`evolution-go`	WhatsApp messaging engine (Go) — alternative high-performance provider
`evo-nexus`	Multi-agent operating layer — used internally by Evolution Foundation to coordinate development and operations

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:

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`)

Submodule	Repository
`evo-auth-service-community`	evolution-foundation/evo-auth-service-community
`evo-ai-crm-community`	evolution-foundation/evo-ai-crm-community
`evo-ai-frontend-community`	evolution-foundation/evo-ai-frontend-community
`evo-ai-processor-community`	evolution-foundation/evo-ai-processor-community
`evo-ai-core-service-community`	evolution-foundation/evo-ai-core-service-community
`evo-bot-runtime`	evolution-foundation/evo-bot-runtime

Companion projects (independent versioning)

Submodule	Repository
`evolution-api`	evolution-foundation/evolution-api
`evolution-go`	evolution-foundation/evolution-go
`evo-nexus`	evolution-foundation/evo-nexus

Documentation

Resource	Link
Website	evolutionfoundation.com.br
Documentation	docs.evolutionfoundation.com.br
Community	evolutionfoundation.com.br/community
Changelog	CHANGELOG.md
Contributing	CONTRIBUTING.md
Security	SECURITY.md