CRMax Core documentation

Everything you need to install, configure and run your free, self-hosted CRM.

Overview

CRMax Core is a complete CRM in one small application: contacts, a deal pipeline, tasks, lead-capture forms, email campaigns and workflow automation. It is written in plain PHP with a SQLite database, so there is no framework, no Composer, no build step and no external services. You host it yourself, you own the data, and it is open-source under the MIT licence.

Requirements

• PHP 8.1 or newer with the pdo_sqlite and curl extensions (both are standard on nearly every host).
• Any web server: Apache, nginx, Caddy, or PHP's own built-in server.
• Write access for the web server to the data/ folder.

Install

1. Download the latest release and unzip it, or clone the repository.
2. Upload the folder to your server (it works at the web root or in a subfolder).
3. Make sure the web server can write to data/ (it is created automatically if missing).
4. Open the folder in your browser.

Try it locally in one command

unzip crmax-core.zip && cd crmax-core
php -S localhost:8000
# then open http://localhost:8000

Apache

Works out of the box. The bundled data/.htaccess blocks web access to the database.

nginx

location / { try_files $uri $uri/ =404; }
location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php-fpm.sock;
}
location ^~ /data/ { deny all; return 404; }

First run

The first time you open CRMax Core it shows a short setup form. The first account you create becomes the administrator. The SQLite database installs itself on that first request - there is nothing else to configure to start. You can add the rest of your team afterwards in Settings.

Sending email (SMTP)

CRMax Core sends campaigns, workflow emails and form notifications through your own mail server. Go to Settings → Email accounts and add your provider's SMTP details, then use the Test button to confirm it works.

Background jobs (cron)

Workflows and campaign sending run from a scheduled task. Add one line to cron so it runs every minute:

* * * * * php /path/to/crmax-core/cron.php >/dev/null 2>&1

Prefer HTTP? Copy config.sample.php to config.php, set a cron_key, and schedule a request to https://your-crm/cron.php?key=YOUR_KEY every minute.

AI (bring your own key)

AI features - such as drafting a campaign email from a short brief - are optional. In Settings → AI, paste your own Anthropic API key to turn them on. No key is included and nothing calls out unless you add one. Leave the key field blank to keep the current key, or type a new value to replace it.

Team & roles

Invite colleagues in Settings → Team. There are two roles: Admin (full access, including settings and team) and Member (everything except settings). Everyone shares the same organisation's data. Each person can change their own password in Settings.

Contacts & CSV

Contacts are searchable and taggable, and each has notes, tasks and a full activity timeline. Use Import CSV to bring contacts in - columns recognised include first_name, last_name, email, phone, company, address and tags (comma separated). Existing contacts are matched by email, so re-importing updates rather than duplicates. Export CSV downloads everything.

Pipeline

Create one or more pipelines with your own stages (edit them any time). Add deals, link them to a contact, and drag cards between stages. Mark a deal Won or Lost to take it out of the board; the column headers show the count and total value in each stage.

Forms

Build a lead-capture form in Forms by adding fields (give a field the key first_name, last_name, email, phone or company to map it onto a contact). Share the public link, or embed the form on your website:

<iframe src="https://your-crm/f.php?s=your-form" style="width:100%;max-width:520px;height:560px;border:0"></iframe>

Every submission becomes a contact and is recorded against the form. Tick Email me each submission to get notified, and a submission can trigger a workflow.

Campaigns

Write a campaign, pick who it goes to (all contacts, or a single tag), choose which email account to send from, and send. Merge tags like {{first_name}} and {{company}} are filled in per contact. Opens are tracked and every email carries a one-click unsubscribe link; unsubscribed contacts are skipped automatically. Delivery happens in the background via cron.

Workflows

A workflow runs a sequence of steps when something happens. Choose a trigger - a contact is created, a form is submitted, or a tag is added - then add steps:

Workflows start paused - activate one when you are ready. Steps run from the cron job.

REST API

Create a token in Settings → REST API and send it as a Bearer header.

curl -H "Authorization: Bearer <token>" https://your-crm/api.php/contacts
curl -H "Authorization: Bearer <token>" https://your-crm/api.php/me

# create or update a contact (de-duplicated by email)
curl -X POST https://your-crm/api.php/contacts \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"first_name":"Dana","email":"dana@example.com","tags":["web"],"source":"api"}'

Backups

Everything lives in data/crm.sqlite. Copy that file to back up, and replace it to restore. Because SQLite runs in WAL mode, either copy crm.sqlite, crm.sqlite-wal and crm.sqlite-shm together, or stop traffic first.

Security

• Keep data/ out of the web root, or rely on the bundled data/.htaccess (Apache) or the nginx deny rule above.
• Always run behind HTTPS in production - session cookies are marked secure automatically over HTTPS.
• CSRF protection, login rate-limiting and HTML sanitisation of saved content are built in.

Updating

Download the newer release and replace the application files, keeping your data/ folder (and config.php if you created one). The database applies any schema changes automatically on the next request.

Frequently asked questions