customermates

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="public/images/dark/customermates.svg">
    <source media="(prefers-color-scheme: light)" srcset="public/images/light/customermates.svg">
    <img src="public/images/light/customermates.svg" height="64" alt="Customermates">
  </picture>
</p>

<p align="center">Open-core CRM with an AGPL-licensed Community Edition, AI agents, APIs, MCP, and self-hosting.</p>

<p align="center">
  <a href="https://customermates.com">Website</a> |
  <a href="https://demo.customermates.com">Demo</a> |
  <a href="https://customermates.com/docs">Documentation</a> |
  <a href="https://github.com/customermates/customermates">GitHub</a> |
  <a href="https://youtu.be/A7juUe3Iaco">Walkthrough</a>
</p>


<p align="center">
  <img src=".github/media/customermates-promo.gif" alt="Customermates: 57 second walkthrough" width="1200">
</p>

Customermates is a CRM for modern teams that want a clear system for contacts, organizations, deals, services, and tasks without the usual enterprise-heavy setup. It combines practical CRM workflows with API access, webhooks, n8n automation, MCP-based tooling, and AI-agent workflows.

You can use the managed cloud version or run Customermates yourself in your own infrastructure with Docker Compose.

## 🚀 Getting Started

There are two ways to start using Customermates:

| Option | Description |
| --- | --- |
| **[Cloud](https://customermates.com)** | Fastest way to get started. Managed by Customermates. |
| **[Self-Hosting](https://customermates.com/docs/self-hosting)** | Run Customermates on your own server with Docker Compose and PostgreSQL. |

Docs entry points:

- [CRM Overview](https://customermates.com/docs)
- [Self-Hosting (install, manage, cloud vs self-host)](https://customermates.com/docs/self-hosting)
- [Connect your AI (Claude)](https://customermates.com/docs/mcp-connect-claude)
- [Webhooks](https://customermates.com/docs/webhooks)

## ⭐ Key Features

- CRM for contacts, organizations, deals, services, and tasks
- API access with OpenAPI documentation
- Webhooks and event-driven integrations
- n8n workflows and automation support
- MCP support for agent tooling and structured tool calling
- Unified inbox for email, LinkedIn, WhatsApp, Instagram, and Telegram (Cloud, from the Pro plan)
- Audit logging
- Single Sign-On and Whitelabeling on the Enterprise plan (self-hosted Enterprise deployments by agreement)
- Role-based access control for teams
- Self-hosted deployment with Docker Compose and PostgreSQL
- Cloud uses monthly per-seat pricing; see the [current plans](https://customermates.com/pricing)

## 📊 Comparison

Customermates supports both cloud and self-hosted deployment models.

| Criterion | Cloud | Self-Hosted |
| --- | --- | --- |
| Pricing | [monthly per-seat plans](https://customermates.com/pricing) | free core + infra costs |
| Setup Time | 2 minutes | ~15 minutes |
| Maintenance Required | None | Docker, Postgres, proxy, TLS, backups |
| Updates | Automatic | `docker compose pull && docker compose up -d` |
| EU-hosted | ✅ | wherever you put it |
| Backups | Automatic daily | You configure |
| API and integrations | ✅ | ✅ |
| Unlimited Users | ✅ | ✅ |
| Unlimited Records | ✅ | ✅ |
| n8n and automation workflows | ✅ | ✅ |
| Unified inbox and calendar sync | from the Pro plan | ❌ (Cloud feature) |
| Audit log | Included | Included |
| Enterprise (SSO, Whitelabeling) | Enterprise plan | By agreement |

If you want the full decision guide, see the [Self-hosting docs](https://customermates.com/docs/self-hosting).

## 🐳 Self-Hosting

Self-hosting is two files (`docker-compose.yml` and `.env`) plus `docker compose up -d`. No `git clone`, no build step. The published image at `ghcr.io/customermates/customermates:latest` applies pending migrations every time it starts.

### Prerequisites

- Docker and Docker Compose v2.
- A domain name if you want TLS (optional for local).
- ~2 GB RAM and a couple of GB of disk per thousand records.

### Setup

```bash
mkdir customermates && cd customermates
curl -fsSL https://raw.githubusercontent.com/customermates/customermates/main/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/customermates/customermates/main/.env.selfhost.template -o .env
# edit .env with real values
docker compose up -d
```

Required `.env` values:

- `BETTER_AUTH_SECRET`: long random string (`openssl rand -hex 32`).
- `POSTGRES_PASSWORD`: change the default.
- `BASE_URL`: your public URL (e.g. `https://crm.example.com`).
- `RESEND_API_KEY` and `RESEND_OPERATOR_EMAIL`: for signup verification, password reset, and invitation emails.

Optional: uncomment `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`, or `AZURE_AD_CLIENT_ID` and `AZURE_AD_CLIENT_SECRET`, to offer sign-in with Google or Microsoft. See [Can users sign in with Google or Microsoft?](https://customermates.com/docs/self-hosting#can-users-sign-in-with-google-or-microsoft).

First boot takes ~1 minute while Prisma applies migrations. Watch with `docker compose logs -f app`, then open `<BASE_URL>/auth/signup`.

### Day-to-day

```bash
docker compose pull && docker compose up -d   # update
docker compose up -d                           # apply .env changes
docker compose logs -f app                     # logs
```

Front the app with a reverse proxy (Caddy, nginx, Traefik) for TLS and set `BASE_URL` to the public `https://` address. Customermates takes the scheme and host for its links from `BASE_URL` and sets secure cookies when it uses `https://`, so `X-Forwarded-Proto` is not required. The proxy must pass on the original `Host` header, because the app rejects form submissions whose origin does not match it, including sign-in and sign-up.

More docs:

- [Self-Hosting (install and manage)](https://customermates.com/docs/self-hosting)
- [Architecture and security](https://customermates.com/docs/architecture-security)

## 🛠️ Development

Create an isolated worktree and run Customermates locally:

```bash
git fetch origin main
git worktree add ../customermates-my-change -b feat/my-change origin/main
cd ../customermates-my-change
nvm use
yarn db:provision
cp .env.cloud.template .env
# Paste the printed DATABASE_URL and DIRECT_URL into .env.
yarn install --frozen-lockfile
yarn db:reset
yarn dev
```

`yarn db:provision` creates a PostgreSQL 17 container and named volume owned by the current worktree. Re-running it is idempotent. `yarn db:reset` applies the migrations, seeds the database, and prepares the workflow schemas. Replacing the database volume is destructive and only happens with `yarn db:provision --recreate`; use `yarn db:provision --destroy` to remove the worktree's owned database when the worktree is retired.

Useful scripts:

- `yarn dev`
- `yarn build`
- `yarn lint`
- `yarn openapi:generate`
- `yarn db:provision`
- `yarn db:reset`

## 📚 Documentation

The docs cover:

- product overview and CRM comparison
- self-hosting and operations
- API integrations and OpenAPI
- MCP and n8n
- architecture and security

Start here: [customermates.com/docs](https://customermates.com/docs)

## 📄 License

Customermates uses an open-core licensing model.

The Community Edition (all first-party code outside `ee/`) is licensed under [AGPL-3.0-only](./LICENSE).

Other first-party files in `ee/` are source-available under the [Customermates Commercial License](./ee/LICENSE.md), subject to its AGPL client-material exception. Production use of Commercial Software outside the limited Community Build permission, including any Enterprise Feature, requires a Commercial Agreement.

The official Community image at `ghcr.io/customermates/customermates` is built from the shared codebase and contains compiled Commercial Software. The limited Community Build permission allows anyone to run its unmodified commercial support components where documented `APP_MODE=self-hosted` operation necessarily executes them; it does not license Enterprise Feature use.

Contributor terms are available in [`.github/CLA.md`](./.github/CLA.md).