A self-hosted, cross-platform desktop chat app. Real-time messaging, group chats, and VoIP calls — all in one open-source client.
A full-featured messaging client built around real-time WebSocket communication, running entirely on your own infrastructure.
Instant WebSocket-based delivery with typing indicators, live online presence, and full message history retrieval.
Create multi-user rooms, invite participants, and manage group membership — all from within the client.
In-app voice calls powered by LiveKit. Peer-to-peer audio with signalling handled through the WebSocket server.
Search through your conversations to jump back into any chat instantly. Archive inactive chats to keep your list clean.
Token-based auth with email verification, persistent login across sessions, password reset by email, and rate-limited endpoints.
Update your username or email, resend verification, and delete or deactivate your account — all directly from the client.
Download the client for your platform, or self-host the backend on your own server.
Go to the GitHub releases page and download the build for your platform.
# Windows ChatCLI Setup 0.4.1-beta.exe # installer (recommended) ChatCLI-0.4.1-beta-win-portable.zip # Linux chatcli_0.4.1-beta_amd64.deb # Debian / Ubuntu chatcli_0.4.1-beta_linux_portable.zip
Run the installer (Windows) or install the package (Linux). No additional dependencies required.
# Linux .deb sudo dpkg -i chatcli_0.4.1-beta_amd64.deb
Register an account or log in. The client connects to the hosted server at chat.puam.be by default — no configuration needed.
Make sure the following are installed before continuing.
python3 --version # >= 3.12.0 mariadb --version # >= 10.6 git --version # Install MariaDB if needed (Debian / Ubuntu) sudo apt install mariadb-server sudo systemctl start mariadb
git clone https://github.com/FrostMantis/ChatCLI.git cd ChatCLI/src/backend
pip3 install -r requirements.txt
Creates the database, tables, and app user. Also generates a .env with safe defaults on first run.
python3 install_update_server.py
.envEdit the generated .env and set your public URL, email credentials, and LiveKit keys.
PUB_URL=your.domain.com EMAIL_USER=your@email.com EMAIL_PASSWORD=app_password LIVEKIT_URL=ws://your-livekit-host:7880 LIVEKIT_KEY=your_key LIVEKIT_SECRET=your_secret
run_server.py launches both the HTTP API (port 5123) and WebSocket server (port 8765) in one command. Press Ctrl+C to stop both.
python3 run_server.py
Download and install the following before continuing.
python --version # >= 3.12.0 — python.org mariadb --version # >= 10.6 — mariadb.org git --version # git-scm.com
git clone https://github.com/FrostMantis/ChatCLI.git cd ChatCLI\src\backend
pip install -r requirements.txt
Creates the database, tables, and app user. Also generates a .env with safe defaults on first run.
python install_update_server.py
.envEdit the generated .env and set your public URL, email credentials, and LiveKit keys.
PUB_URL=your.domain.com EMAIL_USER=your@email.com EMAIL_PASSWORD=app_password LIVEKIT_URL=ws://your-livekit-host:7880 LIVEKIT_KEY=your_key LIVEKIT_SECRET=your_secret
run_server.py opens two CMD windows — one for the HTTP API (port 5123) and one for the WebSocket server (port 8765).
python run_server.py
Architecture overview, API reference, and environment configuration for ChatCLI.
The project is split into two independent parts under src/.
src/backend/ — Python server (Flask API + FastAPI WebSocket)src/backend/app/routes/ — HTTP route blueprintssrc/backend/app/services/ — business logic layersrc/backend/app/websockets/ — FastAPI WebSocket server (port 8765)src/backend/app/database/ — MariaDB connection helperssrc/client/ChatCLI/ — Electron clientsrc/client/ChatCLI/src/renderer/ — UI pages, scripts, stylessrc/client/ChatCLI/src/main/ — Electron main process| Route | Method | Description |
|---|---|---|
| / | GET | Landing page |
| /verify-connection | GET POST | Check server reachability |
| /subscribe | POST | Register email for notifications |
/user| Route | Method | Description |
|---|---|---|
| /user/register | POST | Create account, send verification email |
| /user/verify-email | POST | Confirm email with code |
| /user/resend-verification | POST | Resend verification email |
| /user/login | POST | Authenticate, receive session token |
| /user/refresh-token | GET | Rotate refresh token |
| /user/reset-password-request | POST | Trigger password reset email |
| /user/reset-password | GET POST | Complete password reset |
/chat| Route | Method | Description |
|---|---|---|
| /chat/fetch-chats | POST | List user's chats |
| /chat/create-chat | POST | Start a new 1:1 conversation |
| /chat/create-group | POST | Create a group chat |
| /chat/add-members | POST | Add participants to a group |
| /chat/remove-members | POST | Remove participants from a group |
| /chat/messages | POST | Retrieve message history |
| /chat/archive | POST | Archive a chat |
| /chat/unarchive | POST | Restore an archived chat |
| /chat/fetch-archived | POST | List archived chats |
All chat endpoints require a session_token field in the request body. Responses are JSON; errors return an error field.
wss://ws.chat.puam.be/ws · local: ws://localhost:8765/ws
Send immediately after connecting:
{"type": "auth", "token": "<session_token>"}| Action | Required fields | Description |
|---|---|---|
| join_chat | chatID | Subscribe to a chat room |
| leave_chat | chatID | Unsubscribe from a chat room |
| post_msg | chatID, text | Send a message |
.env keys| Key | Description |
|---|---|
| FLASK_ENV | dev (debug mode) or prod (Waitress) |
| THREADS | Waitress worker threads (production only) |
| DB_HOST / DB_PORT | MariaDB connection (default: localhost:3306) |
| DB_NAME | Database name (default: chatcli) |
| DB_USER / DB_PASSWORD | App DB credentials (auto-generated by installer) |
| FLASK_SECRET_KEY | Session signing key (auto-generated by installer) |
| EMAIL_USER / EMAIL_PASSWORD | SMTP credentials for verification emails |
| PUB_URL | Publicly reachable hostname of the server |
| LIVEKIT_KEY / LIVEKIT_SECRET | LiveKit API credentials for VoIP |
| LIVEKIT_URL | WebSocket URL of your LiveKit instance |
| IGNORE_EMAIL_VERIF | Set true to skip email verification (dev only) |
Check that both main.py (port 5123) and app/websockets/main.py (port 8765) are running. Also verify PUB_URL in .env matches your server's hostname.
mariadb.OperationalError on startupMariaDB is not running or the credentials in .env don't match. Re-run install_update_server.py with root access enabled (ROOT_ACCESS=true).
Set IGNORE_EMAIL_VERIF=true to bypass email verification during development. For production, use an app-specific password with your email provider.
VoIP is a beta feature. Ensure your LiveKit server is reachable at the URL set in LIVEKIT_URL and that LIVEKIT_KEY / LIVEKIT_SECRET are correct.
ChatCLI is an independent open-source project — a fully self-hosted, cross-platform messaging client built from scratch.