Skip to content
AgentSDR
Live demo

Guide · 11 min read

How to self-host an open-source CRM

To self-host an open-source CRM you need a server, a database, a secrets file and a way to reach it over HTTPS. This guide walks through that with AgentSDR's real steps as the worked example, then covers customizing it.

· By the AgentSDR team

The short version

Self-hosting a CRM sounds like a project, and with most software it is. The shape is the same each time: get the files, give the application a database, set the secrets it signs and encrypts with, start it, create the first account, then connect and configure. What differs is how many moving parts the CRM brings.

AgentSDR brings two: one Next.js application and one PostgreSQL database. It has no queue server and no separate worker, because background work runs inside the app. That makes it a reasonable worked example. The commands below come from its self-hosting documentation. If you are still deciding whether to host at all, read open-source vs SaaS CRM first, and self-hosted CRM for what you own once you do.

Decide first: what must the CRM do?

The most expensive mistake is installing a CRM before deciding which job it has. Write down the two or three things it must do in your first month, then check the project does them.

Then check the licence. MIT, which AgentSDR uses, allows self-hosting, modification and commercial use without publishing your changes.

Install it

You need a machine with Docker and Docker Compose, about five minutes, and for a public server a domain and an HTTPS reverse proxy. Docker Compose is the recommended path. The other two are running from source, and Dokploy on a VPS.

Three ways to install AgentSDR
PathBest for
Docker ComposeMost people. Database, schema and scheduled jobs included.
From sourceDevelopment, or a host where you manage Bun or Node.js and PostgreSQL.
Dokploy on a VPSA self-hosted platform with domains, HTTPS and deploy-on-push.

The Compose steps

mkdir agentsdr && cd agentsdr
curl -O https://raw.githubusercontent.com/Kandid-ai/AgentSDR/main/docker-compose.yml

{
  echo "APP_URL=http://localhost:3000"
  for name in BETTER_AUTH_SECRET INTEGRATION_CREDENTIALS_KEY UNSUBSCRIBE_SECRET POSTGRES_PASSWORD; do
    echo "$name=$(openssl rand -hex 32)"
  done
} > .env

docker compose up -d

The .env next to the file holds four generated secrets and your public address. Replace APP_URL with the address people will use. On http://localhost the app starts even with placeholder secrets, so you can try it. With any other address it refuses to start until every CHANGEME value is replaced, because the placeholders are public.

The command starts two containers: PostgreSQL 18 with a persistent volume that publishes no port, and the app on port 3000. On first start the app creates the schema in an empty database and runs its scheduled jobs itself. Check with docker compose ps and docker compose logs -f app.

First sign-up

Open your address. While no account exists, every page sends you to /setup. Enter your name, an organization name, an email and a password. You become the owner of the organization, signed in and verified, with no email or Resend needed for this step.

Everything in AgentSDR belongs to an organization, and a second organization sees nothing of the first. That is how an agency runs one client per organization on a single deployment. Later accounts sign up at /sign-up, and AUTH_SIGNUP decides who may: invite-only by default, or open.

Connect the services

A CRM that sends and reads messages needs accounts to do it with. In AgentSDR you connect them inside the app, per organization, from Settings. There is no environment fallback. Each feature switches on when its service is connected.

Services to connect and what each powers
ServicePowersNeeded for
OpenRouterEvery AI feature, on your own keyClassification, drafts, AI columns
Google WorkspaceSending and reading Gmail through a service accountEmail outreach and the inbox
UnipileLinkedIn and WhatsApp accountsLinkedIn and WhatsApp
Cloudflare R2Call recordingsWhatsApp call recording
ResendInvitation and password-reset email, set in the environmentInviting teammates

Start with OpenRouter and one mailbox. Connecting Google Workspace takes about 15 minutes and a Workspace super admin for the domain-wide delegation step. Do the others as you need them.

Bring in your data

A CRM is only as useful as what is in it. AgentSDR imports people from CSV or Excel files on the Leads page, with the first row as headers. Matching ignores case and spacing, so Job Title and job_title are the same column, and someone imported twice is never duplicated. A row that fails is listed with its reason.

Columns the importer does not recognize are kept as custom fields and can be used as merge fields in messages. Two things to plan before a large import: which fields you want as real, typed fields, and how you will mark people who must never be contacted, since Do Not Contact blocks every channel.

A CRM record begins on a lead’s first reply, not at import. Imported people live in the lead database until they answer.

How do you customize an open-source CRM?

