A lightweight, terminal-based real-time chat platform built with Python, Textual, asyncio, and SQLite. Features DM channels, server communities, persistent chat logs, unread notifications, and TLS transport encryption.
Chatting in a server
Chatting with an user
- Python 3.10+
- OpenSSL (for TLS certificate generation)
Clone the repository and install the dependencies:
git clone https://github.com/MrGidor/Spectre-Community.git
cd Spectre-Community
# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install required packages
pip install textual rich
Run server.py. The server automatically handles database initialization (chat_data.db) and self-signed TLS certificate generation (server.crt, server.key) on its first run:
Default port:
8888
python3 server.py
On startup, the server logs its SHA-256 TLS Fingerprint:
======================================================================
[*] Encrypted Spectre Community server online on 0.0.0.0:8888
[*] SHA-256 Fingerprint: 4a8f...
[*] Share this fingerprint out-of-band with clients for initial trust.
======================================================================Tip for Admins: Share this hash out-of-band (e.g., via Discord/Matrix) with users connecting for the first time so they can verify it in their TOFU prompt modal.
Open a new terminal window, activate your virtual environment, and run:
python3 client.py
To run the Spectre server continuously on a VPS (e.g., DigitalOcean, Hetzner, Linode):
- Configure Firewall: Open TCP port
8888:
sudo ufw allow 8888/tcp
sudo ufw reload- Create a Systemd Service: Create
/etc/systemd/system/spectre.service:
[Unit]
Description=Spectre Community Server
After=network.target
[Service]
Type=simple
User=your_username
WorkingDirectory=/path/to/Spectre-Community
ExecStart=/path/to/Spectre-Community/venv/bin/python3 /path/to/Spectre-Community/server.py
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
- Start the Service:
sudo systemctl daemon-reload
sudo systemctl enable --now spectre
- Configure Firewall: Open TCP port
8888:
sudo ufw allow 8888/tcp
sudo ufw reload- Build:
docker build . -t spectre-chat- Run:
docker run -d -p 8888:8888 spectre-chat| File | Scope | Description |
|---|---|---|
config.json |
Client | Stores host, port, username, and anchored server TLS fingerprint. |
identity.json |
Client | Contains your unique cryptographic identity token. Ties your username to your identity on servers and can be transferred across computers. |
server_config.json |
Server | Server port and binding IP configuration. |
chat_data.db |
Server | SQLite database housing channels, messages, user mappings, and servers. |
server.crt / .key |
Server | TLS certificates auto-generated via OpenSSL. |
Inside the client TUI:
| Command | Description |
|---|---|
/list |
Show your friends, servers, and channels |
/target @username |
Switch active chat target to a DM |
/target code |
Switch active chat target to a Server Code |
/addfriend @username |
Add a user to your friends list |
/createserver <name> |
Create a new server and receive invite code |
/join <code> |
Join a server using an invite code |
/createchannel <name> |
Create a channel in current server target |
/removechannel <name> |
Removes a channel in the current server target |
/channel <name> |
Switch active channel within the current server |
| Useful Hotkeys | Description |
|---|---|
shift+dragclick |
Text selection |
shift+ctrl+c |
Copy selected text |
shift+ctrl+v |
Paste clipboard text |
ctrl+q |
Exit Spectre |
Spectre uses explicit protocol version matching (MAJOR.MINOR):
- Major Version Mismatch (
2.xvs1.x): The server will reject connections withPROTOCOL_MISMATCH. This enforces mandatory security updates across both server and client software. - Minor Version Updates: Backward-compatible feature additions or non-breaking protocol enhancements.
- Release Versioning vs. Protocol Versioning: Application release versions (
v1.4) and protocol versions (2.0) are decoupled. The release version tracks application updates, while the protocol version strictly enforces network compatibility and security boundaries.
- In-Transit TLS Encryption: All client-server traffic is encrypted using TLS (
sslcontext). - Trust On First Use (TOFU): Protects against Man-in-the-Middle (MITM) attacks. Upon initial connection, the client displays the server's SHA-256 TLS certificate fingerprint for out-of-band verification and anchors it locally in
config.json. - Token-Based Device Anchoring: User identity tokens (
identity.json) are autogenerated via UUIDv4 and locked to your device upon initial registration to prevent unauthorized username impersonation. - Storage: Messages and server metadata are stored locally on the hosting server in SQLite (
chat_data.db).