· 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.
- Outbound and replies. If the job is cold outreach and handling the answers, AgentSDR is built for it. See open-source CRM and open-source sales engagement.
- Invoicing, helpdesk or ERP. AgentSDR has none of these. Use a general-purpose CRM, and compare options in the best open-source CRMs or against Twenty, SuiteCRM, EspoCRM and Odoo.
- Replacing a suite. If you are coming from Salesforce or HubSpot, list which of their modules you actually use before you move anything.
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.
| Path | Best for |
|---|---|
| Docker Compose | Most people. Database, schema and scheduled jobs included. |
| From source | Development, or a host where you manage Bun or Node.js and PostgreSQL. |
| Dokploy on a VPS | A 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 -dThe .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.
| Service | Powers | Needed for |
|---|---|---|
| OpenRouter | Every AI feature, on your own key | Classification, drafts, AI columns |
| Google Workspace | Sending and reading Gmail through a service account | Email outreach and the inbox |
| Unipile | LinkedIn and WhatsApp accounts | LinkedIn and WhatsApp |
| Cloudflare R2 | Call recordings | WhatsApp call recording |
| Resend | Invitation and password-reset email, set in the environment | Inviting 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.
- 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. - 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.
- 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.
- 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.
- Sending rules. Set emails a day, send gaps, sending hours and the LinkedIn and WhatsApp limits per organization, with overrides on a single account.
- 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.
- 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.tsand keep schema changes as migration scripts inscripts/, 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_URLto the public address. - Set
RESEND_API_KEYandAUTH_EMAIL_FROMso invitations and password resets send. Without them each link is written todocker compose logs app. - Choose
AUTH_SIGNUPdeliberately. - 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).sqlCall 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-orphansBack 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
- You wrote down the CRM’s first-month jobs and the project does them.
- The licence allows how you will use it.
- Secrets are generated and the credentials key is stored outside the database.
- The admin account exists and sign-up is set the way you want.
- Your AI key and first channel are connected and tested.
- Leads are imported, with fields typed and Do Not Contact marked.
- Categories, sequences and AI instructions match how you sell.
- HTTPS, Resend, time zone and the pool size are set.
- A backup of the database and the key exists, and you have tried a restore.


