https://github.com/rahul-deka/gupsup
Secure terminal chat app
https://github.com/rahul-deka/gupsup
chat python secure terminal websocket
Last synced: 2 months ago
JSON representation
Secure terminal chat app
- Host: GitHub
- URL: https://github.com/rahul-deka/gupsup
- Owner: rahul-deka
- Created: 2025-08-07T09:33:13.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-09-15T10:31:47.000Z (9 months ago)
- Last Synced: 2025-10-30T23:47:20.596Z (8 months ago)
- Topics: chat, python, secure, terminal, websocket
- Language: Python
- Homepage: https://pypi.org/project/gupsup/
- Size: 72.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# gupsup
A secure terminal-based chat application with image sharing for real-time communication — right from your terminal.
[](https://pepy.tech/projects/gupsup)
[](https://pypi.org/project/gupsup/)
[](https://pypi.org/project/gupsup/)
Learn more and explore detailed info at [gupsup-cli](https://gupsup-cli.vercel.app/)
Looking for the server? See [gupsup-server](https://github.com/rahul-deka/terminalchat-server)
## ⚡ Quick Start
```bash
pip install gupsup
gupsup
```
[](https://pypi.org/project/gupsup/)
That's it! Start chatting instantly.
## Features
- **Zero-friction setup** - Just run `gupsup` and start chatting instantly
- **End-to-end encryption** - AES-256-GCM encryption with PBKDF2 key derivation
- **Image sharing** - Send and receive images (PNG, JPG, GIF, BMP, WebP) up to 2MB
- **Secure channels** - Create private rooms with shareable 6-character codes
- **Auto-reconnection** - Handles network issues gracefully with smart retry logic
- **Cross-platform** - Works seamlessly on Windows, macOS, Linux
- **No account required** - Completely anonymous, no sign-up needed
- **Smart image handling** - Automatic format detection, metadata preservation
## Usage
```bash
# Install once
pip install gupsup
# Run anywhere
gupsup
```
### Example Session
```
gupsup - Secure Communication Channel
Channel code (or 'new' to create): new
Channel created: a4b2c1
Share code 'a4b2c1' with others to join
Username: qwerty
Establishing connection...
🟢 Connected to channel: a4b2c1
Commands:
- Type messages to send
- '/image ' to send image
- '/save [filename]' to save last received image
- 'quit' to exit
qwerty: Hello world!
mrrobot: Hey there!
qwerty: /image photo.jpg
Processing image...
Image sent: photo.jpg
alice sent an image:
└─ File: vacation.png
└─ Type: image/png
└─ Size: 245.3KB
└─ Use '/save vacation.png' to save this image
qwerty: /save my_vacation.png
Image saved to: e:\downloads\my_vacation.png
qwerty: quit
Terminating session.
```
## How It Works
1. **Create or join** a secure channel with a 6-character code
2. **Share the code** with people you want to chat with
3. **Chat securely** - messages are only sent to your channel
4. **No persistence** - messages disappear when you disconnect
## Security & Privacy
- **Military-grade encryption** - AES-256-GCM with authenticated encryption
- **Secure key derivation** - PBKDF2 with 100,000 iterations and SHA-256
- **Channel isolation** - Each channel has its own unique encryption key
- **Zero server knowledge** - Server cannot decrypt messages or images
- **Ephemeral messaging** - No message storage, everything is real-time only
- **Complete anonymity** - No accounts, no tracking, no data collection
- **Perfect forward secrecy** - Unique nonces ensure message security
### Encryption Technical Details
- **Algorithm**: AES-256-GCM (Galois/Counter Mode)
- **Key Size**: 256-bit encryption keys
- **Nonce**: 96-bit random nonce per message
- **Authentication**: Built-in message authentication
- **Key Derivation**: PBKDF2-HMAC-SHA256 with 100k iterations
### Development Install
```bash
# Clone the repository
git clone https://github.com/rahul-deka/gupsup.git
cd gupsup
# Install in development mode
pip install -e .
# Run the application
gupsup
```
### Server Setup (Optional)
```bash
# For hosting your own server
git clone https://github.com/rahul-deka/gupsup-server.git
cd gupsup-server
pip install -r requirements.txt
python main.py
```
## Available Commands
### Chat Commands
- **Send message**: Simply type your message and press Enter
- **Exit**: `quit`, `exit`, `/quit`, or `/exit`
- **Force quit**: Press `Ctrl+C`
### Image Commands
- **Send image**: `/image `
- Example: `/image ~/Pictures/photo.jpg`
- Example: `/image C:\Users\Me\Desktop\image.png`
- **Save received image**: `/save [custom_filename]`
- Example: `/save` (uses original filename)
- Example: `/save my_photo.jpg` (custom filename)
### Image Support Details
| Feature | Details |
|---------|---------|
| **Formats** | PNG, JPG/JPEG, GIF, BMP, WebP |
| **Size Limit** | 2MB per image (optimized for reliability) |
| **Encryption** | Full end-to-end encryption like text messages |
| **Metadata** | Filename, size, and MIME type preserved |
| **Validation** | Automatic format detection and size checking |
#### Image Usage Examples
```bash
# Send images
/image path/photo.png
# Save received images
/save # Save with original name
/save my_image.jpg # Save with custom name
/save folder/image.png # Save to specific path
```
## 🛠️ Troubleshooting
Connection Issues
**Symptoms**: Connection timeouts, frequent disconnects
- First connection may be slow (server waking up)
- Retry connection - should be faster on subsequent attempts
- Check your internet connection
- Verify the server is accessible
Image Problems
**Large images failing**:
- Ensure image is under 2MB
- Use image compression tools if needed
- Supported formats: PNG, JPG, GIF, BMP, WebP
**Can't save images**:
- Check file permissions in save directory
- Ensure sufficient disk space
- Try saving to a different location
Encryption Issues
**Messages appear garbled**:
- Ensure all users have the same channel code
- Verify everyone is using the latest version
- Try creating a new channel
**Can't see messages**:
- Confirm you're in the correct channel
- Check if other users are actually connected
- Restart the application
Platform-Specific Issues
**Windows**:
- Use PowerShell or Command Prompt
- Ensure Python 3.8+ is installed
**macOS/Linux**:
- Use Terminal application
- May need to install Python development headers
- Check file path permissions for images
## 📦 Package Information
| Detail | Information |
|--------|-------------|
| **Package Name** | `gupsup` on PyPI |
| **CLI Command** | `gupsup` |
| **Python Version** | 3.8+ required |
| **Dependencies** | `websockets>=11.0`, `cryptography>=3.0.0` |
| **Size** | Ultra-lightweight (~50KB) |
| **License** | MIT License |
| **Latest Version** | 1.1.0 (with image support) |
## Architecture
```
┌─────────────────┐ WebSocket ┌──────────────────┐ Channel ┌─────────────────┐
│ Terminal │ ←─────────────→ │ FastAPI │ ←──────────→ │ Channel │
│ Client │ (Encrypted) │ Server │ Management │ Manager │
│ (gupsup) │ │ │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
↑ ↑
AES-256-GCM Relay Only
Encryption (Cannot Decrypt)
```
### How Messages Flow:
1. **Client A** encrypts message with channel key
2. **Server** receives encrypted message (cannot decrypt)
3. **Server** relays encrypted message to **Client B**
4. **Client B** decrypts message with same channel key
---
**Simple. Secure. Terminal-native.**
MIT License - use freely, contribute back.
**[Rahul Deka](https://rahul-deka.vercel.app/)**