A Tor frontend with retro and modern UI themes

About

Torminator is a desktop application that provides a graphical user interface for managing Tor connections. It allows you to easily start/stop Tor, select exit node countries, configure a WebTunnel bridge, and monitor connection progress.

Note: This is my first time trying Electron.js! I created this project for my personal usage and learned a lot about Electron development along the way. The codebase might be a bit messy in some places, particularly due to the hacks I needed to implement to support multiple themes. Each theme required its own HTML file and custom CSS handling for things like progress bars, which led to some code duplication and workarounds. Please keep this in mind if you're browsing the source code!

Features

• Country Selection - Choose your exit node from 16 different countries
• Multiple Themes - 7 retro and modern UI themes
• Bridge Support - Configure WebTunnel bridges for censorship circumvention
• Real-time Progress - Visual bootstrap progress indicator
• Live Logs - View Tor connection logs in real-time
• SOCKS Proxy - Exposes Tor on localhost:9050 for your applications

Available Themes

Theme	Description
Windows 98	Classic Windows 98 aesthetic using 98.css
Windows XP	Luna theme nostalgia with XP.css
Windows 7	Aero glass effects using 7.css
Windows 11	Modern Fluent design using windows-ui and some vanilla CSS
System 6	Classic Macintosh look using system.css
macOS	Apple's modern macOS styling, a Frankenstein of Puppertino, Photon, and some tinkering with the random CSS code I found online
Adwaita	GNOME's Adwaita theme, thanks to this Figma Project and Google's Gemini

FAQ

Why are there so many themes for a Tor client?

Honestly? I have absolutely no idea. It just... happened. Please don't ask me to justify this. I can't.

Prerequisites

Tor Expert Bundle

Torminator requires the Tor Expert Bundle binaries to function. You need to download and set them up manually.

Download

Download the Tor Expert Bundle from the official Tor Project website:

🔗 https://www.torproject.org/download/tor/

Choose the appropriate version for your operating system.

Installation

After downloading, extract the Tor Expert Bundle and place the following files in the tor/ directory of this project:

tor/
├── tor                    # Main Tor binary (executable)
├── torrc                  # Configuration file (auto-generated by app)
├── geoip                  # GeoIP database for IPv4
├── geoip6                 # GeoIP database for IPv6
├── libcrypto.so.3         # OpenSSL crypto library (Linux)
├── libevent-2.1.so.7      # Libevent library (Linux)
├── libssl.so.3            # OpenSSL SSL library (Linux)
└── pluggable_transports/  # Pluggable transport binaries
    ├── lyrebird           # WebTunnel/obfs4 transport
    ├── conjure-client     # Conjure transport (optional)
    └── pt_config.json     # Transport configuration

Note: On Windows and macOS, the shared library files (.so) will have different extensions (.dll for Windows, .dylib for macOS).

Make sure the tor and transport binaries are executable:

chmod +x tor/tor
chmod +x tor/pluggable_transports/lyrebird
chmod +x tor/pluggable_transports/conjure-client

Installation

1. Clone the repository

   git clone https://github.com/yourusername/torminator.git
   cd torminator

2. Install dependencies

   npm install

3. Set up Tor binaries (see Tor Expert Bundle section above)

4. Start the application

   npm start

Usage

1. Select a Country - Choose your desired exit node country from the dropdown
2. Configure Bridge - Enter your WebTunnel bridge in the text area
3. Start Tor - Click the "Start Tor" button to initiate the connection
4. Monitor Progress - Watch the progress bar as Tor bootstraps
5. Use the Proxy - Once connected, configure your applications to use localhost:9050 as a SOCKS5 proxy

Getting Bridges

If you need bridges to bypass censorship, you can obtain them from:

• https://bridges.torproject.org/
• Email bridges@torproject.org with "get transport obfs4" in the body

Project Structure

torminator/
├── src/
│   ├── main/
│   │   └── main.js          # Main Electron process
│   ├── preload/
│   │   └── preload.js       # Preload scripts for IPC
│   ├── renderer/
│   │   └── renderer.js      # Renderer process logic
│   ├── styles/              # Custom CSS for each theme
│   └── assets/
│       └── logo.svg         # Application logo
├── themes/                  # HTML templates for each theme
│   ├── win98/
│   ├── winxp/
│   ├── win7/
│   ├── win11/
│   ├── system6/
│   ├── macos/
│   └── adwaita/
├── tor/                     # Tor binaries and config
└── package.json

Configuration

The application stores its configuration using electron-store. Settings include:

• theme - Selected UI theme (default: win98)
• bridge - Configured WebTunnel bridge address

Configuration is automatically saved and persisted between sessions.

Technical Details

• SOCKS Port: 9050
• Control Port: 9051
• Transport: WebTunnel via lyrebird

The application generates a torrc configuration file dynamically based on your selected country and bridge settings.

Acknowledgments

• Tor Project for Tor
• 98.css for the Windows 98 theme
• XP.css for the Windows XP theme
• 7.css for the Windows 7 theme
• windows-ui for the Windows 11 theme
• System.css for the System 6 theme
• Puppertino and Photon for the macOS theme
• Adwaita Design Kit for the Adwaita theme
• The Electron.js team for the amazing framework