Chat Directly. Own Your Data.

ChatBox is a lightweight peer-to-peer desktop chat application. Connect with friends over the internet without relying on third-party messaging services.

Download Now View on GitHub
💻 🔗 💻

Why Choose ChatBox?

Everything you need for private, direct messaging

🔗

Peer-to-Peer

Direct TCP connections between users. No intermediary servers, no data collection.

💾

Local Storage

All messages stored securely on your computer. Complete ownership of your data.

🌙

Dark & Light Mode

Toggle between appearance modes. Comfortable viewing in any lighting condition.

🔐

Secure

Local credential hashing. Direct connections. No cloud dependency.

✨

Modern UI

Built with CustomTkinter. Professional desktop experience across platforms.

⚡

Fast & Lightweight

Minimal dependencies. Quick startup. Low system resource usage.

Getting Started in 3 Steps

1

Download & Install

Download the executable or install from source. Works on Windows, macOS, and Linux.

2

Create a Connection

Add a peer by entering their IP address and port. Save the connection for future use.

3

Start Chatting

Send messages that sync with your peer in real-time. Full chat history saved locally.

Installation Guide

Choose the method that works best for you

📦 Download Executable (Easiest)

For Windows users with no Python experience

  1. Go to GitHub Releases
  2. Download ChatBox.zip
  3. Extract the ZIP file
  4. Double-click ChatBox.exe to run
  5. Login with default credentials:
    Username: test
    Password: pwd
✓ No Python installation required - everything is bundled!

🐍 Install from Source

For Python developers

  1. Install Python 3.9+ from python.org
  2. Clone the repository:
    git clone https://github.com/SantanaRichie/ChatBox.git
    cd ChatBox
  3. Install dependencies:
    pip install -r requirements.txt
  4. Run ChatBox:
    python scripts/login.py
✓ Works on Windows, macOS, and Linux

🔨 Build Your Own Executable

For advanced users

  1. Follow steps 1-3 of "Install from Source" above
  2. Build the executable:
    python build_app.py
  3. Find your executable:
    dist/ChatBox/ChatBox.exe
  4. Test it by double-clicking ChatBox.exe
  5. Share the dist/ChatBox/ folder with others
✓ Customize and build your own version

Quick Start: Get Your Peer's Information

Before chatting, exchange this information with your friend:

On Windows (Command Prompt):
ipconfig

On macOS/Linux (Terminal):
ifconfig

Look for:
"IPv4 Address" (usually 192.168.x.x or 10.x.x.x)

Default Port: 5000

Technical Specs

Language
Python 3.9+
GUI Framework
CustomTkinter 5.2.1
Database
SQLite
Networking
TCP Sockets
Authentication
MD5 Hashing
License
Open Source

Your Privacy Matters

✓

Local Storage Only

All chat data stored on your computer. No cloud servers tracking your messages.

✓

Credential Hashing

Passwords hashed with MD5 before storing. Never stored in plain text.

✓

Direct Connections

Peer-to-peer communication. No intermediary services or data collection.

✓

Full Control

You control when data is accessed and shared. Export or delete anytime.

Ready to Chat?

Choose your download option

📦 Pre-Built Executable

Download the ready-to-use Windows executable. No Python installation required.

Download .exe

🐍 Install from Source

Clone the repository and install dependencies with pip. Python 3.9+ required.

View Instructions

🔨 Build Your Own

Compile your own executable from source using our build automation script.

Build Guide

Frequently Asked Questions

Not if you download the pre-built .exe executable. It includes everything you need. If you want to install from source or build your own, Python 3.9 or higher is required.

ChatBox uses TCP sockets to establish direct connections between users. You need to know the peer's IP address and listening port. Both users must be running ChatBox and connected for messaging to work.

Chat data is stored locally on your computer in SQLite databases. Passwords are hashed with MD5. Currently, messages are transmitted in plain JSON. End-to-end encryption is on the roadmap.

ChatBox is cross-platform! You can install from source on any operating system that supports Python 3.9+. Follow the "Install from Source" option in the README.

Windows: Open Command Prompt and type ipconfig. Look for "IPv4 Address".

macOS/Linux: Open Terminal and type ifconfig. Look for "inet" address.

Currently, ChatBox supports one-to-one peer connections. Group chat support is on the roadmap for future versions.

Visit the GitHub Issues page to report bugs or request features. Contributions are welcome!

Yes! ChatBox is completely free and open-source. The code is available on GitHub for anyone to use, modify, or contribute to.