What you need before you start
The deploy tool checks for Docker, scaffolds a project and generates the secrets for you. AI provider keys are added later, in the dashboard.
- A Linux server, or any machine that runs Docker
- Docker with Docker Compose
- Node.js 16 or newer, for the deploy tool
- Ports 80 and 443 open, if it will be public
- A domain name pointed at the server, for HTTPS
- A key for an AI provider, or your own model on an OpenAI-compatible endpoint
- A Firebase project, only if you want push notifications. It is optional
- Your own Meta, Slack or CRM apps for the channels and integrations you connect
What runs on your server
The backend and both workers run from the same prebuilt image. Embeddings for knowledge search are made on your server, so search needs no extra API key.
Web server and HTTPS. Routes the dashboard, API, websockets and widget
Ports 80 and 443The dashboard and the chat widget loader
Inside Docker onlyThe API, the AI agent and every channel
This machine only (127.0.0.1)Crawls sites, reads PDFs and builds the search index
No portRuns AI ticket investigations in the background
No portChats, settings, tickets and your knowledge
This machine onlyCaching and queues, capped at 512 MB
This machine onlyHow big a server you need
Memory runs out before CPU does. The backend and the two workers each load the local embedding model, and a big website crawl is the heaviest moment the install has. Postgres grows with your chats and your knowledge, and uploaded files grow with your help center and attachments.
Our suggestion is to start with 2 vCPUs and 8 GB of RAM, plus enough disk for Docker images, your database and uploads. Small installs run on less, but a crawl may then fail partway through. If you host your own model on the same machine, size for the model separately: it will need far more memory than ChatterMate does.
Install it, step by step
- Step 1Install the tool
npm install -g chattermate-deploygives you thechattermate-deploycommand. - Step 2Scaffold a project
initasks whether to serve a public domain with HTTPS, offers Firebase setup, and generates your secret keys. - Step 3Point your DNSAdd an A or AAAA record for your app domain. Add a wildcard record too if the help center will use subdomains.
- Step 4Start it
startpulls the images, runs the database migrations and waits until every service is healthy. Then sign in and add your AI key.
Three ways to handle HTTPS
Without a domain, the install serves plain HTTP on localhost, which is fine for a trial but not for customers. To switch later, run init again with your domain.
Give an email address and Caddy gets a Let's Encrypt certificate on the first request, then renews it.
Point init at your PEM certificate and key. They are copied into the project and served by Caddy.
If a load balancer already terminates TLS, point it at port 80 on this host and keep the Host header.
The commands
chattermate-deploy init NAMEScaffold a new project
chattermate-deploy startPull the latest images and start every service
chattermate-deploy stopStop them
chattermate-deploy statusCheck what is running
chattermate-deploy logsRead the logs. Add -s backend for one service
chattermate-deploy resetRemove everything, including data
How updates work
Every time you run chattermate-deploy start, it pulls the newest images and the backend applies any database migrations as it boots. That makes start your update command, so treat it like one.
Before you update, back up the database (below) and read the changelog for anything that needs a setting changed. Then run stop and start. Plan a few minutes when chats can't be answered. If the server reboots, Docker restarts the containers on the images you already have, so nothing changes until you choose to update.
What to back up
Back up on a schedule, and test a restore once on a spare machine. An untested backup is a guess.
- The database. For example:
docker compose exec db pg_dump -U postgres chattermate > backup.sql - The uploads volume, unless you store files in S3
backend/.env, which holds your encryption keys- Your Caddyfile and certificates, if you supplied them
Chat messages, AI summaries, model API keys and channel and CRM credentials are encrypted with keys in backend/.env. A database backup without those keys can't be read, so store them somewhere separate from the backup.
Never run reset on a live install. It deletes every chat, agent and file.
What stays on your server and what leaves it
Self-hosting the app keeps your transcripts in your database. Message text still goes to the AI provider you choose, so to keep every message inside your network, host the model too.
| Part | Self-hosted | On our cloud |
|---|---|---|
| The app and inbox | Your servers | Our servers |
| Chats and knowledge | Your database | Our database |
| Knowledge embeddings | Made on your server | Made on our servers |
| The AI model | Your choice: a provider with your key, or your own model | Our hosted model, or your key on paid plans |
Bring your own model
Use OpenAI, Anthropic, Google Gemini, Mistral, xAI, DeepSeek or Groq with your own key, or point it at any OpenAI-compatible endpoint, such as Ollama, vLLM, llama.cpp, OpenRouter or LiteLLM. Saving the setting runs a live test message, so you know it works before a customer sees it.
What you look after, and what it costs
Self-hosting often wins when data rules require it. When they do not, the cloud can be cheaper once you count your own time.
Nobody else is watching the server. Keep the operating system and Docker patched, and set up a check that tells you when the site stops answering.
The app encrypts messages and credentials. Customer names, emails, tickets and knowledge are not, so encrypt the disk on your host.
Free to download is not free to run. Add the server bill to the hours spent on updates, backups and the odd outage, then compare that total with a cloud plan from $4.99 a month.
What is included
The AI agent, inbox, all nine channels, knowledge, tickets, help center, journeys and lead capture, with no message caps from us.
The CLI, the MCP server and access tokens are part of the hosted, commercial edition. So are our managed AI model and one-click Meta sign-in; self-hosted, you use your own key and your own Meta app.
Self-hosting questions
Is it really free?
The software is. You pay for your servers and for any AI provider you use.
What does the AI framework send home?
Its telemetry is off by default. Message text goes only to the model provider you configure.
Can I run it without a domain?
Yes, on http://localhost for a trial. Customers need HTTPS, so add a domain before you put the widget on a live site.
Do I need Firebase?
No. It is only for push notifications to your team. Without it, the dashboard still shows new chats.
How do I update?
Back up, then run stop and start. Start pulls the newest images and the backend runs any migrations as it boots.
Can I use S3 for files?
Yes. Set the S3 settings in backend/.env and uploads go to your bucket instead of the local volume.
Should I self-host at all?
Our essay on what self-hosting really buys you covers the legal and cost side, and when the cloud is the better call.