TOR Messenger

I built this so anyone can clone,

run, and chat over Tor with persistent

identity and chat history.

---

Features

• Invite-code based encrypted chat over Tor hidden services.
• Persistent onion address on every run (same address is reused).
• Persistent chat history per room (encrypted at rest).
• Local backups are created automatically at startup.
• Cross-platform launch scripts:
  • Linux/macOS: run.sh
  • Windows: run.bat
• Separate Windows desktop package with bundled Tor and a GUI launcher: windows_gui/
• Master passphrase protection for local room keys.

Safety by design

• The app writes only inside the project folder (data/, .venv/).
• No destructive system commands are used.
• No admin/system files are modified.
• No global services are overwritten.

Requirements

• Python 3.10+
• Tor executable available on PATH

Install and run

1. Clone the repo.
2. Open terminal in project root.
3. Run:

Linux/macOS:

./run.sh

Windows (Command Prompt or PowerShell):

run.bat

4. Enter your master passphrase when prompted (first run creates it).
5. Open:

http://127.0.0.1:5000

Windows desktop .exe

If you want a traditional Windows app experience instead of terminal launch:

• use the packaged desktop build under windows_gui/
• the desktop package bundles Tor
• the user can launch it from a shortcut and does not need to open terminal
• the launcher shows the local URL and onion URL

Current Windows package outputs:

• windows_gui/dist/TOR Messenger Desktop.exe
• windows_gui/tor-messenger-desktop-windows.zip

First-time chat flow

1. Click Generate Code to create a room and invite code.
2. Share that code with the other person securely.
3. They paste it in Join With Code.
4. Both sides send messages and sync.

Alias behavior (fixed)

• I set my alias once per room.
• After first message, alias is saved and locked for that room.
• On future opens, my alias loads automatically from backup.

Persistence and backups

The app keeps data locally and reuses it every run:

• Chat database: data/chat.db
• Encrypted logs: data/logs/<room_id>.log
• Onion identity keys: data/tor/hidden_service/
• Auto startup backups: data/backups/startup-*/

Because data/tor/hidden_service/ is persistent, my onion address remains the same across runs.

Recoverability

To restore on another machine, copy:

• data/chat.db
• data/logs/
• data/tor/hidden_service/

Then run the app there with the same project structure.

Troubleshooting

If sync says peer onion is unreachable:

1. Keep both apps running.
2. Wait for Tor bootstrap to complete.
3. Check data/tor/tor.log for Bootstrapped 100%.
4. Press Sync again.

Main files

• Launcher: launcher.py
• Linux/macOS runner: run.sh
• Windows runner: run.bat
• Windows desktop package: windows_gui/
• Backend: tor_messenger/app.py
• Frontend: web/index.html, web/styles.css, web/app.js