Watch a quick demo of Ephemeral Chat in action!
Here’s a sneak peek at the app interface:
- GitHub Actions: Automated workflows for building, testing, and analyzing code.
- CodeQL: Security analysis for JavaScript/Node.js and Java/Android code.
- Gradle Build: Ensures Android app builds successfully on every push.
A secure, anonymous, and ephemeral chat application with self-destructing messages. Installable as a Progressive Web App (PWA) for native-like experience.
A secure, anonymous, and ephemeral chat application with self-destructing messages. Installable as a Progressive Web App (PWA) for native-like experience. Can also be distributed as a Trusted Web Activity (TWA) for Android via the Play Store.
- Real-Time Messaging: Lightning-fast message delivery using Socket.io
- 📞 Voice Calls: Crystal clear peer-to-peer audio calls using WebRTC
- 🎤 Universal Voice Notes: Record audio on any device (iOS, Android, Desktop) and play it anywhere.
- Technical Feat: Server-side conversion to AAC (.m4a) ensures seamless playback on Safari and all modern browsers.
- 📸 Image Sharing: Share images securely with view-once capability
- Self-Destructing Messages: Messages disappear after being read or after a set time
- Instant Room Creation: Generate unique chat rooms instantly with 6-digit codes
- 🚪 Knock-to-Join System: Guests enter a lobby and must be approved by the host
- 👑 Host Controls: Room creators can approve or deny entry to pending guests
- 🔄 Host Handover: Automatic ownership transfer if the host leaves
- Anonymous Participation: No accounts or personal information required
- Auto-Cleanup: Rooms automatically close after inactivity
- 🔐 Client-Side Encryption (E2EE): Messages are encrypted in the browser using AES-GCM. The key is in the URL hash and never reaches the server.
- No Message Persistence: Messages are never stored permanently on the server
- 🔒 Password Protection: Optional password protection for rooms
- 🤖 Bot Protection: Integrated Proof-of-Work CAPTCHA to prevent spam
- 🛡️ Brute Force Protection: Failed attempt tracking and automatic lockout
- ✅ Input Validation: XSS prevention and credential sanitization
- Installable: Add to home screen on any device
- Native Feel: App-like experience with splash screen and theme colors
- Offline Capable: Core shell works offline
- React: UI library
- Vite: Build tool and dev server
- Tailwind CSS: Utility-first CSS framework
- Socket.io Client: Real-time communication
- WebRTC: Peer-to-peer audio calls
- Lucide React: Beautiful icons
- Trusted Web Activity (TWA): The project includes an
android/directory with a Gradle project, allowing the PWA to be packaged and distributed as a native Android app on the Google Play Store.
- Node.js & Express: Server runtime and framework
- Socket.io: Real-time event-based communication
- FFmpeg: Audio processing and conversion (with static binaries)
- @cap.js: Proof-of-Work CAPTCHA system
- Redis (Optional): For scaling across multiple instances
- Universal Compatibility: Automated conversion of WebM/Ogg (Android/Chrome) to AAC (iOS/Safari).
- Smart Copy: Intelligent detection of AAC inputs to avoid unnecessary re-encoding.
- Robust Normalization: Auto-correction of sample rates and timestamps for glitch-free playback.
- Vite PWA Plugin: PWA generation and management
- Workbox: Service worker libraries
- Node.js (v16 or higher)
- npm (v8 or higher) or yarn
- (Optional) Redis for production deployments
-
Clone the repository
git clone https://github.com/cLLeB/ephemeral-chat.git cd ephemeral-chat -
Install dependencies
# Install root dependencies npm install # Install client dependencies cd client && npm install && cd ..
-
Set up environment variables Copy the existing
.envfile or create one with these settings:# Server Configuration PORT=3001 NODE_ENV=development # Security Settings (already configured) INACTIVITY_TIMEOUT_MINUTES=10 MAX_FAILED_ATTEMPTS=5 LOCKOUT_DURATION_MINUTES=10 ROOM_CODE_SALT=your-secure-salt-here CAP_SECRET=your-captcha-secret-key # Room Settings ROOM_EXPIRY_MINUTES=60 INVITE_TOKEN_EXPIRY_MINUTES=25 MAX_MESSAGES_PER_MINUTE=30
-
Start the development server
# Start both client and server concurrently npm run dev -
Access the application
- Frontend: http://localhost:5173 (Vite dev server)
- Backend API: http://localhost:3001
Your chat application is a fully-featured PWA that can be installed on any device!
- Open in browser and visit the live demo
- Look for install prompt in your browser's address bar
- Click "Install" or "Add to Home Screen"
- Launch from home screen like a native app
- Offline functionality - Chat works without internet
- Native app feel - Custom splash screen and theme colors
- Auto-updates - Always runs the latest version
- Fast loading - Cached assets for instant access
- User Guide - Complete guide for end users
Contributions are welcome! Here's how you can help:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and test them thoroughly
- Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
See our Contributing Guidelines for more details.
Distributed under the GNU General Public License v3. See LICENSE for more information.
- Project Link: https://github.com/cLLeB/ephemeral-chat
- Live Demo: https://ephemeral-chat-7j66.onrender.com/
- Email: kyereboatengcaleb@gmail.com
- Socket.IO for real-time communication
- React for the amazing UI framework
- Vite for fast development experience
- Tailwind CSS for utility-first CSS
- Render for hosting
- Progressive Web Apps for native-like web experience
ephemeral-chat/
├── android/ # Android TWA project (wraps the PWA for Play Store distribution)
│ ├── app/ # Android app module
│ ├── build.gradle # Gradle build files
│ ├── gradlew, gradlew.bat # Gradle wrapper scripts
│ └── ... # Other Android/Gradle files
├── client/ # React frontend (Vite + PWA)
│ ├── public/ # PWA assets & manifest
│ │ ├── manifest.json # Web app manifest
│ │ ├── sw.js # Service worker
│ │ └── *.png # PWA icons
│ ├── src/ # React source code
│ │ ├── components/ # Reusable UI components
│ │ ├── hooks/ # Custom React hooks
│ │ ├── services/ # API integrations
│ │ └── utils/ # Helper functions
│ ├── vite.config.js # Vite configuration with PWA
│ └── package.json
│
├── server/ # Express + Socket.IO backend
│ ├── auth-utils.js # Authentication utilities
│ ├── index.js # Server entry point
│ ├── rooms.js # Room management
│ ├── security.js # Security middleware
│ └── utils.js # Utility functions
│
├── docs/ # Documentation
│ └── USER_GUIDE.md # User guide
│
├── .env # Environment variables
├── package.json # Root dependencies
└── README.md
This project can be distributed as a native Android app using Trusted Web Activity (TWA). The android/ directory contains a Gradle project that wraps the PWA, allowing you to publish the app on the Google Play Store for a seamless, native-like experience.
cd android
./gradlew assembleDebug # or assembleRelease for productionThe output APK will be in android/app/build/outputs/apk/.
You can customize the TWA settings and assets in the android/ directory as needed.
The application uses the following environment variables (see .env file):
# Server
PORT=3001
NODE_ENV=development
# Security (REQUIRED)
INACTIVITY_TIMEOUT_MINUTES=10
MAX_FAILED_ATTEMPTS=5
LOCKOUT_DURATION_MINUTES=10
ROOM_CODE_SALT=your-secure-salt-here
# Room Settings
ROOM_EXPIRY_MINUTES=60
INVITE_TOKEN_EXPIRY_MINUTES=5
MAX_MESSAGES_PER_MINUTE=30
# Redis (optional)
# Redis (optional)
# REDIS_URL=redis://localhost:6379
### Client Environment Variables
Create a `.env` file in the `client` directory for frontend configurations:
```env
# WebRTC ICE Servers (Optional - for custom TURN/STUN servers)
VITE_ICE_SERVERS=[{"urls":"stun:stun.l.google.com:19302"}]
### Available Scripts
- `npm run dev`: Start development servers (client + server)
- `npm run server`: Start backend server only
- `npm run client`: Start frontend client only
- `npm run build`: Build frontend for production
- `npm start`: Start production server
## 🔧 Development
### Frontend Development
The client is built with React and Vite:
```bash
cd client
npm run dev # Starts on http://localhost:5173
The server uses Node.js with Express and Socket.IO:
npm run server # Starts on http://localhost:3001GET /- Health checkPOST /api/rooms- Create roomGET /api/rooms/:code- Get room info- WebSocket events:
joinRoom,sendMessage,leaveRoom
The application is currently deployed on Render:
- Frontend: Static site deployment
- Backend: Web service
- URL: https://ephemeral-chat-7j66.onrender.com/
The deployment uses the render.yaml configuration for automatic builds and deployments.
Built with ❤️ for privacy-focused communication