Work from the top of this list down, and stop as soon as the job is done. Each step is a smaller change than the one below it.

  1. Fields. In Settings, Lead columns, add fields to people or companies: text, number, currency, checkbox, date, URL, email, select, multi-select and more. Each gets a permanent key beginning x_. You can rename a field and archive it later; built-in fields keep their type.
  2. Categories and stages. The four categories are fixed: Interested, Customer, Not interested and Other. The subcategories under them are yours to add, rename and re-describe, and each can carry a funnel stage number. See the AI CRM.
  3. Sequences. Under CRM, Sequences, write a flow with a goal for each step, up to 30 steps, then attach it to a subcategory in Lead categories. Publish it; only a published version runs.
  4. AI instructions and knowledge. Write the instructions every draft and classification follows, and add knowledge documents the AI can draw on. Better wording here improves later replies without touching code.
  5. Sending rules. Set emails a day, send gaps, sending hours and the LinkedIn and WhatsApp limits per organization, with overrides on a single account.
  6. API and assistants. Create an API key to add leads to email campaigns from another application, or connect an assistant over MCP. Both are scoped to the organization.
  7. Source code. Fork the repository and change what the settings cannot. It is TypeScript on Next.js with Drizzle and PostgreSQL. Add a new table to the allowlist in drizzle.config.ts and keep schema changes as migration scripts in scripts/, the way the project does. The contributing guide covers pull requests if you want changes upstream.

Go to production

Trying it on localhost needs none of this. A server that other people use does.

  • Point a domain at the server, put an HTTPS reverse proxy in front, and set APP_URL to the public address.
  • Set RESEND_API_KEY and AUTH_EMAIL_FROM so invitations and password resets send. Without them each link is written to docker compose logs app.
  • Choose AUTH_SIGNUP deliberately.
  • Set each organization’s time zone, which decides when its day rolls over for send limits.
  • Keep DB_POOL_MAX (default 8) under your PostgreSQL server’s connection limit, counting every client.
  • Run one app instance only. The email sender has no distributed lock.

Operational switches such as PAUSE_EMAIL_OUTBOUNDstop a channel’s sending without touching data, which is useful as an emergency brake.

Backups and upgrades

Two things must be backed up together: the database and the credentials key.

docker compose exec db pg_dump -U agentsdr agentsdr > agentsdr-$(date +%F).sql

Call recordings live in R2, not the database, so back up that bucket separately. Note that docker compose down -v deletes the database volume.

To upgrade a Compose install:

curl -O https://raw.githubusercontent.com/Kandid-ai/AgentSDR/main/docker-compose.yml
docker compose pull
docker compose up -d --remove-orphans

Back up first and read the release notes. The app creates a schema only in an empty database and does not upgrade an existing one, so run any migration scripts the notes name before you rely on the new version. Migrations are guarded with IF NOT EXISTS and safe to run twice.

Checklist

  1. You wrote down the CRM’s first-month jobs and the project does them.
  2. The licence allows how you will use it.
  3. Secrets are generated and the credentials key is stored outside the database.
  4. The admin account exists and sign-up is set the way you want.
  5. Your AI key and first channel are connected and tested.
  6. Leads are imported, with fields typed and Do Not Contact marked.
  7. Categories, sequences and AI instructions match how you sell.
  8. HTTPS, Resend, time zone and the pool size are set.
  9. A backup of the database and the key exists, and you have tried a restore.

FAQ

Questions, answered

How do I implement an open-source CRM?

Decide which jobs it must do, install it on a server with its database, create the admin account, connect the outside services it needs, import your data, then configure fields, stages and automations to match how you sell. With AgentSDR the install is one Docker Compose file and one command.

How long does it take to self-host AgentSDR?

The install is about five minutes, and the first start downloads the image. Connecting Google Workspace takes about 15 minutes according to the integration guide, and Google says delegation changes can take up to 24 hours to apply, though they are usually much quicker.

Do I need to know how to code to customize it?

No for most changes. Custom fields, lead categories, sequences, AI instructions, knowledge and sending rules are settings in the app. Code is for changes the settings cannot make, and the MIT licence lets you make them.

What do I back up?

The PostgreSQL database, your INTEGRATION_CREDENTIALS_KEY kept outside the database, and the Cloudflare R2 bucket if you record calls. A database restored without the key cannot decrypt your saved integrations.

How do I upgrade a self-hosted AgentSDR?

Back up, pull the new image tag, run any migration scripts the release notes name, and restart. The app creates a schema only in an empty database, so it does not upgrade an existing one for you.

Run your own CRM this afternoon.

AgentSDR is MIT-licensed. One file, one command, and the data stays in your database.