Quickstart Guide

There are two ways to run ChatterMate. Pick the one that fits you:

Use the hosted service

Self-host with Docker

Run the full ChatterMate stack on your own infrastructure with the self-host CLI.

Two different chattermate commands. The hosted CLI (pip install chattermate-cli) signs you up and manages agents/knowledge against the ChatterMate API. The self-host CLI (npm install -g chattermate-deploy) scaffolds and runs the Docker stack. They are separate tools.

Option A — Hosted service (fastest)

Create a free account and configure your first agent — no browser required.

Install the ChatterMate CLI

pip install chattermate-cli        # installs the `chattermate` command
# or: npm install -g chattermate-cli

See the CLI reference for pipx/uvx/npm options.

chattermate signup \
  --name "Acme Inc" \
  --domain acme.com \
  --admin-email you@acme.com
# password is prompted securely — you're logged in automatically

Prefer a browser? Sign up at app.chattermate.chat instead.

Create an agent & add knowledge

chattermate agent create --name "Support" --type customer_support -i "Be concise and friendly"
chattermate knowledge add-url --website https://docs.acme.com --agent-id <agent-id>

Go live

Embed the chat widget on your site, or let an AI agent drive everything via the MCP server.

AI Agent & Automation Quickstart

A single copy-paste flow from signup to a live widget — built for AI agents and CI pipelines.

Option B — Self-host with Docker

Run the entire stack on your own machine with the self-host CLI (chattermate-deploy).

Install the self-host CLI

npm install -g chattermate-deploy

Create Project

Initialize a new ChatterMate project:

chattermate-deploy init my-chattermate-project
cd my-chattermate-project

Start Services

Start all services with Docker:

chattermate-deploy start

Access Dashboard

Open your browser and visit:

Frontend Dashboard: http://localhost/
Backend API: http://localhost:8000
API Documentation: http://localhost:8000/docs

Self-host CLI commands

chattermate-deploy init <project-name>    # Initialize a new project
chattermate-deploy reset                  # Reset and cleanup project

chattermate-deploy start                  # Start all services
chattermate-deploy stop                   # Stop all services
chattermate-deploy status                 # Check service status
chattermate-deploy logs                   # View service logs

Manual Installation

If you prefer to set up ChatterMate manually or need custom configuration:

Backend Setup

# Clone the repository
git clone https://github.com/chattermate/chattermate
cd chattermate/backend

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy and configure environment variables
cp .env.example .env
# Edit .env file with your configurations

# Copy .env.example to .env and configure these values:
DATABASE_URL=postgresql://user:pass@localhost:5432/chattermate
FIREBASE_CREDENTIALS=firebase-credentials.json
JWT_SECRET_KEY=your-secret-key
CONVERSATION_SECRET_KEY=yoursecretkey
ENCRYPTION_KEY=encryption.key
CORS_ORIGINS=["https://yourdomain.com"]

Frontend Setup

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Copy and configure environment variables
cp .env.example .env
# Edit .env file with your configurations

# Copy .env.example to .env and configure these values:
VITE_API_URL=http://localhost:8000
VITE_WS_URL=ws://localhost:8000

Database Setup

Create Database

Create a PostgreSQL database and enable the vector extension:

CREATE DATABASE chattermate;
\c chattermate
CREATE EXTENSION vector;

Run Migrations

Apply the database migrations:

alembic upgrade head

Running the Application

# Start the backend server
uvicorn app.main:app --reload --port 8000

# Start the frontend development server
npm run dev

Verify Installation

Open your browser and navigate to http://localhost:8000/docs to view the API documentation
Visit http://localhost/ to access the web interface (CLI) or http://localhost:3000 (manual setup)
Try sending a test message in the chat widget

Next Steps

Setup Organization

Setup new organization

Configure AI

Configure AI provider

Customize AI Agent

Customizing AI agent

Knowledge Base

Adding knowledge to AI agent

Testing

Testing AI agent

Widget Integration

Adding chat widget to the website

Human Agents

Adding Human Agent

Roles & Permissions

Managing Roles and Permission

Chat Management

Managing Customer chat and Taking over chat

Getting Started

Features

Channels

Developer Tools

Deployment

Quickstart: Launch Your AI Support Agent in 5 Minutes

Quickstart Guide

Use the hosted service

Self-host with Docker

Option A — Hosted service (fastest)

AI Agent & Automation Quickstart

Option B — Self-host with Docker

Self-host CLI commands

Manual Installation

Backend Setup

Frontend Setup

Database Setup

Running the Application

Verify Installation

Next Steps

Setup Organization

Configure AI

Customize AI Agent

Knowledge Base

Testing

Widget Integration

Human Agents

Roles & Permissions

Chat Management

​Quickstart Guide

Use the hosted service

Self-host with Docker

​Option A — Hosted service (fastest)

AI Agent & Automation Quickstart

​Option B — Self-host with Docker

​Self-host CLI commands

​Manual Installation

​Backend Setup

​Frontend Setup

​Database Setup

​Running the Application

​Verify Installation

​Next Steps

Setup Organization

Configure AI

Customize AI Agent

Knowledge Base

Testing

Widget Integration

Human Agents

Roles & Permissions

Chat Management

Quickstart Guide

Option A — Hosted service (fastest)

Option B — Self-host with Docker

Self-host CLI commands

Manual Installation

Backend Setup

Frontend Setup

Database Setup

Running the Application

Verify Installation

Next Steps