Skip to main content

​
Quickstart Guide

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

Use the hosted service

Sign up and manage everything from the dashboard or the CLI. No infrastructure to run. Best for most people.

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.
1

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.
2

Sign up (or log in)

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.
3

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>
4

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).
1

Install the self-host CLI

npm install -g chattermate-deploy
2

Create Project

Initialize a new ChatterMate project:
chattermate-deploy init my-chattermate-project
cd my-chattermate-project
3

Start Services

Start all services with Docker:
chattermate-deploy start
4

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

​
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

​
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

​
Database Setup

1

Create Database

Create a PostgreSQL database and enable the vector extension:
CREATE DATABASE chattermate;
\c chattermate
CREATE EXTENSION vector;
2

Run Migrations

Apply the database migrations:
alembic upgrade head

​
Running the Application

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

​
Verify Installation

  1. Open your browser and navigate to http://localhost:8000/docs to view the API documentation
  2. Visit http://localhost/ to access the web interface (CLI) or http://localhost:3000 (manual setup)
  3. 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